From 49abcf3be69b235b68a082438d1b36aea6a862a6 Mon Sep 17 00:00:00 2001 From: LiJiansheng Date: Sat, 25 Feb 2017 17:28:39 +0800 Subject: [PATCH 001/156] follow the issue #299,initialize chinese site. Signed-off-by: LiJiansheng --- _articles/best-practices.md | 275 ------------- _articles/building-community.md | 275 ------------- _articles/code-of-conduct.md | 115 ------ _articles/finding-users.md | 161 -------- _articles/getting-paid.md | 166 -------- _articles/how-to-contribute.md | 523 ------------------------- _articles/leadership-and-governance.md | 160 -------- _articles/legal.md | 161 -------- _articles/metrics.md | 125 ------ _articles/starting-a-project.md | 365 ----------------- _config.yml | 12 +- 11 files changed, 10 insertions(+), 2328 deletions(-) delete mode 100644 _articles/best-practices.md delete mode 100644 _articles/building-community.md delete mode 100644 _articles/code-of-conduct.md delete mode 100644 _articles/finding-users.md delete mode 100644 _articles/getting-paid.md delete mode 100644 _articles/how-to-contribute.md delete mode 100644 _articles/leadership-and-governance.md delete mode 100644 _articles/legal.md delete mode 100644 _articles/metrics.md delete mode 100644 _articles/starting-a-project.md diff --git a/_articles/best-practices.md b/_articles/best-practices.md deleted file mode 100644 index 09a7d2ebcb5..00000000000 --- a/_articles/best-practices.md +++ /dev/null @@ -1,275 +0,0 @@ ---- -title: Best Practices for Maintainers -description: Making your life easier as an open source maintainer, from documenting processes to leveraging your community. -class: best-practices -toc: - what-does-it-mean-to-be-a-maintainer: "What does it mean to be a maintainer?" - documenting-your-processes: "Documenting your processes" - learning-to-say-no: "Learning to say no" - leverage-your-community: "Leverage your community" - bring-in-the-robots: "Bring in the robots" - its-okay-to-hit-pause: "It’s okay to hit pause" -order: 5 -image: /assets/images/cards/best-practices.png ---- - -## What does it mean to be a maintainer? - -If you maintain an open source project that a lot of people use, you may have noticed you're coding less and responding to issues more. - -In the early stages of a project, you're experimenting with new ideas and making decisions based on what you want. As your project increases in popularity, you'll find yourself working with your users and contributors more. - -Maintaining a project requires more than code. These tasks are often unexpected, but they're just as important to a growing project. We've gathered a few ways to make your life easier, from documenting processes to leveraging your community. - -## Documenting your processes - -Writing things down is one of the most important things you can do as a maintainer. - -Documentation not only clarifies your own thinking, but it helps other people understand what you need or expect, before they even ask. - -Writing things down makes it easier to say no when something doesn't fit into your scope. It also makes it easier for people to pitch in and help. You never know who might be reading or using your project. - -Even if you don't use full paragraphs, jotting down bullet points is better than not writing at all. - -### Write down your project's vision - -Start by writing down the goals of your project. Add them to your README, or create a separate file called VISION. If there are other artifacts that could help, like a project roadmap, make those public as well. - -Having a clear, documented vision keeps you focused and helps you avoid "scope creep" from others' contributions. - -For example, @lord discovered that having a project vision helped him figure out which requests to spend time on. As a new maintainer, he regretted not sticking to his project's scope when he got his first feature request for [Slate](https://github.com/lord/slate). - - - -### Communicate your expectations - -Rules can be nerve-wracking to write down. Sometimes you might feel like you're policing other people's behavior or killing all the fun. - -Written and enforced fairly, however, good rules empower maintainers. They prevent you from getting dragged into doing things you don't want to do. - -Most people who come across your project don't know anything about you or your circumstances. They may assume you get paid to work on it, especially if it's something they regularly use and depend on. Maybe at one point you put a lot of time into your project, but now you're busy with a new job or family member. - -All of this is perfectly okay! Just make sure other people know about it. - -If maintaining your project is part-time or purely volunteered, be honest about how much time you have. This is not the same as how much time you think the project requires, or how much time others want you to spend. - -Here are a few rules that are worth writing down: - -* How a contribution is reviewed and accepted (_Do they need tests? An issue template?_) -* The types of contributions you'll accept (_Do you only want help with a certain part of your code?_) -* When it's appropriate to follow up (_ex. "You can expect a response from a maintainer within 7 days. If you haven't heard anything by then, feel free to ping the thread."_) -* How much time you spend on the project (_ex. "We only spend about 5 hours per week on this project"_) - -[Jekyll](https://github.com/jekyll/jekyll/tree/master/docs), [CocoaPods](https://github.com/CocoaPods/CocoaPods/wiki/Communication-&-Design-Rules), and [Homebrew](https://github.com/Homebrew/brew/blob/bbed7246bc5c5b7acb8c1d427d10b43e090dfd39/docs/Maintainers-Avoiding-Burnout.md) are several examples of projects with ground rules for maintainers and contributors. - -### Keep communication public - -Don't forget to document your interactions, too. Wherever you can, keep communication about your project public. If somebody tries to contact you privately to discuss a feature request or support need, politely direct them to a public communication channel, such as a mailing list or issue tracker. - -If you meet with other maintainers, or make a major decision in private, document these conversations in public, even if it's just posting your notes. - -That way, anybody who joins your community will have access to the same information as someone who's been there for years. - -## Learning to say no - -You've written things down. Ideally, everybody would read your documentation, but in reality, you'll have to remind others that this knowledge exists. - -Having everything written down, however, helps depersonalize situations when you do need to enforce your rules. - -Saying no isn't fun, but _"Your contribution doesn't match this project's criteria"_ feels less personal than _"I don't like your contribution"_. - -Saying no applies to many situations you'll come across as a maintainer: feature requests that don't fit the scope, someone derailing a discussion, doing unnecessary work for others. - -### Keep the conversation friendly - -One of the most important places you'll practice saying no is on your issue and pull request queue. As a project maintainer, you'll inevitably receive suggestions that you don't want to accept. - -Maybe the contribution changes your project's scope or doesn't match your vision. Maybe the idea is good, but the implementation is poor. - -Regardless of the reason, it is possible to tactfully handle contributions that don't meet your project's standards. - -If you receive a contribution you don't want to accept, your first reaction might be to ignore it or pretend you didn't see it. Doing so could hurt the other person's feelings and even demotivate other potential contributors in your community. - - - -Don't leave an unwanted contribution open because you feel guilty or want to be nice. Over time, your unanswered issues and PRs will make working on your project feel that much more stressful and intimidating. - -It's better to immediately close the contributions you know you don't want to accept. If your project already suffers from a large backlog, @steveklabnik has suggestions for [how to triage issues efficiently](http://words.steveklabnik.com/how-to-be-an-open-source-gardener). - -Secondly, ignoring contributions sends a negative signal to your community. Contributing to a project can be intimidating, especially if it's someone's first time. Even if you don't accept their contribution, acknowledge the person behind it and thank them for their interest. It's a big compliment! - -If you don't want to accept a contribution: - -* **Thank them** for their contribution -* **Explain why it doesn't fit** into the scope of the project, and offer clear suggestions for improvement, if you're able. Be kind, but firm. -* **Link to relevant documentation**, if you have it. If you notice repeated requests for things you don't want to accept, add them into your documentation to avoid repeating yourself. -* **Close the request** - -You shouldn't need more than 1-2 sentences to respond. For example, when a user of [celery](https://github.com/celery/celery/) reported a Windows-related error, @berkerpeksag [responded with](https://github.com/celery/celery/issues/3383): - -![celery screenshot](/assets/images/best-practices/celery.png) - -If the thought of saying no terrifies you, you're not alone. As @jessfraz [put it](https://blog.jessfraz.com/post/the-art-of-closing/): - -> I've talked to maintainers from several different open source projects, Mesos, Kubernetes, Chromium, and they all agree one of the hardest parts of being a maintainer is saying "No" to patches you don't want. - -Don't feel guilty about not wanting to accept someone's contribution. The first rule of open source, [according to](https://twitter.com/solomonstre/status/715277134978113536) @shykes: _"No is temporary, yes is forever."_ While empathizing with another person's enthusiasm is a good thing, rejecting a contribution is not the same as rejecting the person behind it. - -Ultimately, if a contribution isn't good enough, you're under no obligation to accept it. Be kind and responsive when people contribute to your project, but only accept changes that you truly believe will make your project better. The more often you practice saying no, the easier it becomes. Promise. - -### Be proactive - -To reduce the volume of unwanted contributions in the first place, explain your project's process for submitting and accepting contributions in your contributing guide. - -If you're receiving too many low-quality contributions, require that contributors do a bit of work beforehand, for example: - -* Fill out a issue or PR template/checklist -* Open an issue before submitting a PR - -If they don't follow your rules, close the issue immediately and point to your documentation. - -While this approach may feel unkind at first, being proactive is actually good for both parties. It reduces the chance that someone will put in many wasted hours of work into a pull request that you aren't going to accept. And it makes your workload easier to manage. - - - -Sometimes, when you say no, your potential contributor may get upset or criticize your decision. If their behavior becomes hostile, [take steps to defuse the situation](https://github.com/jonschlinkert/maintainers-guide-to-staying-positive#action-items) or even remove them from your community, if they're not willing to collaborate constructively. - -### Embrace mentorship - -Maybe someone in your community regularly submits contributions that don't meet your project's standards. It can be frustrating for both parties to repeatedly go through rejections. - -If you see that someone is enthusiastic about your project, but needs a bit of polish, be patient. Explain clearly in each situation why their contributions don't meet the expectations of the project. Try pointing them to an easier or less ambiguous task, like an issue marked _"good first bug,"_ to get their feet wet. If you have time, consider mentoring them through their first contribution, or find someone else in your community who might be willing to mentor them. - -## Leverage your community - -You don't have to do everything yourself. Your project's community exists for a reason! Even if you don't yet have an active contributor community, if you have a lot of users, put them to work. - -### Share the workload - -If you're looking for others to pitch in, start by asking around. - -When you see new contributors making repeated contributions, recognize their work by offering more responsibility. Document how others can grow into leadership roles if they wish. - -Encouraging others to [share ownership of the project](../building-community/#share-ownership-of-your-project) can greatly reduce your own workload, as @lmccart discovered on her project, [p5.js](https://github.com/processing/p5.js?files=1). - - - -If you need to step away from your project, either on hiatus or permanently, there's no shame in asking someone else to take over for you. - -If other people are enthusiastic about its direction, give them commit access or formally hand over control to someone else. If someone forked your project and is actively maintaining it elsewhere, consider linking to the fork from your original project. It's great that so many people want your project to live on! - -@progrium [found that](http://progrium.com/blog/2015/12/04/leadership-guilt-and-pull-requests/) documenting the vision for his project, [Dokku](https://github.com/dokku/dokku), helped those goals live on even after he stepped away from the project: - -> I wrote a wiki page describing what I wanted and why I wanted it. For some reason it came as a surprise to me that the maintainers started moving the project in that direction! Did it happen exactly how I'd do it? Not always. But it still brought the project closer to what I wrote down. - -### Let others build the solutions they need - -If a potential contributor has a different opinion on what your project should do, you may want to gently encourage them to work on their own fork. - -Forking a project doesn't have to be a bad thing. Being able to copy and modify projects is one of the best things about open source. Encouraging your community members to work on their own fork can provide the creative outlet they need, without conflicting with your project's vision. - - - -The same applies to a user who really wants a solution that you simply don't have the bandwidth to build. Offering APIs and customization hooks can help others meet their own needs, without having to modify the source directly. @orta [found that](http://artsy.github.io/blog/2016/07/03/handling-big-projects/) encouraging plugins for CocoaPods led to "some of the most interesting ideas": - -> It's almost inevitable that once a project becomes big, maintainers have to become a lot more conservative about how they introduce new code. You become good at saying "no", but a lot of people have legitimate needs. So, instead you end up converting your tool into a platform. - -## Bring in the robots - -Just as there are tasks that other people can help you with, there are also tasks that no human should ever have to do. Robots are your friend. Use them to make your life as a maintainer easier. - -### Require tests and other checks to improve the quality of your code - -One of the most important ways you can automate your project is by adding tests. - -Tests help contributors feel confident that they won't break anything. They also make it easier for you to review and accept contributions quickly. The more responsive you are, the more engaged your community can be. - -Set up automatic tests that will run on all incoming contributions, and ensure that your tests can easily be run locally by contributors. Require that all code contributions pass your tests before they can be submitted. You'll help set a minimum standard of quality for all submissions. [Required status checks](https://help.github.com/articles/about-required-status-checks/) on GitHub can help ensure no change gets merged without your tests passing. - -If you add tests, make sure to explain how they work in your CONTRIBUTING file. - - - -### Use tools to automate basic maintenance tasks - -The good news about maintaining a popular project is that other maintainers have probably faced similar issues and built a solution for it. - -There are a [variety of tools available](https://github.com/integrations) to help automate some aspects of maintenance work. A few examples: - -* [semantic-release](https://github.com/semantic-release/semantic-release) automates your releases -* [mention-bot](https://github.com/facebook/mention-bot) mentions potential reviewers for pull requests -* [Danger](https://github.com/danger/danger) helps automate code review - -For bug reports and other common contributions, GitHub has [Issue Templates and Pull Request Templates](https://github.com/blog/2111-issue-and-pull-request-templates), which you can create to streamline the communication you receive. You can also set up [email filters](https://github.com/blog/2203-email-updates-about-your-own-activity) to manage your email notifications. - -If you want to get a little more advanced, style guides and linters can standardize project contributions and make them easier to review and accept. - -However, if your standards are too complicated, they can increase the barriers to contribution. Make sure you're only adding enough rules to make everyone's lives easier. - -If you're not sure which tools to use, look at what other popular projects do, especially those in your ecosystem. For example, what does the contribution process look like for other Node modules? Using similar tools and approaches will also make your process more familiar to your target contributors. - -## It's okay to hit pause - -Open source work once brought you joy. Maybe now it's starting to make you feel avoidant or guilty. - -Perhaps you're feeling overwhelmed or a growing sense of dread when you think about your projects. And meanwhile, the issues and pull requests pile up. - -Burnout is a real and pervasive issue in open source work, especially among maintainers. As a maintainer, your happiness is a non-negotiable requirement for the survival of any open source project. - -Although it should go without saying, take a break! You shouldn't have to wait until you feel burned out to take a vacation. @brettcannon, a Python core developer, decided to take [a month-long vacation](http://www.snarky.ca/why-i-took-october-off-from-oss-volunteering) after 14 years of volunteer OSS work. - -Just like any other type of work, taking regular breaks will keep you refreshed, happy, and excited about your work. - - - -Sometimes, it can be hard to take a break from open source work when it feels like everybody needs you. People may even try to make you feel guilty for stepping away. - -Do your best to find support for your users and community while you're away from a project. If you can't find the support you need, take a break anyway. Be sure to communicate when you're not available, so people aren't confused by your lack of responsiveness. - -Taking breaks applies to more than just vacations, too. If you don't want to do open source work on weekends, or during work hours, communicate those expectations to others, so they know not to bother you. - -## Take care of yourself first! - -Maintaining a popular project requires different skills than the earlier stages of growth, but it's no less rewarding. As a maintainer, you'll practice leadership and personal skills on a level that few people get to experience. While it's not always easy to manage, setting clear boundaries and only taking on what you're comfortable with will help you stay happy, refreshed, and productive. diff --git a/_articles/building-community.md b/_articles/building-community.md deleted file mode 100644 index 73d27a2364e..00000000000 --- a/_articles/building-community.md +++ /dev/null @@ -1,275 +0,0 @@ ---- -title: Building Welcoming Communities -description: Building a community that encourages people to use, contribute to, and evangelize your project. -class: building -toc: - setting-your-project-up-for-success: "Setting your project up for success" - growing-your-community: "Growing your community" - resolving-conflicts: "Resolving conflicts" -order: 4 -image: /assets/images/cards/building.png ---- - -## Setting your project up for success - -You've launched your project, you're spreading the word, and people are checking it out. Awesome! Now, how do you get them to stick around? - -A welcoming community is an investment into your project's future and reputation. If your project is just starting to see its first contributions, start by giving early contributors a positive experience, and make it easy for them to keep coming back. - -### Make people feel welcome - -One way to think about your project's community is through what @MikeMcQuaid calls the [contributor funnel](https://speakerdeck.com/mikemcquaid/the-open-source-contributor-funnel): - -![contributor funnel](/assets/images/building-community/contributor_funnel_mikemcquaid.png) - -As you build your community, consider how someone at the top of the funnel (a potential user) might theoretically make their way to the bottom (an active maintainer). Your goal is to reduce friction at each stage of the contributor experience. When people have easy wins, they will feel incentivized to do more. - -Start with your documentation: - -* **Make it easy for someone to use your project.** [A friendly README](../starting-a-project/#writing-a-readme) and clear code examples will make it easier for anyone who lands on your project to get started. -* **Clearly explain how to contribute**, using [your CONTRIBUTING file](../starting-a-project/#writing-your-contributing-guidelines) and keeping your issues up-to-date. - -Good documentation invites people to interact with your project. Eventually, someone will open an issue or pull request. Use these interactions as opportunities to move them down the funnel. - -* **When someone new lands on your project, thank them for their interest!** It only takes one negative experience to make someone not want to come back. -* **Be responsive.** If you don't respond to their issue for a month, chances are, they've already forgotten about your project. -* **Be open-minded about the types of contributions you'll accept.** Many contributors start with a bug report or small fix. There are [many ways to contribute](../how-to-contribute/#what-it-means-to-contribute) to a project. Let people help how they want to help. -* **If there's a contribution you disagree with,** thank them for their idea and [explain why](../best-practices/#learning-to-say-no) it doesn't fit into the scope of the project, linking to relevant documentation if you have it. - - - -The majority of open source contributors are "casual contributors": people who contribute to a project only occasionally. A casual contributor may not have time to get fully up to speed with your project, so your job is to make it easy for them to contribute. - -Encouraging other contributors is an investment in yourself, too. When you empower your biggest fans to run with the work they're excited about, there's less pressure to do everything yourself. - -### Document everything - - - -When you start a new project, it may feel natural to keep your work private. But open source projects thrive when you document your process in public. - -When you write things down, more people can participate at every step of the way. You might get help on something you didn't even know you needed. - -Writing things down means more than just technical documentation. Any time you feel the urge to write something down or privately discuss your project, ask yourself whether you can make it public. - -Be transparent about your project's roadmap, the types of contributions you're looking for, how contributions are reviewed, or why you made certain decisions. - -If you notice multiple users running into the same problem, document the answers in the README. - -For meetings, consider publishing your notes or takeaways in a relevant issue. The feedback you'll get from this level of transparency may surprise you. - -Documenting everything applies to the work you do, too. If you're working on a substantial update to your project, put it into a pull request and mark it as a work in progress (WIP). That way, other people can feel involved in the process early on. - -### Be responsive - -As you [promote your project](../finding-users), people will have feedback for you. They may have questions about how things work, or need help getting started. - -Try to be responsive when someone files an issue, submits a pull request, or asks a question about your project. When you respond quickly, people will feel they are part of a dialogue, and they'll be more enthusiastic about participating. - -Even if you can't review the request immediately, acknowledging it early helps increase engagement. Here's how @tdreyno responded to a pull request on [Middleman](https://github.com/middleman/middleman/pull/1466): - -![middleman pull request](/assets/images/building-community/middleman_pr.png) - -[A Mozilla study found that](https://docs.google.com/presentation/d/1hsJLv1ieSqtXBzd5YZusY-mB8e1VJzaeOmh8Q4VeMio/edit#slide=id.g43d857af8_0177) contributors who received code reviews within 48 hours had a much higher rate of return and repeat contribution. - -Conversations about your project could also be happening in other places around the internet, such as Stack Overflow, Twitter, or Reddit. You can set up notifications in some of these places so you are alerted when someone mentions your project. - -### Give your community a place to congregate - -There are two reasons to give your community a place to congregate. - -The first reason is for them. Help people get to know each other. People with common interests will inevitably want a place to talk about it. And when communication is public and accessible, anybody can read past archives to get up to speed and participate. - -The second reason is for you. If you don't give people a public place to talk about your project, they will likely contact you directly. In the beginning, it may seem easy enough to respond to private messages "just this once". But over time, especially if your project becomes popular, you will feel exhausted. Resist the temptation to communicate with people about your project in private. Instead, direct them to a designated public channel. - -Public communication can be as simple as directing people to open an issue instead of emailing you directly or commenting on your blog. You could also set up a mailing list, or create a Twitter account, Slack, or IRC channel for people to talk about your project. Or try all of the above! - -[Kubernetes kops](https://github.com/kubernetes/kops#getting-involved) sets aside office hours every other week to help community members: - -> Kops also has time set aside every other week to offer help and guidance to the community. Kops maintainers have agreed to set aside time specifically dedicated to working with newcomers, helping with PRs, and discussing new features. - -Notable exceptions to public communication are: 1) security issues and 2) sensitive code of conduct violations. You should always have a way for people to report these issues privately. If you don't want to use your personal email, set up a dedicated email address. - -## Growing your community - -Communities are extremely powerful. That power can be a blessing or a curse, depending on how you wield it. As your project's community grows, there are ways to help it become a force of construction, not destruction. - -### Don't tolerate bad actors - -Any popular project will inevitably attract people who harm, rather than help, your community. They may start unnecessary debates, quibble over trivial features, or bully others. - -Do your best to adopt a zero-tolerance policy towards these types of people. If left unchecked, negative people will make other people in your community uncomfortable. They may even leave. - - - -Regular debates over trivial aspects of your project distracts others, including you, from focusing on important tasks. New people who arrive to your project may see these conversations and not want to participate. - -When you see negative behavior happening on your project, call it out publicly. Explain, in a kind but firm tone, why their behavior is not acceptable. If the problem persists, you may need to [ask them to leave](../code-of-conduct/#enforcing-your-code-of-conduct). Your [code of conduct](../code-of-conduct/) can be a constructive guide for these conversations. - -### Meet contributors where they're at - -Good documentation only becomes more important as your community grows. Casual contributors, who may not otherwise be familiar with your project, read your documentation to quickly get the context they need. - -In your CONTRIBUTING file, explicitly tell new contributors how to get started. You may even want to make a dedicated section for this purpose. [Django](https://github.com/django/django), for example, has a special landing page to welcome new contributors. - -![django new contributors page](/assets/images/building-community/django_new_contributors.png) - -In your issue queue, label bugs that are suitable for different types of contributors: for example, [_"first timers only"_](https://medium.com/@kentcdodds/first-timers-only-78281ea47455#.g1k01jy05), _"good first bug"_, or _"documentation"_. [These labels](https://github.com/librariesio/libraries.io/blob/6afea1a3354aef4672d9b3a9fc4cc308d60020c8/app/models/github_issue.rb#L8-L14) make it easy for someone new to your project to quickly scan your issues and get started. - -Finally, use your documentation to make people feel welcome at every step of the way. - -You will never interact with most people who land on your project. There may be contributions you didn't receive because somebody felt intimidated or didn't know where to get started. Even a few kind words can keep someone from leaving your project in frustration. - -For example, here's how [Rubinius](https://github.com/rubinius/rubinius/) starts [its contributing guide](https://github.com/rubinius/rubinius/blob/master/.github/contributing.md): - -> We want to start off by saying thank you for using Rubinius. This project is a labor of love, and we appreciate all of the users that catch bugs, make performance improvements, and help with documentation. Every contribution is meaningful, so thank you for participating. That being said, here are a few guidelines that we ask you to follow so we can successfully address your issue. - -### Share ownership of your project - - - -People are excited to contribute to projects when they feel a sense of ownership. That doesn't mean you need to turn over your project's vision or accept contributions you don't want. But the more you give credit to others, the more they'll stick around. - -See if you can find ways to share ownership with your community as much as possible. Here are some ideas: - -* **Resist fixing easy (non-critical) bugs.** Instead, use them as opportunities to recruit new contributors, or mentor someone who'd like to contribute. It may seem unnatural at first, but your investment will pay off over time. For example, @michaeljoseph asked a contributor to submit a pull request on a [Cookiecutter](https://github.com/audreyr/cookiecutter) issue below, rather than fix it himself. - -![cookiecutter issue](/assets/images/building-community/cookiecutter_submit_pr.png) - -* **Start a CONTRIBUTORS or AUTHORS file in your project** that lists everyone who's contributed to your project, like [Sinatra](https://github.com/sinatra/sinatra/blob/master/AUTHORS.md) does. - -* If you've got a sizeable community, **send out a newsletter or write a blog post** thanking contributors. Rust's [This Week in Rust](https://this-week-in-rust.org/) and Hoodie's [Shoutouts](http://hood.ie/blog/shoutouts-week-24.html) are two good examples. - -* **Give every contributor commit access.** @felixge found that this made people [more excited to polish their patches](http://felixge.de/2013/03/11/the-pull-request-hack.html), and he even found new maintainers for projects that he hadn't worked on in awhile. - -* If your project is on GitHub, **move your project from your personal account to an [Organization](https://help.github.com/articles/creating-a-new-organization-account/)** and add at least one backup admin. Organizations make it easier to work on projects with external collaborators. - -The reality is that [most projects only have](https://peerj.com/preprints/1233.pdf) one or two maintainers who do most of the work. The bigger your project, and the bigger your community, the easier it is to find help. - -While you may not always find someone to answer the call, putting a signal out there increases the chances that other people will pitch in. And the earlier you start, the sooner people can help. - - - -## Resolving conflicts - -In the early stages of your project, making major decisions is easy. When you want to do something, you just do it. - -As your project becomes more popular, more people will take interest in the decisions you make. Even if you don't have a big community of contributors, if your project has a lot of users, you'll find people weighing in on decisions or raising issues of their own. - -For the most part, if you've cultivated a friendly, respectful community and documented your processes openly, your community should be able to find resolution. But sometimes you run into an issue that's a bit harder to address. - -### Set the bar for kindness - -When your community is grappling with a difficult issue, tempers may rise. People may become angry or frustrated and take it out on one another, or on you. - -Your job as a maintainer is to keep these situations from escalating. Even if you have a strong opinion on the topic, try to take the position of a moderator or facilitator, rather than jumping into the fight and pushing your views. If someone is being unkind or monopolizing the conversation, [act immediately](../building-community/#dont-tolerate-bad-actors) to keep discussions civil and productive. - - - -Other people are looking to you for guidance. Set a good example. You can still express disappointment, unhappiness, or concern, but do so calmly. - -Keeping your cool isn't easy, but demonstrating leadership improves the health of your community. The internet thanks you. - -### Treat your README as a constitution - -Your README is [more than just a set of instructions](../starting-a-project/#writing-a-readme). It's also a place to talk about your goals, product vision, and roadmap. If people are overly focused on debating the merit of a particular feature, it may help to revisit your README and talk about the higher vision of your project. Focusing on your README also depersonalizes the conversation, so you can have a constructive discussion. - -### Focus on the journey, not the destination - -Some projects use a voting process to make major decisions. While sensible at first glance, voting emphasizes getting to an "answer," rather than listening to and addressing each other's concerns. - -Voting can become political, where community members feel pressured to do each other favors or vote a certain way. Not everybody votes, either, whether it's the [silent majority](http://ben.balter.com/2016/03/08/optimizing-for-power-users-and-edge-cases/#the-silent-majority-of-users) in your community, or current users who didn't know a vote was taking place. - -Sometimes, voting is a necessary tiebreaker. As much as you are able, however, emphasize ["consensus seeking"](https://en.wikipedia.org/wiki/Consensus-seeking_decision-making) rather than consensus. - -Under a consensus seeking process, community members discuss major concerns until they feel they have been adequately heard. When only minor concerns remain, the community moves forward. "Consensus seeking" acknowledges that a community may not be able to reach a perfect answer. Instead, it prioritizes listening and discussion. - - - -Even if you don't actually adopt a consensus seeking process, as a project maintainer, it's important that people know you are listening. Making other people feel heard, and committing to resolving their concerns, goes a long way to diffuse sensitive situations. Then, follow up on your words with actions. - -Don't rush into a decision for the sake of having a resolution. Make sure that everybody feels heard and that all information has been made public before moving toward a resolution. - -### Keep the conversation focused on action - -Discussion is important, but there is a difference between productive and unproductive conversations. - -Encourage discussion so long as it is actively moving towards resolution. If it's clear that conversation is languishing or going off-topic, jabs are getting personal, or people are quibbling about minor details, it's time to shut it down. - -Allowing these conversations to continue is not only bad for the issue at hand, but bad for the health of your community. It sends a message that these types of conversations are permitted or even encouraged, and it can discourage people from raising or resolving future issues. - -With every point made by you or by others, ask yourself, _"How does this bring us closer to a resolution?"_ - -If the conversation is starting to unravel, ask the group, _"Which steps should we take next?"_ to refocus the conversation. - -If a conversation clearly isn't going anywhere, there are no clear actions to be taken, or the appropriate action has already been taken, close the issue and explain why you closed it. - - - -### Pick your battles wisely - -Context is important. Consider who is involved in the discussion and how they represent the rest of the community. - -Is everybody in the community upset about, or even engaged with, this issue? Or is a lone troublemaker? Don't forget to consider your silent community members, not just the active voices. - -If the issue does not represent the broader needs of your community, you may just need to acknowledge the concerns of a few people. If this is a recurring issue without a clear resolution, point them to previous discussions on the topic and close the thread. - -### Identify a community tiebreaker - -With a good attitude and clear communication, most difficult situations are resolvable. However, even in a productive conversation, there can simply be a difference in opinion on how to proceed. In these cases, identify an individual or group of people that can serve as a tiebreaker. - -A tiebreaker could be the primary maintainer of the project, or it could be a small group of people who make a decision based on voting. Ideally, you've identified a tiebreaker and the associated process in a GOVERNANCE file before you ever have to use it. - -Your tiebreaker should be a last resort. Divisive issues are an opportunity for your community to grow and learn. Embrace these opportunities and use a collaborative process to move to a resolution wherever possible. - -## Community is the ❤️ of open source - -Healthy, thriving communities fuel the thousands of hours poured into open source every week. Many contributors point to other people as the reason for working - or not working - on open source. By learning how to tap into that power constructively, you'll help someone out there have an unforgettable open source experience. diff --git a/_articles/code-of-conduct.md b/_articles/code-of-conduct.md deleted file mode 100644 index afbeef202fa..00000000000 --- a/_articles/code-of-conduct.md +++ /dev/null @@ -1,115 +0,0 @@ ---- -title: Your Code of Conduct -description: Facilitate healthy and constructive community behavior by adopting and enforcing a code of conduct. -class: coc -toc: - why-do-i-need-a-code-of-conduct: "Why do I need a code of conduct?" - establishing-a-code-of-conduct: "Establishing a code of conduct" - deciding-how-youll-enforce-your-code-of-conduct: "Deciding how you’ll enforce your code of conduct" - enforcing-your-code-of-conduct: "Enforcing your code of conduct" -order: 8 -image: /assets/images/cards/coc.png ---- - -## Why do I need a code of conduct? - -A code of conduct is a document that establishes expectations for behavior for your project's participants. Adopting, and enforcing, a code of conduct can help create a positive social atmosphere for your community. - -Codes of conduct help protect not just your participants, but yourself. If you maintain a project, you may find that unproductive attitudes from other participants can make you feel drained or unhappy about your work over time. - -A code of conduct empowers you to facilitate healthy, constructive community behavior. Being proactive reduces the likelihood that you, or others, will become fatigued with your project, and helps you take action when someone does something you don't agree with. - -## Establishing a code of conduct - -Try to establish a code of conduct as early as possible: ideally, when you first create your project. - -In addition to communicating your expectations, a code of conduct describes the following: - -* Where the code of conduct takes effect _(only on issues and pull requests, or community activities like events?)_ -* Whom the code of conduct applies to _(community members and maintainers, but what about sponsors?)_ -* What happens if someone violates the code of conduct -* How someone can report violations - -Wherever you can, use prior art. The [Contributor Covenant](http://contributor-covenant.org/) is a drop-in code of conduct that is used by over 40,000 open source projects, including Kubernetes, Rails, and Swift. - -The [Django Code of Conduct](https://www.djangoproject.com/conduct/) and the [Citizen Code of Conduct](http://citizencodeofconduct.org/) are also two good code of conduct examples. - -Place a CODE_OF_CONDUCT file in your project's root directory, and link to it from your README, so it's visible to your community. - -## Deciding how you'll enforce your code of conduct - - - -You should explain how your code of conduct will be enforced **_before_** a violation occurs. There are several reasons to do so: - -* It demonstrates that you are serious about taking action when it's needed. - -* Your community will feel more reassured that complaints actually get reviewed. - -* You'll reassure your community that the review process is fair and transparent, should they ever find themselves investigated for a violation. - -You should give people a private way (such as an email address) to report a code of conduct violation and explain who receives that report. It could be a maintainer, a group of maintainers, or a code of conduct working group. - -Don't forget that someone might want to report a violation about a person who receives those reports. In this case, give them an option to report violations to someone else. For example, @ctb and @mr-c [explain on their project](https://github.com/dib-lab/khmer/blob/master/CODE_OF_CONDUCT.rst), [khmer](https://github.com/dib-lab/khmer): - -> Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by emailing **khmer-project@idyll.org** which only goes to C. Titus Brown and Michael R. Crusoe. To report an issue involving either of them please email **Judi Brown Clarke, Ph.D.** the Diversity Director at the BEACON Center for the Study of Evolution in Action, an NSF Center for Science and Technology.* - -For inspiration, check out Django's [enforcement manual](https://www.djangoproject.com/conduct/enforcement-manual/) (though you may not need something this comprehensive, depending on the size of your project). - -## Enforcing your code of conduct - -Sometimes, despite your best efforts, somebody will do something that violates this code. There are several ways to address negative or harmful behavior when it comes up. - -### Gather information about the situation - -Treat each community member's voice as important as your own. If you receive a report that someone violated the code of conduct, take it seriously and investigate the matter, even if it does not match your own experience with that person. Doing so signals to your community that you value their perspective and trust their judgment. - -The community member in question may be a repeat offender who consistently makes others feel uncomfortable, or they may have only said or done something once. Both can be grounds for taking action, depending on context. - -Before you respond, give yourself time to understand what happened. Read through the person's past comments and conversations to better understand who they are and why they might have acted in such a way. Try to gather perspectives other than your own about this person and their behavior. - - - -### Take appropriate action - -After gathering and processing sufficient information, you'll need to decide what to do. As you consider your next steps, remember that your goal as a moderator is to foster a safe, respectful, and collaborative environment. Consider not only how to deal with the situation in question, but how your response will affect the rest of your community's behavior and expectations moving forward. - -When somebody reports a code of conduct violation, it is your, not their, job to handle it. Sometimes, the reporter is disclosing information at great risk to their career, reputation, or physical safety. Forcing them to confront their harasser could put the reporter in a compromising position. You should handle direct communication with the person in question, unless the reporter explicitly requests otherwise. - -There are a few ways you might respond to a code of conduct violation: - -* **Give the person in question a public warning** and explain how their behavior negatively impacted others, preferably in the channel where it occurred. Where possible, public communication conveys to the rest of the community that you take the code of conduct seriously. Be kind, but firm in your communication. - -* **Privately reach out to the person** in question to explain how their behavior negatively impacted others. You may want to use a private communication channel if the situation involves sensitive personal information. If you communicate with someone privately, it's a good idea to CC those who first reported the situation, so they know you took action. Ask the reporting person for consent before CCing them. - -Sometimes, a resolution cannot be reached. The person in question may become aggressive or hostile when confronted or does not change their behavior. In this situation, you may want to consider taking stronger action. For example: - -* **Suspend the person** in question from the project, enforced through a temporary ban on participating in any aspect of the project - -* **Permanently ban** the person from the project - -Banning members should not be taken lightly and represents a permanent and irreconcilable difference of perspectives. You should only take these measures when it is clear that a resolution cannot be reached. - -## Your responsibilities as a maintainer - -A code of conduct is not a law that is enforced arbitrarily. You are the enforcer of the code of conduct and it's your responsibility to follow the rules that the code of conduct establishes. - -As a maintainer you establish the guidelines for your community and enforce those guidelines according to the rules set forth in your code of conduct. This means taking any report of a code of conduct violation seriously. The reporter is owed a thorough and fair review of their complaint. If you determine that the behavior that they reported is not a violation, communicate that clearly to them and explain why you're not going to take action on it. What they do with that is up to them: tolerate the behavior that they had an issue with, or stop participating in the community. - -A report of behavior that doesn't _technically_ violate the code of conduct may still indicate that there is a problem in your community, and you should investigate this potential problem and act accordingly. This may include revising your code of conduct to clarify acceptable behavior and/or talking to the person whose behavior was reported and telling them that while they did not violate the code of conduct, they are skirting the edge of what is expected and are making certain participants feel uncomfortable. - -In the end, as a maintainer, you set and enforce the standards for acceptable behavior. You have the ability to shape the community values of the project, and participants expect you to enforce those values in a fair and even-handed way. - -## Encourage the behavior you want to see in the world 🌎 - -When a project seems hostile or unwelcoming, even if it's just one person whose behavior is tolerated by others, you risk losing many more contributors, some of whom you may never even meet. It's not always easy to adopt or enforce a code of conduct, but fostering a welcoming environment will help your community grow. diff --git a/_articles/finding-users.md b/_articles/finding-users.md deleted file mode 100644 index e31f4b49584..00000000000 --- a/_articles/finding-users.md +++ /dev/null @@ -1,161 +0,0 @@ ---- -title: Finding Users For Your Project -description: Help your open source project grow by getting it in the hands of happy users. -class: finding -toc: - spreading-the-word: "Spreading the word" - figure-out-your-message: "Figure out your message" - help-people-find-and-follow-your-project: "Help people find and follow your project" - go-where-your-projects-audience-is-online: "Go where your project’s audience is (online)" - go-where-your-projects-audience-is-offline: "Go where your project’s audience is (offline)" - build-a-reputation: "Build a reputation" -order: 3 -image: /assets/images/cards/finding.png ---- - -## Spreading the word - -There's no rule that says you have to promote an open source project when you launch. There are many fulfilling reasons to work in open source that have nothing to do with popularity. If you are hoping others will find and use your open source project, however, it's time to tell everybody about your hard work! - -## Figure out your message - -Before you start the actual work of promoting your project, you should be able to explain what it does, and why it matters. - -What makes your project different or interesting? Why did you create it? Answering these questions for yourself will make it easier to convince others. - -Remember that people get involved as users, and eventually contributors, because it solves a problem for them. As you think about your project's message and value, try to view it through the lens of what _they_ might want. - -For example, @robb uses code examples to clearly communicate why his project, [Cartography](https://github.com/robb/Cartography), is useful: - -![cartography readme](/assets/images/finding-users/cartography.jpg) - -For a deeper diver into messaging, check out Mozilla's ["Personas and Pathways"](http://mozillascience.github.io/working-open-workshop/personas_pathways/) exercise for developing user personas. - -## Help people find and follow your project - - - -Help people find and remember your project by pointing them to a single namespace. - -**Have a clear handle to promote your work.** A Twitter handle, GitHub URL, or IRC channel is an easy way to point people to your project. They also give your project's growing community a place to convene. - -If you don't wish to set up these channels for your project yet, promote your own Twitter or GitHub handle in everything you do. For example, make sure it is included in your bio or slides if you speak at a meetup or event. That way, people know how to reach you or follow your work. - - - -**Consider creating a website for your project.** A website makes your project friendlier and easier to navigate, especially paired with clear documentation and tutorials. It also suggests that your project is active, which will make your audience feel more comfortable using it. Use examples to give people ideas for how to use your project. - -[@adrianholovaty](https://news.ycombinator.com/item?id=7531689), co-creator of Django, said that a website was _"by far the best thing we did with Django in the early days"_. - -If your project is hosted on GitHub, you can use [GitHub Pages](https://pages.github.com/) to easily make a website. [Yeoman](http://yeoman.io/), [Vagrant](https://www.vagrantup.com/), and [Middleman](https://middlemanapp.com/) are [a few examples](https://github.com/showcases/github-pages-examples) of excellent, comprehensive websites. - -![vagrant homepage](/assets/images/finding-users/vagrant_homepage.png) - -Now that you have a message for your project, and an easy way for people to find your project, let's get out there and talk to your audience! - -## Go where your project's audience is (online) - -Online outreach is a great way to share and spread the word quickly. Using online channels, you have the potential to reach a very wide audience. - -Take advantage of existing online communities and platforms to reach your audience. If your open source project is a software project, you can probably find your audience on [Stack Overflow](http://stackoverflow.com/), [reddit](http://www.reddit.com), [Hacker News](https://news.ycombinator.com/), or [Quora](https://www.quora.com/). Find the channels where you think people will most benefit from or be excited about your work. - - - -See if you can find ways to share your project in relevant ways: - -* **Get to know relevant open source projects and communities.** Sometimes, you don't have to directly promote your project. If your project is perfect for data scientists who use Python, get to know the Python data science community. As people get to know you, natural opportunities will arise to talk about and share your work. -* **Find people experiencing the problem that your project solves.** Search through related forums for people who fall into your project's target audience. Answer their question and find a tactful way, when appropriate, to suggest your project as a solution. -* **Ask for feedback.** Introduce yourself and your work to an audience that would find it relevant and interesting. Be specific about who you think would benefit from your project. Try to finish the sentence: _"I think my project would really help X, who are trying to do Y_". Listen and respond to others' feedback, rather than simply promoting your work. - -Generally speaking, focus on helping others before asking for things in return. Because it is easy for anybody to promote a project online, there will be a lot of noise. Give people context for who you are, not just what you want, to stand out from the crowd. - -If nobody pays attention or responds to your initial outreach, don't get discouraged! Most project launches are an iterative process that can take months or years. If you don't get a response the first time, try a different tactic, or look for ways to add value to others' work first. These things take time and dedication. - -## Go where your project's audience is (offline) - -![public speaking](/assets/images/finding-users/public_speaking.jpg) - -Offline events are a popular way to promote new projects. It's a great way to reach an engaged audience and build deeper human connections, especially if you are interested in reaching developers. - -If you're [new to public speaking](http://speaking.io/), start by finding a local meetup that's related to the language or ecosystem of your project. - - - -If you've never spoken at an event before, it's perfectly normal to feel nervous! Remember that your audience is there because they genuinely want to hear about your work. - -As you write your talk, focus on what your audience will find interesting and get value out of. Keep your language friendly and approachable. Smile, breathe, and have fun. - - - -When you feel ready, consider speaking at a conference to promote your project. Conferences can help you reach more people, sometimes from all over the world. - -Look for conferences that are specific to your language or ecosystem. Before you submit your talk, research the conference beforehand to tailor your talk to its attendees and increase your chances of getting accepted. You can often get a sense of a conference's audience by looking at its speakers. - - - -## Build a reputation - -In addition to the strategies outlined above, the best way to invite people to share and contribute to your project is to share and contribute to their projects. - -Helping newcomers, sharing resources, and making thoughtful contributions to others' work will help you build a positive reputation. Then, people will have context for your work and be more likely to pay attention and share what you're doing. - -Sometimes, these relationships can even lead to official partnerships with the wider ecosystem. - - - -It's never too early, or too late, to start building your reputation. Even if you've launched your own project already, continue looking for ways to help others. - -There is no overnight solution to building an audience. Gaining the trust and respect of others takes time, and reputation building work never ends. - - - -## Keep at it! - -Sometimes, it takes a long time before people notice your open source project. That's okay! Some of the most popular projects today took years to reach high levels of activity. Focus on building relationships instead of a magic bullet. Be patient, and keep sharing your work with those who appreciate it. diff --git a/_articles/getting-paid.md b/_articles/getting-paid.md deleted file mode 100644 index 198571ccc8f..00000000000 --- a/_articles/getting-paid.md +++ /dev/null @@ -1,166 +0,0 @@ ---- -title: Getting Paid for Open Source Work -description: Sustain your work in open source by getting financial support for your time or your project. -class: getting-paid -toc: - why-some-people-seek-financial-support: "Why some people seek financial support" - funding-your-own-time: "Funding your own time" - finding-funding-for-your-project: "Finding funding for your project" - building-a-case-for-financial-support: "Building a case for financial support" -order: 7 -image: /assets/images/cards/getting-paid.png ---- - -## Why some people seek financial support - -Much of open source work is volunteered. For example, someone might come across a bug in a project they use and submit a quick fix, or they might enjoy tinkering with an open source project in their spare time. - - - -There are many reasons why a person would not want to be paid for their open source work. - -* **They may already have a full-time job that they love,** which enables them to contribute to open source in their spare time. -* **They enjoy thinking of open source as a hobby** or creative escape and don't want to feel financially obligated to work on their projects. -* **They get other benefits from contributing to open source,** such as building their reputation or portfolio, learning a new skill, or feeling closer to a community. - - - -For others, especially when contributions are ongoing or require significant time, getting paid to contribute to open source is the only way they can participate, either because the project requires it, or for personal reasons. - -Maintaining popular projects can be a significant responsibility, taking up 10 or 20 hours per week instead of a few hours per month. - - - -Paid work also enables people from different walks of life to make meaningful contributions. Some people cannot afford to spend unpaid time on open source projects, based on their current financial position, debt, or family or other caretaking obligations. That means the world never sees contributions from talented people who can't afford to volunteer their time. This has ethical implications, as @ashedryden [has described](https://www.ashedryden.com/blog/the-ethics-of-unpaid-labor-and-the-oss-community), since work that is done is biased in favor of those who already have advantages in life, who then gain additional advantages based on their volunteer contributions, while others who are not able to volunteer then don't get later opportunities, which reinforces the current lack of diversity in the open source community. - - - -If you're looking for financial support, there are two paths to consider. You can fund your own time as a contributor, or you can find organizational funding for the project. - -## Funding your own time - -Today, many people get paid to work part- or full-time on open source. The most common way to get paid for your time is to talk to your employer. - -It's easier to make a case for open source work if your employer actually uses the project, but get creative with your pitch. Maybe your employer doesn't use the project, but they use Python, and maintaining a popular Python project help attract new Python developers. Maybe it makes your employer look more developer-friendly in general. - - - -If you don't have an existing open source project you'd like to work on, but would rather that your current work output is open sourced, make a case for your employer to open source some of their internal software. - -Many companies are developing open source programs to build their brand and recruit quality talent. - -@hueniverse, for example, found that there were financial reasons to justify [Walmart's investment in open source](https://hueniverse.com/2014/08/15/open-source-aint-charity/). And @jamesgpearce found that Facebook's open source program [made a difference](https://opensource.com/business/14/10/head-of-open-source-facebook-oscon) in recruiting: - -> It is closely aligned with our hacker culture, and how our organization was perceived. We asked our employees, "Were you aware of the open source software program at Facebook?". Two-thirds said "Yes". One-half said that the program positively contributed to their decision to work for us. These are not marginal numbers, and I hope, a trend that continues. - -If your company goes down this route, it's important to keep the boundaries between community and corporate activity clear. Ultimately, open source sustains itself through contributions from people all over the world, and that's bigger than any one company or location. - - - -If you can't convince your current employer to prioritize open source work, consider finding a new employer that encourages employee contributions to open source. Look for companies that make their dedication to open source work explicit. For example: - -* [Ghost](https://ghost.org/) is a company built around [an open source project](https://github.com/tryghost/ghost) -* [Rackspace](https://www.rackspace.com/en-us) published its [open source contribution policy](https://blog.rackspace.com/rackspaces-policy-on-contributing-to-open-source/) for employees - -Projects that originated at a large company, such as [Go](https://github.com/golang) or [React](https://github.com/facebook/react), will also likely employ people to work on open source. - -Finally, depending on your personal circumstances, you can try raising money independently to fund your open source work. For example: - -* @gaearon funded his work on [Redux](https://github.com/reactjs/redux) through a [Patreon crowdfunding campaign](http://redux.js.org/) -* @andrewgodwin funded work on Django schema migrations [through a Kickstarter campaign](https://www.kickstarter.com/projects/andrewgodwin/schema-migrations-for-django) - -## Finding funding for your project - -Beyond arrangements for individual contributors, sometimes projects raise money from companies, individuals, or others to fund ongoing work. - -Organizational funding might go towards paying current contributors, covering the costs of running the project (such as hosting fees), or investing into new features or ideas. - -A few examples of projects with organizational funding include: - -* **[webpack](https://github.com/webpack),** which raises money from companies and individuals [through OpenCollective](https://opencollective.com/webpack) -* **[Vue](https://github.com/vuejs/vue),** created by @yyx990803, which is [funded through Patreon](https://github.com/open-source/stories/yyx990803) -* **[Ruby Together](https://rubytogether.org/),** a nonprofit organization created by @indirect that pays for work on [bundler](https://github.com/bundler/bundler), [RubyGems](https://github.com/rubygems/rubygems), and other Ruby infrastructure projects - -As open source's popularity increases, finding funding for projects is still experimental. A few current options include: - -* **Raise money for your work through crowdfunding campaigns or donations.** This strategy works well if you have a strong audience or reputation already, or your project is very popular. -* **Apply for grant funding.** Some software foundations and companies offer grants for open source work, such as the [Python Software Foundation](https://www.python.org/psf/grants/), [Mozilla Foundation](https://www.mozilla.org/en-US/grants/), and [Stripe](https://stripe.com/blog/open-source-retreat-2016). -* **Raise sponsorships from companies and individual donors** through a software foundation. Or **start a business** to support the project. - -For more detailed options and case studies, @nayafia [wrote a guide](https://github.com/nayafia/lemonade-stand) to getting paid for open source work. Different types of funding require different skills, so consider your strengths to figure out which option works best for you. - -## Building a case for financial support - -Whether your project is a new idea, or has been around for years, you should expect to put significant thought into identifying your target funder and making a compelling case. - -Whether you're looking to pay for your own time, or fundraise for a project, you should be able to answer the following questions. - -### Impact - -Why is this project useful? Why do your users, or potential users, like it so much? Where will it be in five years? - -### Traction - -Try to collect evidence that your project matters, whether it's metrics, anecdotes, or testimonials. Are there any companies or noteworthy people using your project right now? If not, has a prominent person endorsed it? - -### Value to funder - -Funders, whether your employer or a grantmaking foundation, are frequently approached with opportunities. Why should they support your project over any other opportunity? How do they personally benefit? - -### Use of funds - -What, exactly, will you accomplish with the proposed funding? Focus on project milestones or outcomes rather than paying a salary. - -### How you'll receive the funds - -Does the funder have any requirements around disbursal? For example, you may need to be a nonprofit or have a nonprofit fiscal sponsor. Or perhaps the funds must be given to an individual contractor rather than an organization. These requirements vary between funders, so be sure to do your research beforehand. - - - -## Experiment and don't give up - -Raising money isn't easy, whether you're an open source project, a nonprofit, or a software startup, and in most cases require you to get creative. Identifying how you want to get paid, doing your research, and putting yourself in your funder's shoes will help you build a convincing case for funding. - -> diff --git a/_articles/how-to-contribute.md b/_articles/how-to-contribute.md deleted file mode 100644 index 24f5c7cf137..00000000000 --- a/_articles/how-to-contribute.md +++ /dev/null @@ -1,523 +0,0 @@ ---- -title: How to Contribute to Open Source -description: Want to contribute to open source? A guide to making open source contributions, for first-timers and for veterans. -class: contribute -toc: - why-contribute-to-open-source: "Why contribute to open source?" - what-it-means-to-contribute: "What it means to contribute" - orienting-yourself-to-a-new-project: "Orienting yourself to a new project" - finding-a-project-to-contribute-to: "Finding a project to contribute to" - how-to-submit-a-contribution: "How to submit a contribution" - what-happens-after-you-submit-a-contribution: "What happens after you submit a contribution" -order: 1 -image: /assets/images/cards/contribute.png ---- - -## Why contribute to open source? - - - -Contributing to open source can be a rewarding way to learn, teach, and build experience in just about any skill you can imagine. - -Why do people contribute to open source? Plenty of reasons! - -### Improve existing skills - -Whether it's coding, user interface design, graphic design, writing, or organizing, if you're looking for practice, there's a task for you on an open source project. - -### Meet people who are interested in similar things - -Open source projects with warm, welcoming communities keep people coming back for years. Many people form lifelong friendships through their participation in open source, whether it's running into each other at conferences or late night online chats about burritos. - -### Find mentors and teach others - -Working with others on a shared project means you'll have to explain how you do things, as well as ask other people for help. The acts of learning and teaching can be a fulfilling activity for everyone involved. - -### Build public artifacts that help you grow a reputation (and a career) - -By definition, all of your open source work is public, which means you get free examples to take anywhere as a demonstration of what you can do. - -### Learn people skills - -Open source offers opportunities to practice leadership and management skills, such as resolving conflicts, organizing teams of people, and prioritizing work. - -### It's empowering to be able to make changes, even small ones - -You don't have to become a lifelong contributor to enjoy participating in open source. Have you ever seen a typo on a website, and wished someone would fix it? On an open source project, you can do just that. Open source helps people feel agency over their lives and how they experience the world, and that in itself is gratifying. - -## What it means to contribute - -If you're a new open source contributor, the process can be intimidating. How do you find the right project? What if you don't know how to code? What if something goes wrong? - -Not to worry! There are all sorts of ways to get involved with an open source project, and a few tips will help you get the most out of your experience. - -### You don't have to contribute code - -A common misconception about contributing to open source is that you need to contribute code. In fact, it's often the non-code parts of a project that are [most neglected or overlooked](https://github.com/blog/2195-the-shape-of-open-source). You'll do the project a _huge_ favor by offering to pitch in with non-code contributions! - - - -Even if you are a developer, non-code contributions are a great way to get involved with a project and meet other community members. Building those relationships will give you opportunities to work on other parts of the project. - - - -### Do you like planning events? - -* Organize workshops or meetups about the project, [like @fzamperin did for NodeSchool](https://github.com/nodeschool/organizers/issues/406) -* Organize the project's conference (if they have one) -* Help community members find the right conferences and submit proposals for speaking - -### Do you like to design? - -* Restructure layouts to improve the project's usability -* Conduct user research to reorganize and refine the project's navigation or menus -* Put together a style guide to help the project have a consistent visual design -* Create art for t-shirts or a new logo, [like hapi.js's contributors did](https://github.com/hapijs/contrib/issues/68) - -### Do you like to write? - -* Write and improve the project's documentation -* Curate a folder of examples showing how the project is used -* Start a newsletter for the project, or curate highlights from the mailing list -* Write tutorials for the project, [like pypa's contributors did](https://github.com/pypa/python-packaging-user-guide/issues/194) -* Write a translation for the project's documentation - - - -### Do you like organizing? - -* Link to duplicate issues, and suggest new issue labels, to keep things organized -* Go through open issues and suggest closing old ones, [like @nzakas did for eslint](https://github.com/eslint/eslint/issues/6765) -* Ask clarifying questions on recently opened issues to move the discussion forward - -### Do you like to code? - -* Find an open issue to tackle, [like @dianjin did for Leaflet](https://github.com/Leaflet/Leaflet/issues/4528#issuecomment-216520560) -* Ask if you can help write a new feature -* Automate project setup -* Improve tooling and testing - -### Do you like helping people? - -* Answer questions about the project on e.g., Stack Overflow ([like this Postgres example](http://stackoverflow.com/questions/18664074/getting-error-peer-authentication-failed-for-user-postgres-when-trying-to-ge)) or reddit -* Answer questions for people on open issues -* Help moderate the discussion boards or conversation channels - -### Do you like helping others code? - -* Review code on other people's submissions -* Write tutorials for how a project can be used -* Offer to mentor another contributor, [like @ereichert did for @bronzdoc on Rust](https://github.com/rust-lang/book/issues/123#issuecomment-238049666) - -### You don't just have to work on software projects! - -While "open source" often refers to software, you can collaborate on just about anything. There are books, recipes, lists, and classes that get developed as open source projects. - -For example: - -* @sindresorhus curates a [list of "awesome" lists](https://github.com/sindresorhus/awesome) -* @h5bp maintains a [list of potential interview questions](https://github.com/h5bp/Front-end-Developer-Interview-Questions) for front-end developer candidates -* @stuartlynn and @nicole-a-tesla made a [collection of fun facts about puffins](https://github.com/stuartlynn/puffin_facts) - -Even if you're a software developer, working on a documentation project can help you get started in open source. It's often less intimidating to work on projects that don't involve code, and the process of collaboration will build your confidence and experience. - -## Orienting yourself to a new project - - - -For anything more than a typo fix, contributing to open source is like walking up to a group of strangers at a party. If you start talking about llamas, while they were deep in a discussion about goldfish, they'll probably look at you a little strangely. - -Before jumping in blindly with your own suggestions, start by learning how to read the room. Doing so increases the chances that your ideas will be noticed and heard. - -### Anatomy of an open source project - -Every open source community is different. - -Spending years on one open source project means you've gotten to know one open source project. Move to a different project, and you might find the vocabulary, norms, and communication styles are completely different. - -That said, many open source projects follow a similar organizational structure. Understanding the different community roles and overall process will help you get quickly oriented to any new project. - -A typical open source project has the following types of people: - -* **Author:** The person/s or organization that created the project -* **Owner:** The person/s who has administrative ownership over the organization or repository (not always the same as the original author) -* **Maintainers:** Contributors who are responsible for driving the vision and managing the organizational aspects of the project. (They may also be authors or owners of the project.) -* **Contributors:** Everyone who has contributed something back to the project. -* **Community Members:** People who use the project. They might be active in conversations or express their opinion on the project's direction. - -Bigger projects may also have subcommittees or working groups focused on different tasks, such as tooling, triage, community moderation, and event organizing. Look on a project's website for a "team" page, or in the repository for governance documentation, to find this information. - -A project also has documentation. These files are usually listed in the top level of a repository. - -* **LICENSE:** By definition, every open source project must have an [open source license](https://choosealicense.com). If the project does not have a license, it is not open source. -* **README:** The README is the instruction manual that welcomes new community members to the project. It explains why the project is useful and how to get started. -* **CONTRIBUTING:** Whereas READMES help people _use_ the project, contributing docs help people _contribute_ to the project. It explains what types of contributions are needed and how the process works. While not every project has a CONTRIBUTING file, its presence signals that this is a welcoming project to contribute to. -* **CODE_OF_CONDUCT:** The code of conduct sets ground rules for participants' behavior associated and helps to facilitate a friendly, welcoming environment. While not every project has a CODE_OF_CONDUCT file, its presence signals that this is a welcoming project to contribute to. -* **Other documentation:** There might be additional documentation, such as tutorials, walkthroughs, or governance policies, especially on bigger projects. - -Finally, open source projects use the following tools to organize discussion. Reading through the archives will give you a good picture of how the community thinks and works. - -* **Issue tracker:** Where people discuss issues related to the project. -* **Pull requests:** Where people discuss and review changes that are in progress. -* **Discussion forums or mailing lists:** Some projects may use these channels for conversational topics (ex. _"How do I..."_ or _"What do you think about..."_ instead of bug reports or feature requests). Others use the issue tracker for all conversations. -* **Synchronous chat channel:** Some projects use chat channels (such as Slack or IRC) for casual conversation, collaboration, and quick exchanges. - -## Finding a project to contribute to - -Now that you've figured out how open source projects work, it's time to find a project to contribute to! - -If you've never contributed to open source before, take some advice from U.S. President John F. Kennedy, who once said, _"Ask not what your country can do for you - ask what you can do for your country."_ - -Contributing to open source happens at all levels, across projects. You don't need to overthink what exactly your first contribution will be, or how it will look. - -Instead, start by thinking about the projects you already use, or want to use. The projects you'll actively contribute to are the ones you find yourself coming back to. - -Within those projects, whenever you catch yourself thinking that something could be better or different, act on your instinct. - -Open source isn't an exclusive club; it's made by people just like you. "Open source" is just a fancy term for treating the world's problems as fixable. - -You might scan a README and find a broken link or a typo. Or you're a new user and you noticed something is broken, or an issue that you think should really be in the documentation. Instead of ignoring it and moving on, or asking someone else to fix it, see whether you can help out by pitching in. That's what open source is all about! - -> [28% of casual contributions](http://www.igor.pro.br/publica/papers/saner2016.pdf) to open source are documentation, such as a typo fix, reformatting, or writing a translation. - -You can also use one of the following resources to help you discover new projects: - -* [GitHub Explore](https://github.com/explore/) -* [First Timers Only](http://www.firsttimersonly.com/) -* [Your First PR](https://yourfirstpr.github.io/) -* [CodeTriage](https://www.codetriage.com/) -* [24 Pull Requests](https://24pullrequests.com/) -* [Up For Grabs](http://up-for-grabs.net/) -* [Contributor-ninja](https://contributor.ninja) - -### A checklist before you contribute - -When you've found a project you'd like to contribute to, do a quick scan to make sure that the project is suitable for accepting contributions. Otherwise, your hard work may never get a response. - -Here's a handy checklist to evaluate whether a project is good for new contributors. - -**Meets the definition of open source** - -
- - -
- -**Project actively accepts contributions** - -Look at the commit activity on the master branch. On GitHub, you can see this information on a repository's homepage. - -
- - -
- -
- - -
- -
- - -
- -Next, look at the project's issues. - -
- - -
- -
- - -
- -
- - -
- -
- - -
- -
- - -
- -Now do the same for the project's pull requests. - -
- - -
- -
- - -
- -
- - -
- -
- - -
- -
- - -
- -**Project is welcoming** - -A project that is friendly and welcoming signals that they will be receptive to new contributors. - -
- - -
- -
- - -
- -
- - -
- -
- - -
- - - -## How to submit a contribution - -You've found a project you like, and you're ready to make a contribution. Finally! Here's how to get your contribution in the right way. - -### Communicating effectively - -Whether you're a one-time contributor or trying to join a community, working with others is one of the most important skills you'll develop in open source. - - - -Before you open an issue or pull request, or ask a question in chat, keep these points in mind to help your ideas come across effectively. - -**Give context.** Help others get quickly up to speed. If you're running into an error, explain what you're trying to do and how to reproduce it. If you're suggesting a new idea, explain why you think it'd be useful to the project (not just to you!). - -> 😇 _"X doesn't happen when I do Y"_ -> -> 😢 _"X is broken! Please fix it."_ - -**Do your homework beforehand.** It's ok not to know things, but show that you tried. Before asking for help, be sure to check a project's README, documentation, issues (open or closed), mailing list, and search the internet for an answer. People will appreciate when you demonstrate that you're trying to learn. - -> 😇 _"I'm not sure how to implement X. I checked the help docs and didn't find any mentions."_ -> -> 😢 _"How do I X?"_ - -**Keep requests short and direct.** Much like sending an email, every contribution, no matter how simple or helpful, requires someone else's review. Many projects have more incoming requests than people available to help. Be concise. You will increase the chance that someone will be able to help you. - -> 😇 _"I'd like to write an API tutorial."_ -> -> 😢 _"I was driving down the highway the other day and stopped for gas, and then I had this amazing idea for something we should be doing, but before I explain that, let me show you..."_ - -**Keep all communication public.** Although it's tempting, don't reach out to maintainers privately unless you need to share sensitive information (such as a security issue or serious conduct violation). When you keep the conversation public, more people can learn and benefit from your exchange. Discussions can be, in themselves, contributions. - -> 😇 _(as a comment) "@-maintainer Hi there! How should we proceed on this PR?"_ -> -> 😢 _(as an email) "Hey there, sorry to bother you over email, but I was wondering if you've had a chance to review my PR"_ - -**It's okay to ask questions (but be patient!).** Everybody was new to the project at some point, and even experienced contributors need to get up to speed when they look at a new project. By the same token, even longtime maintainers are not always familiar with every part of the project. Show them the same patience that you'd want them to show to you. - -> 😇 _"Thanks for looking into this error. I followed your suggestions. Here's the output."_ -> -> 😢 _"Why can't you fix my problem? Isn't this your project?"_ - -**Respect community decisions.** Your ideas may differ from the community's priorities or vision. They may offer feedback or decide not to pursue your idea. While you should discuss and look for compromise, maintainers have to live with your decision longer than you will. If you disagree with their direction, you can always work on your own fork or start your own project. - -> 😇 _"I'm disappointed you can't support my use case, but as you've explained it only affects a minor portion of users, I understand why. Thanks for listening."_ -> -> 😢 _"Why won't you support my use case? This is unacceptable!"_ - -**Above all, keep it classy.** Open source is made up of collaborators from all over the world. Context gets lost across languages, cultures, geographies, and time zones. In addition, written communication makes it harder to convey a tone or mood. Assume good intentions in these conversations. It's fine to politely push back on an idea, ask for more context, or further clarify your position. Just try to leave the internet a better place than when you found it. - -### Gathering context - -Before doing anything, do a quick check to make sure your idea hasn't been discussed elsewhere. Skim the project's README, issues (open and closed), mailing list, and Stack Overflow. You don't have to spend hours going through everything, but a quick search for a few key terms goes a long way. - -If you can't find your idea elsewhere, you're ready to make a move. If the project is on GitHub, you'll likely communicate by opening an issue or pull request: - -* **Issues** are like starting a conversation or discussion -* **Pull requests** are for starting work on a solution -* **For lightweight communication,** such as a clarifying or how-to question, try asking on Stack Overflow, IRC, Slack, or other chat channels, if the project has one - -Before you open an issue or pull request, check the project's contributing docs (usually a file called CONTRIBUTING, or in the README), to see whether you need to include anything specific. For example, they may ask that you follow a template, or require that you use tests. - -If you want to make a substantial contribution, open an issue to ask before working on it. It's helpful to watch the project for awhile (on GitHub, [you can click "Watch"](https://help.github.com/articles/watching-repositories/) to be notified of all conversations), and get to know community members, before doing work that might not get accepted. - - - -### Opening an issue - -You should usually open an issue in the following situations: - -* Report an error you can't solve yourself -* Discuss a high-level topic or idea (ex. community, vision, policies) -* Propose a new feature or other project idea - -Tips for communicating on issues: - -* **If you see an open issue that you want to tackle,** comment on the issue to let people know you're on it. That way, people are less likely to duplicate your work. -* **If an issue was opened awhile ago,** it's possible that it's being addressed somewhere else, or has already been resolved, so comment to ask for confirmation before starting work. -* **If you opened an issue, but figured out the answer later on your own,** comment on the issue to let people know, then close the issue. Even documenting that outcome is a contribution to the project. - -### Opening a pull request - -You should usually open a pull request in the following situations: - -* Submit trivial fixes (ex. a typo, broken link, or obvious error) -* Start work on a contribution that was already asked for, or that you've already discussed, in an issue - -A pull request doesn't have to represent finished work. It's usually better to open a pull request early on, so others can watch or give feedback on your progress. Just mark it as a "WIP" (Work in Progress) in the subject line. You can always add more commits later. - -If the project is on GitHub, here's how to submit a pull request: - -* **[Fork the repository](https://guides.github.com/activities/forking/)** and clone it locally. Connect your local to the original "upstream" repository by adding it as a remote. Pull in changes from "upstream" often so that you stay up to date so that when you submit your pull request, merge conflicts will be less likely. (See more detailed instructions [here](https://help.github.com/articles/syncing-a-fork/).) -* **[Create a branch](https://guides.github.com/introduction/flow/)** for your edits. -* **Reference any relevant issues** or supporting documentation in your PR (ex. "Closes #37.") -* **Include screenshots of the before and after** if your changes include differences in HTML/CSS. Drag and drop the images into the body of your pull request. -* **Test your changes!** Run your changes against any existing tests if they exist and create new ones when needed. Whether tests exist or not, make sure your changes don't break the existing project. -* **Contribute in the style of the project** to the best of your abilities. This may mean using indents, semi-colons or comments differently than you would in your own repository, but makes it easier for the maintainer to merge, others to understand and maintain in the future. - -If this is your first pull request, check out [Make a Pull Request](http://makeapullrequest.com/), which @kentcdodds created as a free walkthrough resource. - -## What happens after you submit a contribution - -You did it! Congratulations on becoming an open source contributor. We hope it's the first of many. - -After you submit a contribution, one of the following will happen: - -### 😭 You don't get a response. - -Hopefully you [checked the project for signs of activity](#a-checklist-before-you-contribute) before making a contribution. Even on an active project, however, it's possible that your contribution won't get a response. - -If you haven't gotten a response in over a week, it's fair to politely respond in that same thread, asking someone for a review. If you know the name of the right person to review your contribution, you can @-mention them in that thread. - -**Don't** reach out to that person privately; remember that public communication is vital to open source projects. - -If you make a polite bump and still nobody responds, it's possible that nobody will respond, ever. It's not a great feeling, but don't let that discourage you. It's happened to everyone! There are many possible reasons why you didn't get a response, including personal circumstances that may be out of your control. Try to find another project or way to contribute. If anything, this is a good reason not to invest too much time in making a contribution before other community members are engaged and responsive. - -### 🚧 Someone requests changes to your contribution. - -It's common that you'll be asked to make changes to your contribution, whether that's feedback on the scope of your idea, or changes to your code. - -When someone requests changes, be responsive. They've taken the time to review your contribution. Opening a PR and walking away is bad form. If you don't know how to make changes, research the problem, then ask for help if you need it. - -If you don't have time to work on the issue anymore (for example, if the conversation has been going on for months, and your circumstances have changed), let the maintainer know so they're not expecting a response. Someone else may be happy to take over. - -### 👎 Your contribution doesn't get accepted. - -Your contribution may or may not be accepted in the end. Hopefully you didn't put too much work into it already. If you're not sure why it wasn't accepted, it's perfectly reasonable to ask the maintainer for feedback and clarification. Ultimately, however, you'll need to respect that this is their decision. Don't argue or get hostile. You're always welcome to fork and work on your own version if you disagree! - -### 🎉 Your contribution gets accepted. - -Hooray! You've successfully made an open source contribution! - -## You did it! - -Whether you just made your first open source contribution, or you're looking for new ways to contribute, we hope you're inspired to take action. Even if your contribution wasn't accepted, don't forget to say thanks when a maintainer put effort into helping you. Open source is made by people like you: one issue, pull request, comment, or high-five at a time. diff --git a/_articles/leadership-and-governance.md b/_articles/leadership-and-governance.md deleted file mode 100644 index 61205a1a70a..00000000000 --- a/_articles/leadership-and-governance.md +++ /dev/null @@ -1,160 +0,0 @@ ---- -title: Leadership and Governance -description: Growing open source projects can benefit from formal rules for making decisions. -class: leadership -toc: - what-are-examples-of-formal-roles-used-in-open-source-projects: "What are examples of formal roles used in open source projects?" - how-do-i-formalize-these-leadership-roles: "How do I formalize these leadership roles?" - when-should-i-give-someone-commit-access: "When should I give someone commit access?" - what-are-some-of-the-common-governance-structures-for-open-source-projects: "What are some of the common governance structures for open source projects?" - do-i-need-governance-docs-when-i-launch-my-project: "Do I need governance docs when I launch my project?" - what-happens-if-corporate-employees-start-submitting-contributions: "What happens if corporate employees start submitting contributions?" - do-i-need-a-legal-entity-to-support-my-project: "Do I need a legal entity to support my project?" -order: 6 -image: /assets/images/cards/leadership.png ---- - -## Understanding governance for your growing project - -Your project is growing, people are engaged, and you're committed to keeping this thing going. At this stage, you may be wondering how to incorporate regular project contributors into your workflow, whether it's giving someone commit access or resolving community debates. If you have questions, we've got answers. - -## What are examples of formal roles used in open source projects? - -Many projects follow a similar structure for contributor roles and recognition. - -What these roles actually mean, though, is entirely up to you. Here are a few types of roles you may recognize: - -* **Maintainer** -* **Contributor** -* **Committer** - -**For some projects, "maintainers"** are the only people in a project with commit access. In other projects, they're simply the people who are listed in the README as maintainers. - -A maintainer doesn't necessarily have to be someone who writes code for your project. It could be someone who's done a lot of work evangelizing your project, or written documentation that made the project more accessible to others. Regardless of what they do day-to-day, a maintainer is probably someone who feels responsibility over the direction of the project and is committed to improving it. - -**A "contributor" could be anyone** who comments on an issue or pull request, people who add value to the project (whether it's triaging issues, writing code, or organizing events), or anybody with a merged pull request (perhaps the narrowest definition of a contributor). - - - -**The term "committer"** might be used to distinguish commit access, which is a specific type of responsibility, from other forms of contribution. - -While you can define your project roles any way you'd like, [consider using broader definitions](../how-to-contribute/#what-it-means-to-contribute) to encourage more forms of contribution. You can use leadership roles to formally recognize people who have made outstanding contributions to your project, regardless of their technical skill. - - - -## How do I formalize these leadership roles? - -Formalizing your leadership roles helps people feel ownership and tells other community members who to look to for help. - -For a smaller project, designating leaders can be as simple as adding their names to your README or a CONTRIBUTORS text file. - -For a bigger project, if you have a website, create a team page or list your project leaders there. For example, [PostgreSQL](https://github.com/postgres/postgres/) has a [comprehensive team page](https://www.postgresql.org/community/contributors/) with short profiles for each contributor. - -If your project has a very active contributor community, you might form a "core team" of maintainers, or even subcommittees of people who take ownership of different issue areas (ex. security, issue triaging, or community conduct). Let people self-organize and volunteer for the roles they're most excited about, rather than assigning them. - - - -Leadership teams may want to create a designated channel (like on IRC) or meet regularly to discuss the project (like on Gitter or Google Hangout). You can even make those meetings public so other people can listen. [Cucumber-ruby](https://github.com/cucumber/cucumber-ruby), for example, [hosts office hours every week](https://github.com/cucumber/cucumber-ruby/blob/master/CONTRIBUTING.md#talking-with-other-devs). - -Once you've established leadership roles, don't forget to document how people can attain them! Establish a clear process for how someone can become a maintainer or join a subcommittee in your project, and write it into your GOVERNANCE.md. - -Tools like [Vossibility](https://github.com/icecrime/vossibility-stack) can help you publicly track who is (or isn't) making contributions to the project. Documenting this information avoids the community perception that maintainers are a clique that makes its decisions privately. - -Finally, if your project is on GitHub, consider moving your project from your personal account to an Organization and adding at least one backup admin. [GitHub Organizations](https://help.github.com/articles/creating-a-new-organization-account/) make it easier to manage permissions and multiple repositories and protect your project's legacy through [shared ownership](../building-community/#share-ownership-of-your-project). - -## When should I give someone commit access? - -Some people think you should give commit access to everybody who makes a contribution. Doing so could encourage more people to feel ownership of your project. - -On the other hand, especially for bigger, more complex projects, you may want to only give commit access to people who have demonstrated their commitment. There's no one right way of doing it - do what makes you most comfortable! - -If your project is on GitHub, you can use [protected branches](https://help.github.com/articles/about-protected-branches/) to manage who can push to a particular branch, and under which circumstances. - - - -## What are some of the common governance structures for open source projects? - -There are three common governance structures associated with open source projects. - -* **BDFL:** BDFL stands for "Benevolent Dictator for Life". Under this structure, one person (usually the initial author of the project) has final say on all major project decisions. [Python](https://github.com/python) is a classic example. Smaller projects are probably BDFL by default, because there are only one or two maintainers. A project that originated at a company might also fall into the BDFL category. - -* **Meritocracy:** **(Note: the term "meritocracy" carries negative connotations for some communities and has a [complex social and political history](http://geekfeminism.wikia.com/wiki/Meritocracy).)** Under a meritocracy, active project contributors (those who demonstrate "merit") are given a formal decision making role. Decisions are usually made based on pure voting consensus. The meritocracy concept was pioneered by the [Apache Foundation](http://www.apache.org/); [all Apache projects](http://www.apache.org/index.html#projects-list) are meritocracies. Contributions can only be made by individuals representing themselves, not by a company. - -* **Liberal contribution:** Under a liberal contribution model, the people who do the most work are recognized as most influential, but this is based on current work and not historic contributions. Major project decisions are made based on a consensus seeking process (discuss major grievances) rather than pure vote, and strive to include as many community perspectives as possible. Popular examples of projects that use a liberal contribution model include [Node.js](https://nodejs.org/en/foundation/) and [Rust](https://www.rust-lang.org/en-US/). - -Which one should you use? It's up to you! Every model has advantages and tradeoffs. And although they may seem quite different at first, all three models have more in common than they seem. If you're interested in adopting one of these models, check out these templates: - -* [BDFL model template](http://oss-watch.ac.uk/resources/benevolentdictatorgovernancemodel) -* [Meritocracy model template](http://oss-watch.ac.uk/resources/meritocraticgovernancemodel) -* [Node.js's liberal contribution policy](https://medium.com/the-javascript-collection/healthy-open-source-967fa8be7951#.m9ht26e79) - -## Do I need governance docs when I launch my project? - -There is no right time to write down your project's governance, but it's much easier to define once you've seen your community dynamics play out. The best (and hardest) part about open source governance is that it is shaped by the community! - -Some early documentation will inevitably contribute to your project's governance, however, so start writing down what you can. For example, you can define clear expectations for behavior, or how your contributor process works, even at your project's launch. - -If you're part of a company launching an open source project, it's worth having an internal discussion before launch about how your company expects to maintain and make decisions about the project moving forward. You may also want to publicly explain anything particular to how your company will (or won't!) be involved with the project. - - - -## What happens if corporate employees start submitting contributions? - -Successful open source projects get used by many people and companies, and some companies may eventually have revenue streams eventually tied to the project. For example, a company may use the project's code as one component in a commercial service offering. - -As the project gets more widely used, people who have expertise in it become more in-demand - you may be one of them! - and will sometimes get paid for work they do in the project. - -It's important to treat commercial activity as normal and as just another source of development energy. Paid developers shouldn't get special treatment over unpaid ones, of course; each contribution must be evaluated on its technical merits. However, people should feel comfortable engaging in commercial activity, and feel comfortable stating their use cases when arguing in favor of a particular enhancement or feature. - -"Commercial" is completely compatible with "open source". "Commercial" just means there is money involved somewhere - that the software is used in commerce, which is increasingly likely as a project gains adoption. (When open source software is used as part of a non-open-source product, the overall product is still "proprietary" software, though, like open source, it might be used for commercial or non-commercial purposes.) - -Like anyone else, commercially-motivated developers gain influence in the project through the quality and quantity of their contributions. Obviously, a developer who is paid for her time may be able to do more than someone who is not paid, but that's okay: payment is just one of many possible factors that could affect how much someone does. Keep your project discussions focused on the contributions, not on the external factors that enable people to make those contributions. - -## Do I need a legal entity to support my project? - -You don't need a legal entity to support your open source project unless you're handling money. - -For example, if you want to create a commercial business, you'll want to set up a C Corp or LLC (if you're based in the US). If you're just doing contract work related to your open source project, you can accept money as a sole proprietor, or set up an LLC (if you're based in the US). - -If you want to accept donations for your open source project, you can set up a donation button (using PayPal or Stripe, for example), but the money won't be tax-deductible unless you are a qualifying nonprofit (a 501c3, if you're in the US). - -Many projects don't wish to go through the trouble of setting up a nonprofit, so they find a nonprofit fiscal sponsor instead. A fiscal sponsor accepts donations on your behalf, usually in exchange for a percentage of the donation. [Software Freedom Conservancy](https://sfconservancy.org/), [Apache Foundation](http://www.apache.org/), [Eclipse Foundation](https://eclipse.org/org/foundation/), [Linux Foundation](https://www.linuxfoundation.org/projects) and [Open Collective](https://opencollective.com/opensource) are examples of organizations that serve as fiscal sponsors for open source projects. - - - -If your project is closely associated with a certain language or ecosystem, there may also be a related software foundation you can work with. For example, the [Python Software Foundation](https://www.python.org/psf/) helps support [PyPI](https://pypi.python.org/pypi), the Python package manager, and the [Node.js Foundation](https://nodejs.org/en/foundation/) helps support [Express.js](http://expressjs.com/), a Node-based framework. diff --git a/_articles/legal.md b/_articles/legal.md deleted file mode 100644 index c0c761b6149..00000000000 --- a/_articles/legal.md +++ /dev/null @@ -1,161 +0,0 @@ ---- -title: The Legal Side of Open Source -description: Everything you've ever wondered about the legal side of open source, and a few things you didn't. -class: legal -toc: - why-do-people-care-so-much-about-the-legal-side-of-open-source: "Why do people care so much about the legal side of open source?" - are-public-github-projects-open-source: "Are public GitHub projects open source?" - just-give-me-the-tldr-on-what-i-need-to-protect-my-project: "Just give me the TL;DR on what I need to protect my project" - which-open-source-license-is-appropriate-for-my-project: "Which open source license is appropriate for my project?" - what-if-i-want-to-change-the-license-of-my-project: "What if I want to change the license of my project?" - does-my-project-need-an-additional-contributor-agreement: "Does my project need an additional contributor agreement?" - what-does-my-companys-legal-team-need-to-know: "What does my company’s legal team need to know?" -order: 10 -image: /assets/images/cards/legal.png ---- - -## Understanding the legal implications of open source - -Sharing your creative work with the world can be an exciting and rewarding experience. It can also mean a bunch of legal things you didn't know you had to worry about. Thankfully, you don't have to start from scratch. We've got your legal needs covered. (Before you dig in, be sure to read our [disclaimer](../notices/).) - -## Why do people care so much about the legal side of open source? - -Glad you asked! When you make a creative work (such as writing, graphics, or code), that work is under exclusive copyright by default. That is, the law assumes that as the author of your work, you have a say in what others can do with it. - -In general, that means nobody else can use, copy, distribute, or modify your work without being at risk of take-downs, shake-downs, or litigation. - -Open source is an unusual circumstance, however, because the author expects that others will use, modify, and share the work. But because the legal default is still exclusive copyright, you need a license that explicitly states these permissions. - -If you don't apply an open source license, everybody who contributes to your project also becomes an exclusive copyright holder of their work. That means nobody can use, copy, distribute, or modify their contributions -- and that "nobody" includes you. - -Finally, your project may have dependencies with license requirements that you weren't aware of. Your project's community, or your employer's policies, may also require your project to use specific open source licenses. We'll cover these situations below. - -## Are public GitHub projects open source? - -When you [create a new project](https://help.github.com/articles/creating-a-new-repository/) on GitHub, you have the option to make the repository **private** or **public**. - -![create repository](/assets/images/legal/repo-create-name.png) - -**Making your GitHub project public is not the same as licensing your project.** Public projects are covered by [GitHub's Terms of Service](https://help.github.com/articles/github-terms-of-service/#f-copyright-and-content-ownership), which allows others to view and fork your project, but your work otherwise comes with no permissions. - -If you want others to use, copy, modify, or contribute back to your project, you need to include an open source license. For example, someone cannot legally use any part of your GitHub project in their code, even if it's public, unless you explicitly give them the right to do so. - -## Just give me the TL;DR on what I need to protect my project. - -You're in luck, because today, open source licenses are standardized and easy to use. You can copy-paste an existing license directly into your project. - -[MIT](https://choosealicense.com/licenses/mit/), [Apache 2.0](https://choosealicense.com/licenses/apache-2.0/), and [GPLv3](https://choosealicense.com/licenses/gpl-3.0/) are the most popular open source licenses, but there are other options to choose from. You can find the full text of these licenses, and instructions on how to use them, on [choosealicense.com](https://choosealicense.com/). - -When you create a new project on GitHub, you'll be [asked to add a license](https://help.github.com/articles/open-source-licensing/). - - - -## Which open source license is appropriate for my project? - -If you're starting from a blank slate, it's hard to go wrong with the [MIT License](https://choosealicense.com/licenses/mit/). It's short, very easy to understand, and allows anyone to do anything so long as they keep a copy of the license, including your copyright notice. You'll be able to release the project under a different license if you ever need to. - -Otherwise, picking the right open source license for your project depends on your objectives. - -Your project very likely has (or will have) **dependencies**. For example, if you're open sourcing a Node.js project, you'll probably use libraries from the Node Package Manager (npm). Each of those libraries you depend on will have its own open source license. If each of their licenses is "permissive" (gives the public permission to use, modify, and share, without any condition for downstream licensing), you can use any license you want. Common permissive licenses include MIT, Apache 2.0, ISC, and BSD. - -On the other hand, if any of your dependencies' licenses are "strong copyleft" (also gives public same permissions, subject to condition of using the same license downstream), then your project will have to use the same license. Common strong copyleft licenses include GPLv2, GPLv3, and AGPLv3. - -You may also want to consider the **communities** you hope will use and contribute to your project: - -* **Do you want your project to be used as a dependency by other projects?** Probably best to use the most popular license in your relevant community. For example, [MIT](https://choosealicense.com/licenses/mit/) is the most popular license for [npm libraries](https://libraries.io/npm). -* **Do you want your project to appeal to large businesses?** A large business will likely want an express patent license from all contributors. In this case, [Apache 2.0](https://choosealicense.com/licenses/apache-2.0/) has you (and them) covered. -* **Do you want your project to appeal to contributors who do not want their contributions to be used in closed source software?** [GPLv3](https://choosealicense.com/licenses/gpl-3.0/) or (if they also do not wish to contribute to closed source services) [AGPLv3](https://choosealicense.com/licenses/agpl-3.0/) will go over well. - -Your **company** may have specific licensing requirements for its open source projects. For example, it may require a permissive license so that the company can use your project in the company's closed source product. Or your company may require a strong copyleft license and an additional contributor agreement (see below) so that only your company, and nobody else, can use your project in closed source software. Or your company may have certain needs related to standards, social responsibility, or transparency, any of which could require a particular licensing strategy. Talk to your [company's legal department](#what-does-my-companys-legal-team-need-to-know). - -When you create a new project on GitHub, you are given the option to select a license. Including one of the licenses mentioned above will make your GitHub project open source. If you'd like to see other options, check out [choosealicense.com](https://choosealicense.com) to find the right license for your project, even if it [isn't software](https://choosealicense.com/non-software/). - -## What if I want to change the license of my project? - -Most projects never need to change licenses. But occasionally circumstances change. - -For example, as your project grows it adds dependencies or users, or your company changes strategies, any of which could require or want a different license. Also, if you neglected to license your project from the start, adding a license is effectively the same as changing licenses. There are three fundamental things to consider when adding or changing a your project's license: - -**It's complicated.** Determining license compatibility and compliance and who holds copyright can get complicated and confusing very quickly. Switching to a new but compatible license for new releases and contributions is different from relicensing all existing contributions. Involve your legal team the first hint of any desire to change licenses. Even if you have or can obtain permission from your project's copyright holders for a license change, consider the impact of the change on your project's other users and contributors. Think of a license change as a "governance event" for your project that will more likely go smoothly with clear communications and consultation with your project's stakeholders. All the more reason to choose and use an appropriate license for your project from its inception! - -**Your project's existing license.** If your project's existing license is compatible with the license you want to change to, you could just start using the new license. That's because if license A is compatible with license B, you'll comply with the terms of A while complying with the terms of B (but not necessarily vice versa). So if you're currently using a permissive license (e.g., MIT), you could change to a license with more conditions, so long as you retain a copy of the MIT license and any associated copyright notices (i.e., continue to comply with the MIT license's minimal conditions). But if your current license is not permissive (e.g., copyleft, or you don't have a license) and you aren't the sole copyright holder, you couldn't just change your project's license to MIT. Essentially, with a permissive license the project's copyright holders have given permission in advance to change licenses. - -**Your project's existing copyright holders.** If you're the sole contributor to your project then either you or your company is the project's sole copyright holder. You can add or change to whatever license you or your company wants to. Otherwise there may be other copyright holders that you need agreement from in order to change licenses. Who are they? People who have commits in your project is a good place to start. But in some cases copyright will be held by those people's employers. In some cases people will have only made _de minimis_ contributions, but there's no hard and fast rule that contributions under some number of lines of code are not subject to copyright. What to do? It depends. For a relatively small and young project, it may be feasible to get all existing contributors to agree to a license change in an issue or pull request. For large and long-lived projects, you may have to seek out many contributors and even their heirs. Mozilla took years (2001-2006) to relicense Firefox, Thunderbird, and related software. - -Alternatively, you can have contributors agree in advance (via an additional contributor agreement -- see below) to certain license changes under certain conditions, beyond those allowed by your existing open source license. This shifts the complexity of changing licenses a bit. You'll need more help from your lawyers up front, and you'll still want to clearly communicate with your project's stakeholders when executing a license change. - -## Does my project need an additional contributor agreement? - -Probably not. For the vast majority of open source projects, an open source license implicitly serves as both the inbound (from contributors) and outbound (to other contributors and users) license. - -Contributor agreements can create additional administrative work for project maintainers. How much work these agreements add depends on the project and implementation. A simple agreement might require that contributors confirm, with a click, that they have the rights necessary to contribute under the project open source license. A more complicated agreement might require legal review and sign-off from contributors' employers. - -In addition, contributor agreements are sometimes perceived as not friendly to the project's community. They can also increase the barrier to community participation by adding more paperwork than some believe is necessary. - - - -Some situations where you may want to consider an additional contribution agreement for your project include: - -* Your lawyers want all contributors to expressly accept (_sign_, online or offline) contribution terms, perhaps because they feel the open source license itself is not enough (even though it is!). If this is the only concern, a contributor agreement that affirms the project's open source license should be enough. The [jQuery Individual Contributor License Agreement](https://contribute.jquery.org/CLA/) is a good example of a lightweight additional contributor agreement. For some projects, a [Developer Certificate of Origin](http://developercertificate.org/) can be an even simpler alternative. -* Your project uses an open source license that does not include an express patent grant (such as MIT), and you need a patent grant from all contributors, some of whom may work for companies with large patent portfolios that could be used to target you or the project's other contributors and users. The [Apache Individual Contributor License Agreement](https://www.apache.org/licenses/icla.txt) is a commonly used additional contributor agreement that has a patent grant mirroring the one found in the Apache License 2.0. -* Your project is under a copyleft license, but you also need to distribute a proprietary version of the project. You'll need every contributor to assign copyright to you or grant you (but not the public) a permissive license. The [MongoDB Contributor Agreement](https://www.mongodb.com/legal/contributor-agreement) is an example this type of agreement. -* You think your project might need to change licenses over its lifetime and want contributors to agree in advance to such changes. - -If you do need to use an additional contributor agreement with your project, consider using an integration such as [CLA assistant](https://github.com/cla-assistant/cla-assistant) to minimize contributor distraction. - -## What does my company's legal team need to know? - -If you're releasing an open source project as a company employee, first, your legal team should know that you're open sourcing a project. - -For better or worse, consider letting them know even if it's a personal project. You probably have an "employee IP agreement" with your company that gives them some control of your projects, especially if they are at all related to the company's business or you use any company resources to develop the project. Your company _should_ easily give you permission, and maybe already has through an employee-friendly IP agreement or a company policy. If not, you can negotiate (for example, explain that your project serves the company's professional learning and development objectives for you), or avoid working on your project until you find a better company. - -**If you're open sourcing a project for your company,** then definitely let them know. Your legal team probably already has policies for what open source license (and maybe additional contributor agreement) to use based on the company's business requirements and expertise around ensuring your project complies with the licenses of its dependencies. If not, you and they are in luck! Your legal team should be eager to work with you to figure this stuff out. Some things to think about: - -* **Third party material:** Does your project have dependencies created by others or otherwise include or use others' code? If these are open source, you'll need to comply with the materials' open source licenses. That starts with choosing a license that works with the third party open source licenses (see above). If your project modifies or distributes third party open source material, then your legal team will also want to know that you're meeting other conditions of the third party open source licenses such as retaining copyright notices. If your project uses others' code that does't have an open source license, you'll probably have to ask the third party maintainers to [add an open source license](https://choosealicense.com/no-license/#for-users), and if you can't get one, stop using their code in your project. - -* **Trade secrets:** Consider whether there is anything in the project that the company does not want to make available to the general public. If so, you could open source the rest of your project, after extracting the material the you want to keep private. - -* **Patents:** Is your company applying for a patent of which open sourcing your project would constitute [public disclosure](https://en.wikipedia.org/wiki/Public_disclosure)? Sadly, you might be asked to wait (or maybe the company will reconsider the wisdom of the application). If you're expecting contributions to your project from employees of companies with large patent portfolios, your legal team may want you to use a license with an express patent grant from contributors (such as Apache 2.0 or GPLv3), or an additional contributor agreement (see above). - -* **Trademarks:** Double check that your project's name [does not conflict with any existing trademarks](../starting-a-project/#avoiding-name-conflicts). If you use your own company trademarks in the project, check that it does not cause any conflicts. [FOSSmarks](http://fossmarks.org/) is a practical guide to understanding trademarks in the context of free and open source projects. - -* **Privacy:** Does your project collect data on users? "Phone home" to company servers? Your legal team can help you comply with company policies and external regulations. - -If you're releasing your company's first open source project, the above is more than enough to get through (but don't worry, most projects shouldn't raise any major concerns). - -Longer term, your legal team can do more to help the company get more from its involvement in open source, and stay safe: - -* **Employee contribution policies:** Consider developing a corporate policy that specifies how your employees contribute to open source projects. A clear policy will reduce confusion among your employees and help them contribute to open source projects in the company's best interest, whether as part of their jobs or in their free time. A good example is Rackspace's [Model IP and Open Source Contribution Policy](https://processmechanics.com/2015/07/23/a-model-ip-and-open-source-contribution-policy/). - - - -* **What to release:** [(Almost) everything?](http://tom.preston-werner.com/2011/11/22/open-source-everything.html) If your legal team understands and is invested in your company's open source strategy, they'll be best able to help rather than hinder your efforts. -* **Compliance:** Even if your company doesn't release any open source projects, it uses others' open source software. [Awareness and process](https://www.linux.com/blog/why-companies-use-open-source-need-compliance-program) can prevent headaches, product delays, and lawsuits. - - - -* **Patents:** Your company may wish to join the [Open Invention Network](http://www.openinventionnetwork.com/), a shared defensive patent pool to protect members' use of major open source projects, or explore other [alternative patent licensing](https://www.eff.org/document/hacking-patent-system-2016). -* **Governance:** Especially if and when it makes sense to move a project to a [legal entity outside of the company](../leadership-and-governance/#do-i-need-a-legal-entity-to-support-my-project). diff --git a/_articles/metrics.md b/_articles/metrics.md deleted file mode 100644 index 16cf32f2fe7..00000000000 --- a/_articles/metrics.md +++ /dev/null @@ -1,125 +0,0 @@ ---- -title: Open Source Metrics -description: Make informed decisions to help your open source project thrive by measuring and tracking its success. -class: metrics -toc: - why-measure-anything: "Why measure anything?" - discovery: "Discovery" - usage: "Usage" - retention: "Retention" - maintainer-activity: "Maintainer activity" -order: 9 -image: /assets/images/cards/metrics.png ---- - -## Why measure anything? - -Data, when used wisely, can help you make better decisions as an open source maintainer. - -With more information, you can: - -* Understand how users respond to a new feature -* Figure out where new users come from -* Identify, and decide whether to support, an outlier use case or functionality -* Quantify your project's popularity -* Raise money through sponsorships and grants - -For example, [Homebrew](https://github.com/Homebrew/brew/blob/bbed7246bc5c5b7acb8c1d427d10b43e090dfd39/docs/Analytics.md) finds that Google Analytics helps them prioritize work: - -> Homebrew is provided free of charge and run entirely by volunteers in their spare time. As a result, we do not have the resources to do detailed user studies of Homebrew users to decide on how best to design future features and prioritise current work. Anonymous aggregate user analytics allow us to prioritise fixes and features based on how, where and when people use Homebrew. - -Popularity isn't everything. Everybody gets into open source for different reasons. If your goal as an open source maintainer is to show off your work, be transparent about your code, or just have fun, metrics may not be important to you. - -If you _are_ interested in understanding your project on a deeper level, read on for ways to analyze your project's activity. - -## Discovery - -Before anybody can use or contribute back to your project, they need to know it exists. Ask yourself: _are people finding this project?_ - -![traffic graph](/assets/images/metrics/repo_traffic_graphs_tooltip.png) - -If your project is hosted on GitHub, [you can view](https://help.github.com/articles/about-repository-graphs/#traffic) how many people land on your project and where they come from. From your project's page, click "Graphs", then "Traffic". On this page, you can see: - -* **Total pageviews:** Tells you how many times your project was viewed - -* **Total unique visitors:** Tells you how many people viewed your project - -* **Referring sites:** Tells you where visitors came from. This metric can help you figure out where to reach your audience and whether your promotion efforts are working. - -* **Popular content:** Tells you where visitors go on your project, broken down by pageviews and unique visitors. - -[GitHub stars](https://help.github.com/articles/about-stars/) can also help provide a baseline measure of popularity. While GitHub stars don't necessarily correlate to downloads and usage, they can tell you how many people are taking notice of your work. - -You may also want to [track discoverability in specific places](https://opensource.com/business/16/6/pirate-metrics): for example, Google PageRank, referral traffic from your project's website, or referrals from other open source projects or websites. - -## Usage - -People are finding your project on this wild and crazy thing we call the internet. Ideally, when they see your project, they'll feel compelled to do something. The second question you'll want to ask is: _are people using this project?_ - -If you use a package manager, such as npm or RubyGems.org, to distribute your project, you may be able to track your project's downloads. - -Each package manager may use a slightly different definition of "download", and downloads do not necessarily correlate to installs or use, but it provides some baseline for comparison. Try using [Libraries.io](https://libraries.io/) to track usage statistics across many popular package managers. - -If your project is on GitHub, navigate again to the "Traffic" page. You can use the [clone graph](https://github.com/blog/1873-clone-graphs) to see how many times your project has been cloned on a given day, broken down by total clones and unique cloners. - -![clone graph](/assets/images/metrics/clone_graph.png) - -If usage is low compared to the number of people discovering your project, there are two issues to consider. Either: - -* Your project isn't successfully converting your audience, or -* You're attracting the wrong audience - -For example, if your project lands on the front page of Hacker News, you'll probably see a spike in discovery (traffic), but a lower conversion rate, because you're reaching everyone on Hacker News. If your Ruby project is featured at a Ruby conference, however, you're more likely to see a high conversion rate from a targeted audience. - -Try to figure out where your audience is coming from and ask others for feedback on your project page to figure out which of these two issues you're facing. - -## Retention - -People are finding your project and they're using it. The next question you'll want to ask yourself is: _are people contributing back to this project?_ - -It's never too early to start thinking about contributors. Without other people pitching in, you risk putting yourself into an unhealthy situation where your project is _popular_ (many people use it) but not _supported_ (not enough maintainer time to meet demand). - -Retention also requires an [inflow of new contributors](http://blog.abigailcabunoc.com/increasing-developer-engagement-at-mozilla-science-learning-advocacy#contributor-pathways_2), as previously active contributors will eventually move on to other things. - -Examples of community metrics that you may want to regularly track include: - -* **Total contributor count and number of commits per contributor:** Tells you how many contributors you have, and who's more or less active. On GitHub, you can view this under "Graphs" -> "Contributors." Right now, this graph only counts contributors who have committed to the default branch of the repository. - -![contributor graph](/assets/images/metrics/repo_contributors_specific_graph.png) - -* **First time, casual, and repeat contributors:** Helps you track whether you're getting new contributors, and whether they come back. (Casual contributors are contributors with a low number of commits. Whether that's one commit, less than five commits, or something else is up to you.) Without new contributors, your project's community can become stagnant. - -* **Number of open issues and open pull requests:** If these numbers get too high, you might need help with issue triaging and code reviews. - -* **Number of _opened_ issues and _opened_ pull requests:** Opened issues means somebody cares enough about your project to open an issue. If that number increases over time, it suggests people are interested in your project. - -* **Types of contributions:** For example, commits, fixing typos or bugs, or commenting on an issue. - - - -## Maintainer activity - -Finally, you'll want to close the loop by making sure your project's maintainers are able to handle the volume of contributions received. The last question you'll want to ask yourself is: _am I (or are we) responding to our community?_ - -Unresponsive maintainers become a bottleneck for open source projects. If someone submits a contribution but never hears back from a maintainer, they may feel discouraged and leave. - -[Research from Mozilla](https://docs.google.com/presentation/d/1hsJLv1ieSqtXBzd5YZusY-mB8e1VJzaeOmh8Q4VeMio/edit#slide=id.g43d857af8_0177) suggests that maintainer responsiveness is a critical factor in encouraging repeat contributions. - -Consider tracking how long it takes for you (or another maintainer) to respond to contributions, whether an issue or a pull request. Responding doesn't require taking action. It can be as simple as saying: _"Thanks for your submission! I'll review this within the next week."_ - -You could also measure the time it takes to move between stages in the contribution process, such as: - -* Average time an issue remains open -* Whether issues get closed by PRs -* Whether stale issues get closed -* Average time to merge a pull request - -## Use 📊 to learn about people - -Understanding metrics will help you build an active, growing open source project. Even if you don't track every metric on a dashboard, use the framework above to focus your attention on the type of behavior that will help your project thrive. diff --git a/_articles/starting-a-project.md b/_articles/starting-a-project.md deleted file mode 100644 index b759cd84917..00000000000 --- a/_articles/starting-a-project.md +++ /dev/null @@ -1,365 +0,0 @@ ---- -title: Starting an Open Source Project -description: Learn more about the world of open source and get ready to launch your own project. -class: beginners -toc: - the-what-and-why-of-open-source: "The what and why of open source" - should-i-launch-my-own-open-source-project: "Should I launch my own open source project?" - launching-your-own-open-source-project: "Launching your own open source project" - naming-and-branding-your-project: "Naming and branding your project" - your-pre-launch-checklist: "Your pre-launch checklist" -order: 2 -image: /assets/images/cards/beginner.png ---- - -## The "what" and "why" of open source - -So you're thinking about getting started with open source? Congratulations! The world appreciates your contribution. Let's talk about what open source is and why people do it. - -### What does "open source" mean? - -When a project is open source, that means **anybody can view, use, modify, and distribute your project for any purpose.** These permissions are enforced through [an open source license](https://opensource.org/licenses). - -Open source is powerful because it lowers the barriers to adoption, allowing ideas to spread quickly. - -To understand how it works, imagine your friend is having a potluck, and you bring a cherry pie. - -* Everybody tries the pie (_use_) -* The pie is a hit! They ask you for the recipe, which you provide (_view_) -* One friend, Alex, who's a pastry chef, suggests reducing the sugar (_modify_) -* Another friend, Lisa, asks to use it for a dinner next week (_distribute_) - -By comparison, a closed source process would be going to a restaurant and ordering a slice of cherry pie. You must pay a fee to eat the pie, and the restaurant probably won't give you their recipe. If you copied their pie exactly and sold it under your own name, the restaurant could take action against you. - -### Why do people open source their work? - - - -[There are many reasons](http://ben.balter.com/2015/11/23/why-open-source/) why a person or organization would want to open source a project. Some examples include: - -* **Collaboration:** Open source projects can accept changes from anybody in the world. [Exercism](https://github.com/exercism/), for example, is a programming exercise platform with over 350 contributors. - -* **Adoption and remixing:** Open source projects can be used by anyone for nearly any purpose. People can even use it to build other things. [WordPress](https://github.com/WordPress), for example, started as a fork of an existing project called [b2](https://github.com/WordPress/book/blob/master/Content/Part%201/2-b2-cafelog.md). - -* **Transparency:** Anyone can inspect an open source project for errors or inconsistencies. Transparency matters to governments like [Bulgaria](https://medium.com/@bozhobg/bulgaria-got-a-law-requiring-open-source-98bf626cf70a) or the [United States](https://sourcecode.cio.gov/), regulated industries like banking or healthcare, and security software like [Let's Encrypt](https://github.com/letsencrypt). - -Open source isn't just for software, either. You can open source everything from datasets to books. Check out [GitHub Explore](https://github.com/explore) for ideas on what else you can open source. - -### Does open source mean "free of charge"? - -One of open source's biggest draws is that it does not cost money. "Free of charge", however, is a byproduct of open source's overall value. - -Because [an open source license requires](https://opensource.org/osd-annotated) that anyone can use, modify, and share your project for nearly any purpose, projects themselves tend to be free of charge. If the project cost money to use, anyone could legally make a copy and use the free version instead. - -As a result, most open source projects are free, but "free of charge" is not part of the open source definition. There are ways to charge for open source projects indirectly through dual licensing or limited features, while still complying with the official definition of open source. - -## Should I launch my own open source project? - -The short answer is yes, because no matter the outcome, launching your own project is a great way to learn how open source works. - -If you've never open sourced a project before, you might be nervous about what people will say, or whether anyone will notice at all. If this sounds like you, you're not alone! - -Open source work is like any other creative activity, whether it's writing or painting. It can feel scary to share your work with the world, but the only way to get better is to practice - even if you don't have an audience. - -If you're not yet convinced, take a moment to think about what your goals might be. - -### Setting your goals - -Goals can help you figure out what to work on, what to say no to, and where you need help from others. Start by asking yourself, _why am I open sourcing this project?_ - -There is no one right answer to this question. You may have multiple goals for a single project, or different projects with different goals. - -If your only goal is to show off your work, you may not even want contributions, and even say so in your README. On the other hand, if you do want contributors, you'll invest time into clear documentation and making newcomers feel welcome. - - - -As your project grows, your community may need more than just code from you. Responding to issues, reviewing code, and evangelizing your project are all important tasks in an open source project. - -While the amount of time you spend on non-coding tasks will depend on the size and scope of your project, you should be prepared as a maintainer to address them yourself or find someone to help you. - -**If you're part of a company open sourcing a project,** make sure your project has the internal resources it needs to thrive. You'll want to identify who's responsible for maintaining the project after launch, and how you'll share those tasks with your community. - -If you need a dedicated budget or staffing for promotion, operations and maintaining the project, start those conversations early. - - - -### Contributing to other projects - -If your goal is to learn how to collaborate with others or understand how open source works, consider contributing to an existing project. Start with a project that you already use and love. Contributing to a project can be as simple as fixing typos or updating documentation. - -If you're not sure how to get started as a contributor, check out our [How to Contribute to Open Source guide](../how-to-contribute/). - -## Launching your own open source project - -There is no perfect time to open source your work. You can open source an idea, a work in progress, or after years of being closed source. - -Generally speaking, you should open source your project when you feel comfortable having others view, and give feedback on, your work. - -No matter which stage you decide to open source your project, every project should include the following documentation: - -* [Open source license](https://help.github.com/articles/open-source-licensing/#where-does-the-license-live-on-my-repository) -* [README](https://help.github.com/articles/create-a-repo/#commit-your-first-change) -* [Contributing guidelines](https://help.github.com/articles/setting-guidelines-for-repository-contributors/) -* [Code of conduct](../code-of-conduct/) - -As a maintainer, these components will help you communicate expectations, manage contributions, and protect everyone's legal rights (including your own). They significantly increase your chances of having a positive experience. - -If your project is on GitHub, putting these files in your root directory with the recommended filenames will help GitHub recognize and automatically surface them to your readers. - -### Choosing a license - -An open source license guarantees that others can use, copy, modify, and contribute back to your project without repercussions. It also protects you from sticky legal situations. **You must include a license when you launch an open source project.** - -Legal work is no fun. The good news is that you can copy and paste an existing license into your repository. It will only take a minute to protect your hard work. - -[MIT](https://choosealicense.com/licenses/mit/), [Apache 2.0](https://choosealicense.com/licenses/apache-2.0/), and [GPLv3](https://choosealicense.com/licenses/gpl-3.0/) are the most popular open source licenses, but [there are other options](https://choosealicense.com) to choose from. - -When you create a new project on GitHub, you are given the option to select a license. Including an open source license will make your GitHub project open source. - -![pick a license](/assets/images/starting-a-project/repository-license-picker.png) - -If you have other questions or concerns around the legal aspects of managing an open source project, [we've got you covered](../legal/). - -### Writing a README - -READMEs do more than explain how to use your project. They also explain why your project matters, and what your users can do with it. - -In your README, try to answer the following questions: - -* What does this project do? -* Why is this project useful? -* How do I get started? -* Where can I get more help, if I need it? - -You can use your README to answer other questions, like how you handle contributions, what the goals of the project are, and information about licenses and attribution. If you don't want to accept contributions, or your project is not yet ready for production, write this information down. - - - -Sometimes, people avoid writing a README because they feel like the project is unfinished, or they don't want contributions. These are all very good reasons to write one. - -For more inspiration, try using @18F's ["Making READMEs Readable"](https://pages.18f.gov/open-source-guide/making-readmes-readable/) or @PurpleBooth's [README template](https://gist.github.com/PurpleBooth/109311bb0361f32d87a2) to write a complete README. - -When you include a README file in the root directory, GitHub will automatically display it on the repository homepage. - -### Writing your contributing guidelines - -A CONTRIBUTING file tells your audience how to participate in your project. For example, you might include information on: - -* How to file a bug report (try using [issue and pull request templates](https://github.com/blog/2111-issue-and-pull-request-templates)) -* How to suggest a new feature -* How to set up your environment and run tests - -In addition to technical details, a CONTRIBUTING file is an opportunity to communicate your expectations for contributions, such as: - -* The types of contributions you're looking for -* Your roadmap or vision for the project -* How contributors should (or should not) get in touch with you - -Using a warm, friendly tone and offering specific suggestions for contributions (such as writing documentation, or making a website) can go a long way in making newcomers feel welcomed and excited to participate. - -For example, [Active Admin](https://github.com/activeadmin/activeadmin/) starts [its contributing guide](https://github.com/activeadmin/activeadmin/blob/master/CONTRIBUTING.md) with: - -> First off, thank you for considering contributing to Active Admin. It's people like you that make Active Admin such a great tool. - -In the earliest stages of your project, your CONTRIBUTING file can be simple. You should always explain how to report bugs or file issues, and any technical requirements (like tests) to make a contribution. - -Over time, you might add other frequently asked questions to your CONTRIBUTING file. Writing down this information means fewer people will ask you the same questions over and over again. - -For more help with writing your CONTRIBUTING file, check out @nayafia's [contributing guide template](https://github.com/nayafia/contributing-template/blob/master/CONTRIBUTING-template.md) or @mozilla's ["How to Build a CONTRIBUTING.md"](http://mozillascience.github.io/working-open-workshop/contributing/). - -Link to your CONTRIBUTING file from your README, so more people see it. If you [place the CONTRIBUTING file in your project's repository](https://help.github.com/articles/setting-guidelines-for-repository-contributors/), GitHub will automatically link to your file when a contributor creates an issue or opens a pull request. - -![contributing guidelines](/assets/images/starting-a-project/Contributing-guidelines.jpg) - -### Establishing a code of conduct - - - -Finally, a code of conduct helps set ground rules for behavior for your project's participants. This is especially valuable if you're launching an open source project for a community or company. A code of conduct empowers you to facilitate healthy, constructive community behavior, which will reduce your stress as a maintainer. - -For more information, check out our [Code of Conduct guide](../code-of-conduct/). - -In addition to communicating _how_ you expect participants to behave, a code of conduct also tends to describe who these expectations apply to, when they apply, and what to do if a violation occurs. - -Much like open source licenses, there are also emerging standards for codes of conduct, so you don't have to write your own. The [Contributor Covenant](http://contributor-covenant.org/) is a drop-in code of conduct that is used by [over 40,000 open source projects](http://contributor-covenant.org/adopters/), including Kubernetes, Rails, and Swift. No matter which text you use, you should be prepared to enforce your code of conduct when necessary. - -Paste the text directly into a CODE_OF_CONDUCT file in your repository. Keep the file in your project's root directory so it's easy to find, and link to it from your README. - -## Naming and branding your project - -Branding is more than a flashy logo or catchy project name. It's about how you talk about your project, and who you reach with your message. - -### Choosing the right name - -Pick a name that is easy to remember and, ideally, gives some idea of what the project does. For example: - -* [Sentry](https://github.com/getsentry/sentry) monitors apps for crash reporting -* [Thin](https://github.com/macournoyer/thin) is a fast and simple Ruby web server - -If you're building upon an existing project, using their name as a prefix can help clarify what your project does (ex. [node-fetch](https://github.com/bitinn/node-fetch) brings `window.fetch` to Node.js). - -Consider clarity above all. Puns are fun, but remember that some jokes might not translate to other cultures or people with different experiences from you. Some of your potential users might be company employees: you don't want to make them uncomfortable when they have to explain your project at work! - -### Avoiding name conflicts - -[Check for open source projects with a similar name](http://ivantomic.com/projects/ospnc/), especially if you share the same language or ecosystem. If your name overlaps with a popular existing project, you might confuse your audience. - -If you want a website, Twitter handle, or other properties to represent your project, make sure you can get the names you want. Ideally, [reserve those names now](https://instantdomainsearch.com/) for peace of mind, even if you don't intend to use them just yet. - -Make sure that your project's name doesn't infringe upon any trademarks. A company might ask you to take down your project later on, or even take legal action against you. It's just not worth the risk. - -You can check the [WIPO Global Brand Database](http://www.wipo.int/branddb/en/) for trademark conflicts. If you're at a company, this is one of the things your [legal team can help you with](../legal/). - -Finally, do a quick Google search for your project name. Will people be able to easily find your project? Does something else appear in the search results that you wouldn't want them to see? - -### How you write (and code) affects your brand, too! - -Throughout the life of your project, you'll do a lot of writing: READMEs, tutorials, community documents, responding to issues, maybe even newsletters and mailing lists. - -Whether it's official documentation or a casual email, your writing style is part of your project's brand. Consider how you might come across to your audience and whether that is the tone you wish to convey. - - - -Using warm, inclusive language (such as "them", even when referring to the single person) can go a long way in making your project feel welcoming to new contributors. Stick to simple language, as many of your readers may not be native English speakers. - -Beyond how you write words, your coding style may also become part of your project's brand. [Angular](https://github.com/johnpapa/angular-styleguide) and [jQuery](http://contribute.jquery.org/style-guide/js/) are two examples of projects with rigorous coding styles and guidelines. - -It isn't necessary to write a style guide for your project when you're just starting out, and you may find that you enjoy incorporating different coding styles into your project anyway. But you should anticipate how your writing and coding style might attract or discourage different types of people. The earliest stages of your project are your opportunity to set the precedent you wish to see. - -## Your pre-launch checklist - -Ready to open source your project? Here's a checklist to help. Check all the boxes? You're ready to go! [Click "publish"](https://help.github.com/articles/making-a-private-repository-public/) and pat yourself on the back. - -**Documentation** - -
- - -
- -
- - -
- -
- - -
- -
- - -
- -**Code** - -
- - -
- -
- - -
- -
- - -
- -**People** - -If you're an individual: - -
- - -
- -If you're a company or organization: - -
- - -
- -
- - -
- -
- - -
- -
- - -
- -## You did it! - -Congratulations on open sourcing your first project. No matter the outcome, working in public is a gift to the community. With every commit, comment, and pull request, you're creating opportunities for yourself and for others to learn and grow. diff --git a/_config.yml b/_config.yml index a6b3816a5be..a08601ad060 100644 --- a/_config.yml +++ b/_config.yml @@ -1,5 +1,12 @@ -title: "Open Source Guide" -description: "A community guide for open source creators." +title: "开源指南" +description: "为开放源代码的初学者提供的向导，基于社区合著的形式存在。" + +locale: zh-CN +translations: + - locale: zh-CN + name: 简体中文 (zh-CN) + repository: github/open-source-guide + exclude: - bin @@ -39,6 +46,7 @@ gems: - jekyll-octicons - jekyll-seo-tag - jekyll-sitemap + - jekyll-multiple-languages-plugin markdown: kramdown From 278a6f0f87f186bcf0e952cffb87b1ae8e28411c Mon Sep 17 00:00:00 2001 From: LiJiansheng Date: Mon, 27 Feb 2017 22:32:42 +0800 Subject: [PATCH 002/156] add README file for Chinese. Signed-off-by: LiJiansheng --- README-zh_CN.md | 50 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) create mode 100644 README-zh_CN.md diff --git a/README-zh_CN.md b/README-zh_CN.md new file mode 100644 index 00000000000..52979ceb534 --- /dev/null +++ b/README-zh_CN.md @@ -0,0 +1,50 @@ +# 开源指南 + +[![Build Status](https://travis-ci.org/github/open-source-guide.svg?branch=gh-pages)](https://travis-ci.org/github/open-source-guide) + +开源指南 (https://opensource.guide/) 是为打算学习如何运行和参与开源项目整理的资料集合，至于学习者，可以是独立的个体、也可以是来自社区成员、甚至是来自企业。 + +## 背景 + +开源指南最初是由 GitHub 创立和策划，渐渐的有了来自公司外部的社区的参与和审核，而这些人也并非是针对GitHub的产品来贡献的。 + +我们的目标是希望聚合社区的最佳实践，而 *不需要* 关心GitHub（或者是任何其他的独立个体或公司）是否认为是最佳的。因此，我们尝试使用广泛的实例和引用来说明我们的观点。 + +**开源指南是资料集合地和讨论区。** 我们之所以启动这个项目的一个原因就是：我们认为目前人们要创建开源项目时没有充足的资料可以查看。我们所做的这些开源指南希望能够成为大家的最佳实践，当然由不足的地方，也请大家多多参与。我们也希望这里能够成为大家敞谈关于运行开源项目的各种困难、障碍、以及困惑。 + + +## 路线图 + +项目的[路线图](docs/roadmap.md)，我们分享了项目的愿景和事项的优先级。 + +## 参与贡献 + +我们对本项目的目标是成为社区的最佳实践，所以我们需要四方人才的参与！有一些主见和建议？请移步[贡献指南](/CONTRIBUTING.md)，找找反馈和贡献的正确路径。 + + +## Licenses + +本项目内容基于[CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/)，此协议赋予你可基于任何目的来使用这些内容（但是你不可以进行商标授权），所以你需要遵循以下内容： + +> Content based on [github.com/github/open-source-guide](https://github.com/github/open-source-guide) used under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/) license. + +Code, including source files and code samples if any in the content, is released under [CC0-1.0](https://creativecommons.org/publicdomain/zero/1.0/), with the following exceptions: + +* The primer components in `node_modules` are under the MIT license; see `LICENSE` in each component's directory +* The [Octicons images](https://octicons.github.com) are under the [SIL OFL 1.1](http://scripts.sil.org/OFL) + +This means you can use the code and content in this repository except for GitHub trademarks in your own projects. When using the GitHub logos, be sure to follow the [GitHub logo guidelines](https://github.com/logos). + +When you contribute to this repository you are doing so under the above licenses. + +Screenshots and images from other projects are used according to [various permissions](notices.md#permissions). + +## 感谢 + +这些指南的初始版本的作者： **@nayafia, @bkeepers, @stephbwills,** 以及 **@mlinksva**。 + + +特别感谢 **@aitchabee, @benbalter, @brettcannon, @caabernathy, @coralineada, @dmleong, @ericholscher, @gr2m, @janl, @jessfraz, @joshsimmons, @kfogel, @kytrinyx, @lee-dohm, @mikeal, @mikemcquaid, @nathansobo, @nruff, @nsqe, @orta, @parkr, @shazow, @steveklabnik,** 以及 **@wooorm** ，感谢他们为初始版本非常有价值的贡献和专业的知识。特别感谢 **@sophshep** 和 **@jeejkang** 为本指南所做的设计和说明。 + +## 免责声明 +尽管我们提供了运行开源项目的意见，但我们毕竟不是律师。请在开始之前，阅读我们的[免责声明](notices.md#legal-disclaimer) 。 From b5133d3aa87a12ff8c1c68357947c1ca9a0000f7 Mon Sep 17 00:00:00 2001 From: LiJiansheng Date: Sun, 5 Mar 2017 21:43:34 +0800 Subject: [PATCH 003/156] add zh-CN for all articles. --- _articles/zh-CN/best-practices.md | 1 + 1 file changed, 1 insertion(+) diff --git a/_articles/zh-CN/best-practices.md b/_articles/zh-CN/best-practices.md index 74e62b80b13..b84eb9624f2 100644 --- a/_articles/zh-CN/best-practices.md +++ b/_articles/zh-CN/best-practices.md @@ -1,4 +1,5 @@ --- +locale: zh-CN title: 维护者最佳实践 description: Making your life easier as an open source maintainer, from documenting processes to leveraging your community. class: best-practices From e8b1ef2907597f5dfaa22a78e7c8cd5cd94053ba Mon Sep 17 00:00:00 2001 From: LiJiansheng Date: Sun, 5 Mar 2017 21:46:01 +0800 Subject: [PATCH 004/156] add md head "locale=zh_CN". Signed-off-by: LiJiansheng --- _articles/zh-CN/building-community.md | 276 ++++++++++ _articles/zh-CN/code-of-conduct.md | 116 ++++ _articles/zh-CN/finding-users.md | 162 ++++++ _articles/zh-CN/getting-paid.md | 167 ++++++ _articles/zh-CN/how-to-contribute.md | 524 +++++++++++++++++++ _articles/zh-CN/leadership-and-governance.md | 161 ++++++ _articles/zh-CN/legal.md | 162 ++++++ _articles/zh-CN/metrics.md | 129 +++++ _articles/zh-CN/starting-a-project.md | 366 +++++++++++++ 9 files changed, 2063 insertions(+) create mode 100644 _articles/zh-CN/building-community.md create mode 100644 _articles/zh-CN/code-of-conduct.md create mode 100644 _articles/zh-CN/finding-users.md create mode 100644 _articles/zh-CN/getting-paid.md create mode 100644 _articles/zh-CN/how-to-contribute.md create mode 100644 _articles/zh-CN/leadership-and-governance.md create mode 100644 _articles/zh-CN/legal.md create mode 100644 _articles/zh-CN/metrics.md create mode 100644 _articles/zh-CN/starting-a-project.md diff --git a/_articles/zh-CN/building-community.md b/_articles/zh-CN/building-community.md new file mode 100644 index 00000000000..b7843b58304 --- /dev/null +++ b/_articles/zh-CN/building-community.md @@ -0,0 +1,276 @@ +--- +locale: zh-CN +title: 打造受欢迎的社区 +description: Building a community that encourages people to use, contribute to, and evangelize your project. +class: building +toc: + setting-your-project-up-for-success: "Setting your project up for success" + growing-your-community: "Growing your community" + resolving-conflicts: "Resolving conflicts" +order: 4 +image: /assets/images/cards/building.png +--- + +## Setting your project up for success + +You've launched your project, you're spreading the word, and people are checking it out. Awesome! Now, how do you get them to stick around? + +A welcoming community is an investment into your project's future and reputation. If your project is just starting to see its first contributions, start by giving early contributors a positive experience, and make it easy for them to keep coming back. + +### Make people feel welcome + +One way to think about your project's community is through what @MikeMcQuaid calls the [contributor funnel](https://speakerdeck.com/mikemcquaid/the-open-source-contributor-funnel): + +![contributor funnel](/assets/images/building-community/contributor_funnel_mikemcquaid.png) + +As you build your community, consider how someone at the top of the funnel (a potential user) might theoretically make their way to the bottom (an active maintainer). Your goal is to reduce friction at each stage of the contributor experience. When people have easy wins, they will feel incentivized to do more. + +Start with your documentation: + +* **Make it easy for someone to use your project.** [A friendly README](../starting-a-project/#writing-a-readme) and clear code examples will make it easier for anyone who lands on your project to get started. +* **Clearly explain how to contribute**, using [your CONTRIBUTING file](../starting-a-project/#writing-your-contributing-guidelines) and keeping your issues up-to-date. + +Good documentation invites people to interact with your project. Eventually, someone will open an issue or pull request. Use these interactions as opportunities to move them down the funnel. + +* **When someone new lands on your project, thank them for their interest!** It only takes one negative experience to make someone not want to come back. +* **Be responsive.** If you don't respond to their issue for a month, chances are, they've already forgotten about your project. +* **Be open-minded about the types of contributions you'll accept.** Many contributors start with a bug report or small fix. There are [many ways to contribute](../how-to-contribute/#what-it-means-to-contribute) to a project. Let people help how they want to help. +* **If there's a contribution you disagree with,** thank them for their idea and [explain why](../best-practices/#learning-to-say-no) it doesn't fit into the scope of the project, linking to relevant documentation if you have it. + + + +The majority of open source contributors are "casual contributors": people who contribute to a project only occasionally. A casual contributor may not have time to get fully up to speed with your project, so your job is to make it easy for them to contribute. + +Encouraging other contributors is an investment in yourself, too. When you empower your biggest fans to run with the work they're excited about, there's less pressure to do everything yourself. + +### Document everything + + + +When you start a new project, it may feel natural to keep your work private. But open source projects thrive when you document your process in public. + +When you write things down, more people can participate at every step of the way. You might get help on something you didn't even know you needed. + +Writing things down means more than just technical documentation. Any time you feel the urge to write something down or privately discuss your project, ask yourself whether you can make it public. + +Be transparent about your project's roadmap, the types of contributions you're looking for, how contributions are reviewed, or why you made certain decisions. + +If you notice multiple users running into the same problem, document the answers in the README. + +For meetings, consider publishing your notes or takeaways in a relevant issue. The feedback you'll get from this level of transparency may surprise you. + +Documenting everything applies to the work you do, too. If you're working on a substantial update to your project, put it into a pull request and mark it as a work in progress (WIP). That way, other people can feel involved in the process early on. + +### Be responsive + +As you [promote your project](../finding-users), people will have feedback for you. They may have questions about how things work, or need help getting started. + +Try to be responsive when someone files an issue, submits a pull request, or asks a question about your project. When you respond quickly, people will feel they are part of a dialogue, and they'll be more enthusiastic about participating. + +Even if you can't review the request immediately, acknowledging it early helps increase engagement. Here's how @tdreyno responded to a pull request on [Middleman](https://github.com/middleman/middleman/pull/1466): + +![middleman pull request](/assets/images/building-community/middleman_pr.png) + +[A Mozilla study found that](https://docs.google.com/presentation/d/1hsJLv1ieSqtXBzd5YZusY-mB8e1VJzaeOmh8Q4VeMio/edit#slide=id.g43d857af8_0177) contributors who received code reviews within 48 hours had a much higher rate of return and repeat contribution. + +Conversations about your project could also be happening in other places around the internet, such as Stack Overflow, Twitter, or Reddit. You can set up notifications in some of these places so you are alerted when someone mentions your project. + +### Give your community a place to congregate + +There are two reasons to give your community a place to congregate. + +The first reason is for them. Help people get to know each other. People with common interests will inevitably want a place to talk about it. And when communication is public and accessible, anybody can read past archives to get up to speed and participate. + +The second reason is for you. If you don't give people a public place to talk about your project, they will likely contact you directly. In the beginning, it may seem easy enough to respond to private messages "just this once". But over time, especially if your project becomes popular, you will feel exhausted. Resist the temptation to communicate with people about your project in private. Instead, direct them to a designated public channel. + +Public communication can be as simple as directing people to open an issue instead of emailing you directly or commenting on your blog. You could also set up a mailing list, or create a Twitter account, Slack, or IRC channel for people to talk about your project. Or try all of the above! + +[Kubernetes kops](https://github.com/kubernetes/kops#getting-involved) sets aside office hours every other week to help community members: + +> Kops also has time set aside every other week to offer help and guidance to the community. Kops maintainers have agreed to set aside time specifically dedicated to working with newcomers, helping with PRs, and discussing new features. + +Notable exceptions to public communication are: 1) security issues and 2) sensitive code of conduct violations. You should always have a way for people to report these issues privately. If you don't want to use your personal email, set up a dedicated email address. + +## Growing your community + +Communities are extremely powerful. That power can be a blessing or a curse, depending on how you wield it. As your project's community grows, there are ways to help it become a force of construction, not destruction. + +### Don't tolerate bad actors + +Any popular project will inevitably attract people who harm, rather than help, your community. They may start unnecessary debates, quibble over trivial features, or bully others. + +Do your best to adopt a zero-tolerance policy towards these types of people. If left unchecked, negative people will make other people in your community uncomfortable. They may even leave. + + + +Regular debates over trivial aspects of your project distracts others, including you, from focusing on important tasks. New people who arrive to your project may see these conversations and not want to participate. + +When you see negative behavior happening on your project, call it out publicly. Explain, in a kind but firm tone, why their behavior is not acceptable. If the problem persists, you may need to [ask them to leave](../code-of-conduct/#enforcing-your-code-of-conduct). Your [code of conduct](../code-of-conduct/) can be a constructive guide for these conversations. + +### Meet contributors where they're at + +Good documentation only becomes more important as your community grows. Casual contributors, who may not otherwise be familiar with your project, read your documentation to quickly get the context they need. + +In your CONTRIBUTING file, explicitly tell new contributors how to get started. You may even want to make a dedicated section for this purpose. [Django](https://github.com/django/django), for example, has a special landing page to welcome new contributors. + +![django new contributors page](/assets/images/building-community/django_new_contributors.png) + +In your issue queue, label bugs that are suitable for different types of contributors: for example, [_"first timers only"_](https://medium.com/@kentcdodds/first-timers-only-78281ea47455#.g1k01jy05), _"good first bug"_, or _"documentation"_. [These labels](https://github.com/librariesio/libraries.io/blob/6afea1a3354aef4672d9b3a9fc4cc308d60020c8/app/models/github_issue.rb#L8-L14) make it easy for someone new to your project to quickly scan your issues and get started. + +Finally, use your documentation to make people feel welcome at every step of the way. + +You will never interact with most people who land on your project. There may be contributions you didn't receive because somebody felt intimidated or didn't know where to get started. Even a few kind words can keep someone from leaving your project in frustration. + +For example, here's how [Rubinius](https://github.com/rubinius/rubinius/) starts [its contributing guide](https://github.com/rubinius/rubinius/blob/master/.github/contributing.md): + +> We want to start off by saying thank you for using Rubinius. This project is a labor of love, and we appreciate all of the users that catch bugs, make performance improvements, and help with documentation. Every contribution is meaningful, so thank you for participating. That being said, here are a few guidelines that we ask you to follow so we can successfully address your issue. + +### Share ownership of your project + + + +People are excited to contribute to projects when they feel a sense of ownership. That doesn't mean you need to turn over your project's vision or accept contributions you don't want. But the more you give credit to others, the more they'll stick around. + +See if you can find ways to share ownership with your community as much as possible. Here are some ideas: + +* **Resist fixing easy (non-critical) bugs.** Instead, use them as opportunities to recruit new contributors, or mentor someone who'd like to contribute. It may seem unnatural at first, but your investment will pay off over time. For example, @michaeljoseph asked a contributor to submit a pull request on a [Cookiecutter](https://github.com/audreyr/cookiecutter) issue below, rather than fix it himself. + +![cookiecutter issue](/assets/images/building-community/cookiecutter_submit_pr.png) + +* **Start a CONTRIBUTORS or AUTHORS file in your project** that lists everyone who's contributed to your project, like [Sinatra](https://github.com/sinatra/sinatra/blob/master/AUTHORS.md) does. + +* If you've got a sizeable community, **send out a newsletter or write a blog post** thanking contributors. Rust's [This Week in Rust](https://this-week-in-rust.org/) and Hoodie's [Shoutouts](http://hood.ie/blog/shoutouts-week-24.html) are two good examples. + +* **Give every contributor commit access.** @felixge found that this made people [more excited to polish their patches](http://felixge.de/2013/03/11/the-pull-request-hack.html), and he even found new maintainers for projects that he hadn't worked on in awhile. + +* If your project is on GitHub, **move your project from your personal account to an [Organization](https://help.github.com/articles/creating-a-new-organization-account/)** and add at least one backup admin. Organizations make it easier to work on projects with external collaborators. + +The reality is that [most projects only have](https://peerj.com/preprints/1233.pdf) one or two maintainers who do most of the work. The bigger your project, and the bigger your community, the easier it is to find help. + +While you may not always find someone to answer the call, putting a signal out there increases the chances that other people will pitch in. And the earlier you start, the sooner people can help. + + + +## Resolving conflicts + +In the early stages of your project, making major decisions is easy. When you want to do something, you just do it. + +As your project becomes more popular, more people will take interest in the decisions you make. Even if you don't have a big community of contributors, if your project has a lot of users, you'll find people weighing in on decisions or raising issues of their own. + +For the most part, if you've cultivated a friendly, respectful community and documented your processes openly, your community should be able to find resolution. But sometimes you run into an issue that's a bit harder to address. + +### Set the bar for kindness + +When your community is grappling with a difficult issue, tempers may rise. People may become angry or frustrated and take it out on one another, or on you. + +Your job as a maintainer is to keep these situations from escalating. Even if you have a strong opinion on the topic, try to take the position of a moderator or facilitator, rather than jumping into the fight and pushing your views. If someone is being unkind or monopolizing the conversation, [act immediately](../building-community/#dont-tolerate-bad-actors) to keep discussions civil and productive. + + + +Other people are looking to you for guidance. Set a good example. You can still express disappointment, unhappiness, or concern, but do so calmly. + +Keeping your cool isn't easy, but demonstrating leadership improves the health of your community. The internet thanks you. + +### Treat your README as a constitution + +Your README is [more than just a set of instructions](../starting-a-project/#writing-a-readme). It's also a place to talk about your goals, product vision, and roadmap. If people are overly focused on debating the merit of a particular feature, it may help to revisit your README and talk about the higher vision of your project. Focusing on your README also depersonalizes the conversation, so you can have a constructive discussion. + +### Focus on the journey, not the destination + +Some projects use a voting process to make major decisions. While sensible at first glance, voting emphasizes getting to an "answer," rather than listening to and addressing each other's concerns. + +Voting can become political, where community members feel pressured to do each other favors or vote a certain way. Not everybody votes, either, whether it's the [silent majority](http://ben.balter.com/2016/03/08/optimizing-for-power-users-and-edge-cases/#the-silent-majority-of-users) in your community, or current users who didn't know a vote was taking place. + +Sometimes, voting is a necessary tiebreaker. As much as you are able, however, emphasize ["consensus seeking"](https://en.wikipedia.org/wiki/Consensus-seeking_decision-making) rather than consensus. + +Under a consensus seeking process, community members discuss major concerns until they feel they have been adequately heard. When only minor concerns remain, the community moves forward. "Consensus seeking" acknowledges that a community may not be able to reach a perfect answer. Instead, it prioritizes listening and discussion. + + + +Even if you don't actually adopt a consensus seeking process, as a project maintainer, it's important that people know you are listening. Making other people feel heard, and committing to resolving their concerns, goes a long way to diffuse sensitive situations. Then, follow up on your words with actions. + +Don't rush into a decision for the sake of having a resolution. Make sure that everybody feels heard and that all information has been made public before moving toward a resolution. + +### Keep the conversation focused on action + +Discussion is important, but there is a difference between productive and unproductive conversations. + +Encourage discussion so long as it is actively moving towards resolution. If it's clear that conversation is languishing or going off-topic, jabs are getting personal, or people are quibbling about minor details, it's time to shut it down. + +Allowing these conversations to continue is not only bad for the issue at hand, but bad for the health of your community. It sends a message that these types of conversations are permitted or even encouraged, and it can discourage people from raising or resolving future issues. + +With every point made by you or by others, ask yourself, _"How does this bring us closer to a resolution?"_ + +If the conversation is starting to unravel, ask the group, _"Which steps should we take next?"_ to refocus the conversation. + +If a conversation clearly isn't going anywhere, there are no clear actions to be taken, or the appropriate action has already been taken, close the issue and explain why you closed it. + + + +### Pick your battles wisely + +Context is important. Consider who is involved in the discussion and how they represent the rest of the community. + +Is everybody in the community upset about, or even engaged with, this issue? Or is a lone troublemaker? Don't forget to consider your silent community members, not just the active voices. + +If the issue does not represent the broader needs of your community, you may just need to acknowledge the concerns of a few people. If this is a recurring issue without a clear resolution, point them to previous discussions on the topic and close the thread. + +### Identify a community tiebreaker + +With a good attitude and clear communication, most difficult situations are resolvable. However, even in a productive conversation, there can simply be a difference in opinion on how to proceed. In these cases, identify an individual or group of people that can serve as a tiebreaker. + +A tiebreaker could be the primary maintainer of the project, or it could be a small group of people who make a decision based on voting. Ideally, you've identified a tiebreaker and the associated process in a GOVERNANCE file before you ever have to use it. + +Your tiebreaker should be a last resort. Divisive issues are an opportunity for your community to grow and learn. Embrace these opportunities and use a collaborative process to move to a resolution wherever possible. + +## Community is the ❤️ of open source + +Healthy, thriving communities fuel the thousands of hours poured into open source every week. Many contributors point to other people as the reason for working - or not working - on open source. By learning how to tap into that power constructively, you'll help someone out there have an unforgettable open source experience. diff --git a/_articles/zh-CN/code-of-conduct.md b/_articles/zh-CN/code-of-conduct.md new file mode 100644 index 00000000000..aee84181e68 --- /dev/null +++ b/_articles/zh-CN/code-of-conduct.md @@ -0,0 +1,116 @@ +--- +locale: zh-CN +title: 行为准则 +description: Facilitate healthy and constructive community behavior by adopting and enforcing a code of conduct. +class: coc +toc: + why-do-i-need-a-code-of-conduct: "Why do I need a code of conduct?" + establishing-a-code-of-conduct: "Establishing a code of conduct" + deciding-how-youll-enforce-your-code-of-conduct: "Deciding how you’ll enforce your code of conduct" + enforcing-your-code-of-conduct: "Enforcing your code of conduct" +order: 8 +image: /assets/images/cards/coc.png +--- + +## Why do I need a code of conduct? + +A code of conduct is a document that establishes expectations for behavior for your project's participants. Adopting, and enforcing, a code of conduct can help create a positive social atmosphere for your community. + +Codes of conduct help protect not just your participants, but yourself. If you maintain a project, you may find that unproductive attitudes from other participants can make you feel drained or unhappy about your work over time. + +A code of conduct empowers you to facilitate healthy, constructive community behavior. Being proactive reduces the likelihood that you, or others, will become fatigued with your project, and helps you take action when someone does something you don't agree with. + +## Establishing a code of conduct + +Try to establish a code of conduct as early as possible: ideally, when you first create your project. + +In addition to communicating your expectations, a code of conduct describes the following: + +* Where the code of conduct takes effect _(only on issues and pull requests, or community activities like events?)_ +* Whom the code of conduct applies to _(community members and maintainers, but what about sponsors?)_ +* What happens if someone violates the code of conduct +* How someone can report violations + +Wherever you can, use prior art. The [Contributor Covenant](http://contributor-covenant.org/) is a drop-in code of conduct that is used by over 40,000 open source projects, including Kubernetes, Rails, and Swift. + +The [Django Code of Conduct](https://www.djangoproject.com/conduct/) and the [Citizen Code of Conduct](http://citizencodeofconduct.org/) are also two good code of conduct examples. + +Place a CODE_OF_CONDUCT file in your project's root directory, and link to it from your README, so it's visible to your community. + +## Deciding how you'll enforce your code of conduct + + + +You should explain how your code of conduct will be enforced **_before_** a violation occurs. There are several reasons to do so: + +* It demonstrates that you are serious about taking action when it's needed. + +* Your community will feel more reassured that complaints actually get reviewed. + +* You'll reassure your community that the review process is fair and transparent, should they ever find themselves investigated for a violation. + +You should give people a private way (such as an email address) to report a code of conduct violation and explain who receives that report. It could be a maintainer, a group of maintainers, or a code of conduct working group. + +Don't forget that someone might want to report a violation about a person who receives those reports. In this case, give them an option to report violations to someone else. For example, @ctb and @mr-c [explain on their project](https://github.com/dib-lab/khmer/blob/master/CODE_OF_CONDUCT.rst), [khmer](https://github.com/dib-lab/khmer): + +> Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by emailing **khmer-project@idyll.org** which only goes to C. Titus Brown and Michael R. Crusoe. To report an issue involving either of them please email **Judi Brown Clarke, Ph.D.** the Diversity Director at the BEACON Center for the Study of Evolution in Action, an NSF Center for Science and Technology.* + +For inspiration, check out Django's [enforcement manual](https://www.djangoproject.com/conduct/enforcement-manual/) (though you may not need something this comprehensive, depending on the size of your project). + +## Enforcing your code of conduct + +Sometimes, despite your best efforts, somebody will do something that violates this code. There are several ways to address negative or harmful behavior when it comes up. + +### Gather information about the situation + +Treat each community member's voice as important as your own. If you receive a report that someone violated the code of conduct, take it seriously and investigate the matter, even if it does not match your own experience with that person. Doing so signals to your community that you value their perspective and trust their judgment. + +The community member in question may be a repeat offender who consistently makes others feel uncomfortable, or they may have only said or done something once. Both can be grounds for taking action, depending on context. + +Before you respond, give yourself time to understand what happened. Read through the person's past comments and conversations to better understand who they are and why they might have acted in such a way. Try to gather perspectives other than your own about this person and their behavior. + + + +### Take appropriate action + +After gathering and processing sufficient information, you'll need to decide what to do. As you consider your next steps, remember that your goal as a moderator is to foster a safe, respectful, and collaborative environment. Consider not only how to deal with the situation in question, but how your response will affect the rest of your community's behavior and expectations moving forward. + +When somebody reports a code of conduct violation, it is your, not their, job to handle it. Sometimes, the reporter is disclosing information at great risk to their career, reputation, or physical safety. Forcing them to confront their harasser could put the reporter in a compromising position. You should handle direct communication with the person in question, unless the reporter explicitly requests otherwise. + +There are a few ways you might respond to a code of conduct violation: + +* **Give the person in question a public warning** and explain how their behavior negatively impacted others, preferably in the channel where it occurred. Where possible, public communication conveys to the rest of the community that you take the code of conduct seriously. Be kind, but firm in your communication. + +* **Privately reach out to the person** in question to explain how their behavior negatively impacted others. You may want to use a private communication channel if the situation involves sensitive personal information. If you communicate with someone privately, it's a good idea to CC those who first reported the situation, so they know you took action. Ask the reporting person for consent before CCing them. + +Sometimes, a resolution cannot be reached. The person in question may become aggressive or hostile when confronted or does not change their behavior. In this situation, you may want to consider taking stronger action. For example: + +* **Suspend the person** in question from the project, enforced through a temporary ban on participating in any aspect of the project + +* **Permanently ban** the person from the project + +Banning members should not be taken lightly and represents a permanent and irreconcilable difference of perspectives. You should only take these measures when it is clear that a resolution cannot be reached. + +## Your responsibilities as a maintainer + +A code of conduct is not a law that is enforced arbitrarily. You are the enforcer of the code of conduct and it's your responsibility to follow the rules that the code of conduct establishes. + +As a maintainer you establish the guidelines for your community and enforce those guidelines according to the rules set forth in your code of conduct. This means taking any report of a code of conduct violation seriously. The reporter is owed a thorough and fair review of their complaint. If you determine that the behavior that they reported is not a violation, communicate that clearly to them and explain why you're not going to take action on it. What they do with that is up to them: tolerate the behavior that they had an issue with, or stop participating in the community. + +A report of behavior that doesn't _technically_ violate the code of conduct may still indicate that there is a problem in your community, and you should investigate this potential problem and act accordingly. This may include revising your code of conduct to clarify acceptable behavior and/or talking to the person whose behavior was reported and telling them that while they did not violate the code of conduct, they are skirting the edge of what is expected and are making certain participants feel uncomfortable. + +In the end, as a maintainer, you set and enforce the standards for acceptable behavior. You have the ability to shape the community values of the project, and participants expect you to enforce those values in a fair and even-handed way. + +## Encourage the behavior you want to see in the world 🌎 + +When a project seems hostile or unwelcoming, even if it's just one person whose behavior is tolerated by others, you risk losing many more contributors, some of whom you may never even meet. It's not always easy to adopt or enforce a code of conduct, but fostering a welcoming environment will help your community grow. diff --git a/_articles/zh-CN/finding-users.md b/_articles/zh-CN/finding-users.md new file mode 100644 index 00000000000..d958932c32e --- /dev/null +++ b/_articles/zh-CN/finding-users.md @@ -0,0 +1,162 @@ +--- +locale: zh-CN +title: 为项目寻找适合的用户 +description: 通过找到诚心如意的用户，帮助开源项目成长。 +class: finding +toc: + spreading-the-word: "Spreading the word" + figure-out-your-message: "Figure out your message" + help-people-find-and-follow-your-project: "Help people find and follow your project" + go-where-your-projects-audience-is-online: "Go where your project’s audience is (online)" + go-where-your-projects-audience-is-offline: "Go where your project’s audience is (offline)" + build-a-reputation: "Build a reputation" +order: 3 +image: /assets/images/cards/finding.png +--- + +## Spreading the word + +There's no rule that says you have to promote an open source project when you launch. There are many fulfilling reasons to work in open source that have nothing to do with popularity. If you are hoping others will find and use your open source project, however, it's time to tell everybody about your hard work! + +## Figure out your message + +Before you start the actual work of promoting your project, you should be able to explain what it does, and why it matters. + +What makes your project different or interesting? Why did you create it? Answering these questions for yourself will make it easier to convince others. + +Remember that people get involved as users, and eventually contributors, because it solves a problem for them. As you think about your project's message and value, try to view it through the lens of what _they_ might want. + +For example, @robb uses code examples to clearly communicate why his project, [Cartography](https://github.com/robb/Cartography), is useful: + +![cartography readme](/assets/images/finding-users/cartography.jpg) + +For a deeper diver into messaging, check out Mozilla's ["Personas and Pathways"](http://mozillascience.github.io/working-open-workshop/personas_pathways/) exercise for developing user personas. + +## Help people find and follow your project + + + +Help people find and remember your project by pointing them to a single namespace. + +**Have a clear handle to promote your work.** A Twitter handle, GitHub URL, or IRC channel is an easy way to point people to your project. They also give your project's growing community a place to convene. + +If you don't wish to set up these channels for your project yet, promote your own Twitter or GitHub handle in everything you do. For example, make sure it is included in your bio or slides if you speak at a meetup or event. That way, people know how to reach you or follow your work. + + + +**Consider creating a website for your project.** A website makes your project friendlier and easier to navigate, especially paired with clear documentation and tutorials. It also suggests that your project is active, which will make your audience feel more comfortable using it. Use examples to give people ideas for how to use your project. + +[@adrianholovaty](https://news.ycombinator.com/item?id=7531689), co-creator of Django, said that a website was _"by far the best thing we did with Django in the early days"_. + +If your project is hosted on GitHub, you can use [GitHub Pages](https://pages.github.com/) to easily make a website. [Yeoman](http://yeoman.io/), [Vagrant](https://www.vagrantup.com/), and [Middleman](https://middlemanapp.com/) are [a few examples](https://github.com/showcases/github-pages-examples) of excellent, comprehensive websites. + +![vagrant homepage](/assets/images/finding-users/vagrant_homepage.png) + +Now that you have a message for your project, and an easy way for people to find your project, let's get out there and talk to your audience! + +## Go where your project's audience is (online) + +Online outreach is a great way to share and spread the word quickly. Using online channels, you have the potential to reach a very wide audience. + +Take advantage of existing online communities and platforms to reach your audience. If your open source project is a software project, you can probably find your audience on [Stack Overflow](http://stackoverflow.com/), [reddit](http://www.reddit.com), [Hacker News](https://news.ycombinator.com/), or [Quora](https://www.quora.com/). Find the channels where you think people will most benefit from or be excited about your work. + + + +See if you can find ways to share your project in relevant ways: + +* **Get to know relevant open source projects and communities.** Sometimes, you don't have to directly promote your project. If your project is perfect for data scientists who use Python, get to know the Python data science community. As people get to know you, natural opportunities will arise to talk about and share your work. +* **Find people experiencing the problem that your project solves.** Search through related forums for people who fall into your project's target audience. Answer their question and find a tactful way, when appropriate, to suggest your project as a solution. +* **Ask for feedback.** Introduce yourself and your work to an audience that would find it relevant and interesting. Be specific about who you think would benefit from your project. Try to finish the sentence: _"I think my project would really help X, who are trying to do Y_". Listen and respond to others' feedback, rather than simply promoting your work. + +Generally speaking, focus on helping others before asking for things in return. Because it is easy for anybody to promote a project online, there will be a lot of noise. Give people context for who you are, not just what you want, to stand out from the crowd. + +If nobody pays attention or responds to your initial outreach, don't get discouraged! Most project launches are an iterative process that can take months or years. If you don't get a response the first time, try a different tactic, or look for ways to add value to others' work first. These things take time and dedication. + +## Go where your project's audience is (offline) + +![public speaking](/assets/images/finding-users/public_speaking.jpg) + +Offline events are a popular way to promote new projects. It's a great way to reach an engaged audience and build deeper human connections, especially if you are interested in reaching developers. + +If you're [new to public speaking](http://speaking.io/), start by finding a local meetup that's related to the language or ecosystem of your project. + + + +If you've never spoken at an event before, it's perfectly normal to feel nervous! Remember that your audience is there because they genuinely want to hear about your work. + +As you write your talk, focus on what your audience will find interesting and get value out of. Keep your language friendly and approachable. Smile, breathe, and have fun. + + + +When you feel ready, consider speaking at a conference to promote your project. Conferences can help you reach more people, sometimes from all over the world. + +Look for conferences that are specific to your language or ecosystem. Before you submit your talk, research the conference beforehand to tailor your talk to its attendees and increase your chances of getting accepted. You can often get a sense of a conference's audience by looking at its speakers. + + + +## Build a reputation + +In addition to the strategies outlined above, the best way to invite people to share and contribute to your project is to share and contribute to their projects. + +Helping newcomers, sharing resources, and making thoughtful contributions to others' work will help you build a positive reputation. Then, people will have context for your work and be more likely to pay attention and share what you're doing. + +Sometimes, these relationships can even lead to official partnerships with the wider ecosystem. + + + +It's never too early, or too late, to start building your reputation. Even if you've launched your own project already, continue looking for ways to help others. + +There is no overnight solution to building an audience. Gaining the trust and respect of others takes time, and reputation building work never ends. + + + +## Keep at it! + +Sometimes, it takes a long time before people notice your open source project. That's okay! Some of the most popular projects today took years to reach high levels of activity. Focus on building relationships instead of a magic bullet. Be patient, and keep sharing your work with those who appreciate it. diff --git a/_articles/zh-CN/getting-paid.md b/_articles/zh-CN/getting-paid.md new file mode 100644 index 00000000000..3f3c57c53b7 --- /dev/null +++ b/_articles/zh-CN/getting-paid.md @@ -0,0 +1,167 @@ +--- +locale: zh-CN +title: 通过为开源工作获得报酬 +description: Sustain your work in open source by getting financial support for your time or your project. +class: getting-paid +toc: + why-some-people-seek-financial-support: "Why some people seek financial support" + funding-your-own-time: "Funding your own time" + finding-funding-for-your-project: "Finding funding for your project" + building-a-case-for-financial-support: "Building a case for financial support" +order: 7 +image: /assets/images/cards/getting-paid.png +--- + +## Why some people seek financial support + +Much of open source work is volunteered. For example, someone might come across a bug in a project they use and submit a quick fix, or they might enjoy tinkering with an open source project in their spare time. + + + +There are many reasons why a person would not want to be paid for their open source work. + +* **They may already have a full-time job that they love,** which enables them to contribute to open source in their spare time. +* **They enjoy thinking of open source as a hobby** or creative escape and don't want to feel financially obligated to work on their projects. +* **They get other benefits from contributing to open source,** such as building their reputation or portfolio, learning a new skill, or feeling closer to a community. + + + +For others, especially when contributions are ongoing or require significant time, getting paid to contribute to open source is the only way they can participate, either because the project requires it, or for personal reasons. + +Maintaining popular projects can be a significant responsibility, taking up 10 or 20 hours per week instead of a few hours per month. + + + +Paid work also enables people from different walks of life to make meaningful contributions. Some people cannot afford to spend unpaid time on open source projects, based on their current financial position, debt, or family or other caretaking obligations. That means the world never sees contributions from talented people who can't afford to volunteer their time. This has ethical implications, as @ashedryden [has described](https://www.ashedryden.com/blog/the-ethics-of-unpaid-labor-and-the-oss-community), since work that is done is biased in favor of those who already have advantages in life, who then gain additional advantages based on their volunteer contributions, while others who are not able to volunteer then don't get later opportunities, which reinforces the current lack of diversity in the open source community. + + + +If you're looking for financial support, there are two paths to consider. You can fund your own time as a contributor, or you can find organizational funding for the project. + +## Funding your own time + +Today, many people get paid to work part- or full-time on open source. The most common way to get paid for your time is to talk to your employer. + +It's easier to make a case for open source work if your employer actually uses the project, but get creative with your pitch. Maybe your employer doesn't use the project, but they use Python, and maintaining a popular Python project help attract new Python developers. Maybe it makes your employer look more developer-friendly in general. + + + +If you don't have an existing open source project you'd like to work on, but would rather that your current work output is open sourced, make a case for your employer to open source some of their internal software. + +Many companies are developing open source programs to build their brand and recruit quality talent. + +@hueniverse, for example, found that there were financial reasons to justify [Walmart's investment in open source](https://hueniverse.com/2014/08/15/open-source-aint-charity/). And @jamesgpearce found that Facebook's open source program [made a difference](https://opensource.com/business/14/10/head-of-open-source-facebook-oscon) in recruiting: + +> It is closely aligned with our hacker culture, and how our organization was perceived. We asked our employees, "Were you aware of the open source software program at Facebook?". Two-thirds said "Yes". One-half said that the program positively contributed to their decision to work for us. These are not marginal numbers, and I hope, a trend that continues. + +If your company goes down this route, it's important to keep the boundaries between community and corporate activity clear. Ultimately, open source sustains itself through contributions from people all over the world, and that's bigger than any one company or location. + + + +If you can't convince your current employer to prioritize open source work, consider finding a new employer that encourages employee contributions to open source. Look for companies that make their dedication to open source work explicit. For example: + +* [Ghost](https://ghost.org/) is a company built around [an open source project](https://github.com/tryghost/ghost) +* [Rackspace](https://www.rackspace.com/en-us) published its [open source contribution policy](https://blog.rackspace.com/rackspaces-policy-on-contributing-to-open-source/) for employees + +Projects that originated at a large company, such as [Go](https://github.com/golang) or [React](https://github.com/facebook/react), will also likely employ people to work on open source. + +Finally, depending on your personal circumstances, you can try raising money independently to fund your open source work. For example: + +* @gaearon funded his work on [Redux](https://github.com/reactjs/redux) through a [Patreon crowdfunding campaign](http://redux.js.org/) +* @andrewgodwin funded work on Django schema migrations [through a Kickstarter campaign](https://www.kickstarter.com/projects/andrewgodwin/schema-migrations-for-django) + +## Finding funding for your project + +Beyond arrangements for individual contributors, sometimes projects raise money from companies, individuals, or others to fund ongoing work. + +Organizational funding might go towards paying current contributors, covering the costs of running the project (such as hosting fees), or investing into new features or ideas. + +A few examples of projects with organizational funding include: + +* **[webpack](https://github.com/webpack),** which raises money from companies and individuals [through OpenCollective](https://opencollective.com/webpack) +* **[Vue](https://github.com/vuejs/vue),** created by @yyx990803, which is [funded through Patreon](https://github.com/open-source/stories/yyx990803) +* **[Ruby Together](https://rubytogether.org/),** a nonprofit organization created by @indirect that pays for work on [bundler](https://github.com/bundler/bundler), [RubyGems](https://github.com/rubygems/rubygems), and other Ruby infrastructure projects + +As open source's popularity increases, finding funding for projects is still experimental. A few current options include: + +* **Raise money for your work through crowdfunding campaigns or donations.** This strategy works well if you have a strong audience or reputation already, or your project is very popular. +* **Apply for grant funding.** Some software foundations and companies offer grants for open source work, such as the [Python Software Foundation](https://www.python.org/psf/grants/), [Mozilla Foundation](https://www.mozilla.org/en-US/grants/), and [Stripe](https://stripe.com/blog/open-source-retreat-2016). +* **Raise sponsorships from companies and individual donors** through a software foundation. Or **start a business** to support the project. + +For more detailed options and case studies, @nayafia [wrote a guide](https://github.com/nayafia/lemonade-stand) to getting paid for open source work. Different types of funding require different skills, so consider your strengths to figure out which option works best for you. + +## Building a case for financial support + +Whether your project is a new idea, or has been around for years, you should expect to put significant thought into identifying your target funder and making a compelling case. + +Whether you're looking to pay for your own time, or fundraise for a project, you should be able to answer the following questions. + +### Impact + +Why is this project useful? Why do your users, or potential users, like it so much? Where will it be in five years? + +### Traction + +Try to collect evidence that your project matters, whether it's metrics, anecdotes, or testimonials. Are there any companies or noteworthy people using your project right now? If not, has a prominent person endorsed it? + +### Value to funder + +Funders, whether your employer or a grantmaking foundation, are frequently approached with opportunities. Why should they support your project over any other opportunity? How do they personally benefit? + +### Use of funds + +What, exactly, will you accomplish with the proposed funding? Focus on project milestones or outcomes rather than paying a salary. + +### How you'll receive the funds + +Does the funder have any requirements around disbursal? For example, you may need to be a nonprofit or have a nonprofit fiscal sponsor. Or perhaps the funds must be given to an individual contractor rather than an organization. These requirements vary between funders, so be sure to do your research beforehand. + + + +## Experiment and don't give up + +Raising money isn't easy, whether you're an open source project, a nonprofit, or a software startup, and in most cases require you to get creative. Identifying how you want to get paid, doing your research, and putting yourself in your funder's shoes will help you build a convincing case for funding. + +> diff --git a/_articles/zh-CN/how-to-contribute.md b/_articles/zh-CN/how-to-contribute.md new file mode 100644 index 00000000000..c0eeb47edf8 --- /dev/null +++ b/_articles/zh-CN/how-to-contribute.md @@ -0,0 +1,524 @@ +--- +locale: zh-CN +title: 如何为开源做贡献 +description: Want to contribute to open source? A guide to making open source contributions, for first-timers and for veterans. +class: contribute +toc: + why-contribute-to-open-source: "Why contribute to open source?" + what-it-means-to-contribute: "What it means to contribute" + orienting-yourself-to-a-new-project: "Orienting yourself to a new project" + finding-a-project-to-contribute-to: "Finding a project to contribute to" + how-to-submit-a-contribution: "How to submit a contribution" + what-happens-after-you-submit-a-contribution: "What happens after you submit a contribution" +order: 1 +image: /assets/images/cards/contribute.png +--- + +## Why contribute to open source? + + + +Contributing to open source can be a rewarding way to learn, teach, and build experience in just about any skill you can imagine. + +Why do people contribute to open source? Plenty of reasons! + +### Improve existing skills + +Whether it's coding, user interface design, graphic design, writing, or organizing, if you're looking for practice, there's a task for you on an open source project. + +### Meet people who are interested in similar things + +Open source projects with warm, welcoming communities keep people coming back for years. Many people form lifelong friendships through their participation in open source, whether it's running into each other at conferences or late night online chats about burritos. + +### Find mentors and teach others + +Working with others on a shared project means you'll have to explain how you do things, as well as ask other people for help. The acts of learning and teaching can be a fulfilling activity for everyone involved. + +### Build public artifacts that help you grow a reputation (and a career) + +By definition, all of your open source work is public, which means you get free examples to take anywhere as a demonstration of what you can do. + +### Learn people skills + +Open source offers opportunities to practice leadership and management skills, such as resolving conflicts, organizing teams of people, and prioritizing work. + +### It's empowering to be able to make changes, even small ones + +You don't have to become a lifelong contributor to enjoy participating in open source. Have you ever seen a typo on a website, and wished someone would fix it? On an open source project, you can do just that. Open source helps people feel agency over their lives and how they experience the world, and that in itself is gratifying. + +## What it means to contribute + +If you're a new open source contributor, the process can be intimidating. How do you find the right project? What if you don't know how to code? What if something goes wrong? + +Not to worry! There are all sorts of ways to get involved with an open source project, and a few tips will help you get the most out of your experience. + +### You don't have to contribute code + +A common misconception about contributing to open source is that you need to contribute code. In fact, it's often the non-code parts of a project that are [most neglected or overlooked](https://github.com/blog/2195-the-shape-of-open-source). You'll do the project a _huge_ favor by offering to pitch in with non-code contributions! + + + +Even if you are a developer, non-code contributions are a great way to get involved with a project and meet other community members. Building those relationships will give you opportunities to work on other parts of the project. + + + +### Do you like planning events? + +* Organize workshops or meetups about the project, [like @fzamperin did for NodeSchool](https://github.com/nodeschool/organizers/issues/406) +* Organize the project's conference (if they have one) +* Help community members find the right conferences and submit proposals for speaking + +### Do you like to design? + +* Restructure layouts to improve the project's usability +* Conduct user research to reorganize and refine the project's navigation or menus +* Put together a style guide to help the project have a consistent visual design +* Create art for t-shirts or a new logo, [like hapi.js's contributors did](https://github.com/hapijs/contrib/issues/68) + +### Do you like to write? + +* Write and improve the project's documentation +* Curate a folder of examples showing how the project is used +* Start a newsletter for the project, or curate highlights from the mailing list +* Write tutorials for the project, [like pypa's contributors did](https://github.com/pypa/python-packaging-user-guide/issues/194) +* Write a translation for the project's documentation + + + +### Do you like organizing? + +* Link to duplicate issues, and suggest new issue labels, to keep things organized +* Go through open issues and suggest closing old ones, [like @nzakas did for eslint](https://github.com/eslint/eslint/issues/6765) +* Ask clarifying questions on recently opened issues to move the discussion forward + +### Do you like to code? + +* Find an open issue to tackle, [like @dianjin did for Leaflet](https://github.com/Leaflet/Leaflet/issues/4528#issuecomment-216520560) +* Ask if you can help write a new feature +* Automate project setup +* Improve tooling and testing + +### Do you like helping people? + +* Answer questions about the project on e.g., Stack Overflow ([like this Postgres example](http://stackoverflow.com/questions/18664074/getting-error-peer-authentication-failed-for-user-postgres-when-trying-to-ge)) or reddit +* Answer questions for people on open issues +* Help moderate the discussion boards or conversation channels + +### Do you like helping others code? + +* Review code on other people's submissions +* Write tutorials for how a project can be used +* Offer to mentor another contributor, [like @ereichert did for @bronzdoc on Rust](https://github.com/rust-lang/book/issues/123#issuecomment-238049666) + +### You don't just have to work on software projects! + +While "open source" often refers to software, you can collaborate on just about anything. There are books, recipes, lists, and classes that get developed as open source projects. + +For example: + +* @sindresorhus curates a [list of "awesome" lists](https://github.com/sindresorhus/awesome) +* @h5bp maintains a [list of potential interview questions](https://github.com/h5bp/Front-end-Developer-Interview-Questions) for front-end developer candidates +* @stuartlynn and @nicole-a-tesla made a [collection of fun facts about puffins](https://github.com/stuartlynn/puffin_facts) + +Even if you're a software developer, working on a documentation project can help you get started in open source. It's often less intimidating to work on projects that don't involve code, and the process of collaboration will build your confidence and experience. + +## Orienting yourself to a new project + + + +For anything more than a typo fix, contributing to open source is like walking up to a group of strangers at a party. If you start talking about llamas, while they were deep in a discussion about goldfish, they'll probably look at you a little strangely. + +Before jumping in blindly with your own suggestions, start by learning how to read the room. Doing so increases the chances that your ideas will be noticed and heard. + +### Anatomy of an open source project + +Every open source community is different. + +Spending years on one open source project means you've gotten to know one open source project. Move to a different project, and you might find the vocabulary, norms, and communication styles are completely different. + +That said, many open source projects follow a similar organizational structure. Understanding the different community roles and overall process will help you get quickly oriented to any new project. + +A typical open source project has the following types of people: + +* **Author:** The person/s or organization that created the project +* **Owner:** The person/s who has administrative ownership over the organization or repository (not always the same as the original author) +* **Maintainers:** Contributors who are responsible for driving the vision and managing the organizational aspects of the project. (They may also be authors or owners of the project.) +* **Contributors:** Everyone who has contributed something back to the project. +* **Community Members:** People who use the project. They might be active in conversations or express their opinion on the project's direction. + +Bigger projects may also have subcommittees or working groups focused on different tasks, such as tooling, triage, community moderation, and event organizing. Look on a project's website for a "team" page, or in the repository for governance documentation, to find this information. + +A project also has documentation. These files are usually listed in the top level of a repository. + +* **LICENSE:** By definition, every open source project must have an [open source license](https://choosealicense.com). If the project does not have a license, it is not open source. +* **README:** The README is the instruction manual that welcomes new community members to the project. It explains why the project is useful and how to get started. +* **CONTRIBUTING:** Whereas READMES help people _use_ the project, contributing docs help people _contribute_ to the project. It explains what types of contributions are needed and how the process works. While not every project has a CONTRIBUTING file, its presence signals that this is a welcoming project to contribute to. +* **CODE_OF_CONDUCT:** The code of conduct sets ground rules for participants' behavior associated and helps to facilitate a friendly, welcoming environment. While not every project has a CODE_OF_CONDUCT file, its presence signals that this is a welcoming project to contribute to. +* **Other documentation:** There might be additional documentation, such as tutorials, walkthroughs, or governance policies, especially on bigger projects. + +Finally, open source projects use the following tools to organize discussion. Reading through the archives will give you a good picture of how the community thinks and works. + +* **Issue tracker:** Where people discuss issues related to the project. +* **Pull requests:** Where people discuss and review changes that are in progress. +* **Discussion forums or mailing lists:** Some projects may use these channels for conversational topics (ex. _"How do I..."_ or _"What do you think about..."_ instead of bug reports or feature requests). Others use the issue tracker for all conversations. +* **Synchronous chat channel:** Some projects use chat channels (such as Slack or IRC) for casual conversation, collaboration, and quick exchanges. + +## Finding a project to contribute to + +Now that you've figured out how open source projects work, it's time to find a project to contribute to! + +If you've never contributed to open source before, take some advice from U.S. President John F. Kennedy, who once said, _"Ask not what your country can do for you - ask what you can do for your country."_ + +Contributing to open source happens at all levels, across projects. You don't need to overthink what exactly your first contribution will be, or how it will look. + +Instead, start by thinking about the projects you already use, or want to use. The projects you'll actively contribute to are the ones you find yourself coming back to. + +Within those projects, whenever you catch yourself thinking that something could be better or different, act on your instinct. + +Open source isn't an exclusive club; it's made by people just like you. "Open source" is just a fancy term for treating the world's problems as fixable. + +You might scan a README and find a broken link or a typo. Or you're a new user and you noticed something is broken, or an issue that you think should really be in the documentation. Instead of ignoring it and moving on, or asking someone else to fix it, see whether you can help out by pitching in. That's what open source is all about! + +> [28% of casual contributions](http://www.igor.pro.br/publica/papers/saner2016.pdf) to open source are documentation, such as a typo fix, reformatting, or writing a translation. + +You can also use one of the following resources to help you discover new projects: + +* [GitHub Explore](https://github.com/explore/) +* [First Timers Only](http://www.firsttimersonly.com/) +* [Your First PR](https://yourfirstpr.github.io/) +* [CodeTriage](https://www.codetriage.com/) +* [24 Pull Requests](https://24pullrequests.com/) +* [Up For Grabs](http://up-for-grabs.net/) +* [Contributor-ninja](https://contributor.ninja) + +### A checklist before you contribute + +When you've found a project you'd like to contribute to, do a quick scan to make sure that the project is suitable for accepting contributions. Otherwise, your hard work may never get a response. + +Here's a handy checklist to evaluate whether a project is good for new contributors. + +**Meets the definition of open source** + +
+ + +
+ +**Project actively accepts contributions** + +Look at the commit activity on the master branch. On GitHub, you can see this information on a repository's homepage. + +
+ + +
+ +
+ + +
+ +
+ + +
+ +Next, look at the project's issues. + +
+ + +
+ +
+ + +
+ +
+ + +
+ +
+ + +
+ +
+ + +
+ +Now do the same for the project's pull requests. + +
+ + +
+ +
+ + +
+ +
+ + +
+ +
+ + +
+ +
+ + +
+ +**Project is welcoming** + +A project that is friendly and welcoming signals that they will be receptive to new contributors. + +
+ + +
+ +
+ + +
+ +
+ + +
+ +
+ + +
+ + + +## How to submit a contribution + +You've found a project you like, and you're ready to make a contribution. Finally! Here's how to get your contribution in the right way. + +### Communicating effectively + +Whether you're a one-time contributor or trying to join a community, working with others is one of the most important skills you'll develop in open source. + + + +Before you open an issue or pull request, or ask a question in chat, keep these points in mind to help your ideas come across effectively. + +**Give context.** Help others get quickly up to speed. If you're running into an error, explain what you're trying to do and how to reproduce it. If you're suggesting a new idea, explain why you think it'd be useful to the project (not just to you!). + +> 😇 _"X doesn't happen when I do Y"_ +> +> 😢 _"X is broken! Please fix it."_ + +**Do your homework beforehand.** It's ok not to know things, but show that you tried. Before asking for help, be sure to check a project's README, documentation, issues (open or closed), mailing list, and search the internet for an answer. People will appreciate when you demonstrate that you're trying to learn. + +> 😇 _"I'm not sure how to implement X. I checked the help docs and didn't find any mentions."_ +> +> 😢 _"How do I X?"_ + +**Keep requests short and direct.** Much like sending an email, every contribution, no matter how simple or helpful, requires someone else's review. Many projects have more incoming requests than people available to help. Be concise. You will increase the chance that someone will be able to help you. + +> 😇 _"I'd like to write an API tutorial."_ +> +> 😢 _"I was driving down the highway the other day and stopped for gas, and then I had this amazing idea for something we should be doing, but before I explain that, let me show you..."_ + +**Keep all communication public.** Although it's tempting, don't reach out to maintainers privately unless you need to share sensitive information (such as a security issue or serious conduct violation). When you keep the conversation public, more people can learn and benefit from your exchange. Discussions can be, in themselves, contributions. + +> 😇 _(as a comment) "@-maintainer Hi there! How should we proceed on this PR?"_ +> +> 😢 _(as an email) "Hey there, sorry to bother you over email, but I was wondering if you've had a chance to review my PR"_ + +**It's okay to ask questions (but be patient!).** Everybody was new to the project at some point, and even experienced contributors need to get up to speed when they look at a new project. By the same token, even longtime maintainers are not always familiar with every part of the project. Show them the same patience that you'd want them to show to you. + +> 😇 _"Thanks for looking into this error. I followed your suggestions. Here's the output."_ +> +> 😢 _"Why can't you fix my problem? Isn't this your project?"_ + +**Respect community decisions.** Your ideas may differ from the community's priorities or vision. They may offer feedback or decide not to pursue your idea. While you should discuss and look for compromise, maintainers have to live with your decision longer than you will. If you disagree with their direction, you can always work on your own fork or start your own project. + +> 😇 _"I'm disappointed you can't support my use case, but as you've explained it only affects a minor portion of users, I understand why. Thanks for listening."_ +> +> 😢 _"Why won't you support my use case? This is unacceptable!"_ + +**Above all, keep it classy.** Open source is made up of collaborators from all over the world. Context gets lost across languages, cultures, geographies, and time zones. In addition, written communication makes it harder to convey a tone or mood. Assume good intentions in these conversations. It's fine to politely push back on an idea, ask for more context, or further clarify your position. Just try to leave the internet a better place than when you found it. + +### Gathering context + +Before doing anything, do a quick check to make sure your idea hasn't been discussed elsewhere. Skim the project's README, issues (open and closed), mailing list, and Stack Overflow. You don't have to spend hours going through everything, but a quick search for a few key terms goes a long way. + +If you can't find your idea elsewhere, you're ready to make a move. If the project is on GitHub, you'll likely communicate by opening an issue or pull request: + +* **Issues** are like starting a conversation or discussion +* **Pull requests** are for starting work on a solution +* **For lightweight communication,** such as a clarifying or how-to question, try asking on Stack Overflow, IRC, Slack, or other chat channels, if the project has one + +Before you open an issue or pull request, check the project's contributing docs (usually a file called CONTRIBUTING, or in the README), to see whether you need to include anything specific. For example, they may ask that you follow a template, or require that you use tests. + +If you want to make a substantial contribution, open an issue to ask before working on it. It's helpful to watch the project for awhile (on GitHub, [you can click "Watch"](https://help.github.com/articles/watching-repositories/) to be notified of all conversations), and get to know community members, before doing work that might not get accepted. + + + +### Opening an issue + +You should usually open an issue in the following situations: + +* Report an error you can't solve yourself +* Discuss a high-level topic or idea (ex. community, vision, policies) +* Propose a new feature or other project idea + +Tips for communicating on issues: + +* **If you see an open issue that you want to tackle,** comment on the issue to let people know you're on it. That way, people are less likely to duplicate your work. +* **If an issue was opened awhile ago,** it's possible that it's being addressed somewhere else, or has already been resolved, so comment to ask for confirmation before starting work. +* **If you opened an issue, but figured out the answer later on your own,** comment on the issue to let people know, then close the issue. Even documenting that outcome is a contribution to the project. + +### Opening a pull request + +You should usually open a pull request in the following situations: + +* Submit trivial fixes (ex. a typo, broken link, or obvious error) +* Start work on a contribution that was already asked for, or that you've already discussed, in an issue + +A pull request doesn't have to represent finished work. It's usually better to open a pull request early on, so others can watch or give feedback on your progress. Just mark it as a "WIP" (Work in Progress) in the subject line. You can always add more commits later. + +If the project is on GitHub, here's how to submit a pull request: + +* **[Fork the repository](https://guides.github.com/activities/forking/)** and clone it locally. Connect your local to the original "upstream" repository by adding it as a remote. Pull in changes from "upstream" often so that you stay up to date so that when you submit your pull request, merge conflicts will be less likely. (See more detailed instructions [here](https://help.github.com/articles/syncing-a-fork/).) +* **[Create a branch](https://guides.github.com/introduction/flow/)** for your edits. +* **Reference any relevant issues** or supporting documentation in your PR (ex. "Closes #37.") +* **Include screenshots of the before and after** if your changes include differences in HTML/CSS. Drag and drop the images into the body of your pull request. +* **Test your changes!** Run your changes against any existing tests if they exist and create new ones when needed. Whether tests exist or not, make sure your changes don't break the existing project. +* **Contribute in the style of the project** to the best of your abilities. This may mean using indents, semi-colons or comments differently than you would in your own repository, but makes it easier for the maintainer to merge, others to understand and maintain in the future. + +If this is your first pull request, check out [Make a Pull Request](http://makeapullrequest.com/), which @kentcdodds created as a free walkthrough resource. + +## What happens after you submit a contribution + +You did it! Congratulations on becoming an open source contributor. We hope it's the first of many. + +After you submit a contribution, one of the following will happen: + +### 😭 You don't get a response. + +Hopefully you [checked the project for signs of activity](#a-checklist-before-you-contribute) before making a contribution. Even on an active project, however, it's possible that your contribution won't get a response. + +If you haven't gotten a response in over a week, it's fair to politely respond in that same thread, asking someone for a review. If you know the name of the right person to review your contribution, you can @-mention them in that thread. + +**Don't** reach out to that person privately; remember that public communication is vital to open source projects. + +If you make a polite bump and still nobody responds, it's possible that nobody will respond, ever. It's not a great feeling, but don't let that discourage you. It's happened to everyone! There are many possible reasons why you didn't get a response, including personal circumstances that may be out of your control. Try to find another project or way to contribute. If anything, this is a good reason not to invest too much time in making a contribution before other community members are engaged and responsive. + +### 🚧 Someone requests changes to your contribution. + +It's common that you'll be asked to make changes to your contribution, whether that's feedback on the scope of your idea, or changes to your code. + +When someone requests changes, be responsive. They've taken the time to review your contribution. Opening a PR and walking away is bad form. If you don't know how to make changes, research the problem, then ask for help if you need it. + +If you don't have time to work on the issue anymore (for example, if the conversation has been going on for months, and your circumstances have changed), let the maintainer know so they're not expecting a response. Someone else may be happy to take over. + +### 👎 Your contribution doesn't get accepted. + +Your contribution may or may not be accepted in the end. Hopefully you didn't put too much work into it already. If you're not sure why it wasn't accepted, it's perfectly reasonable to ask the maintainer for feedback and clarification. Ultimately, however, you'll need to respect that this is their decision. Don't argue or get hostile. You're always welcome to fork and work on your own version if you disagree! + +### 🎉 Your contribution gets accepted. + +Hooray! You've successfully made an open source contribution! + +## You did it! + +Whether you just made your first open source contribution, or you're looking for new ways to contribute, we hope you're inspired to take action. Even if your contribution wasn't accepted, don't forget to say thanks when a maintainer put effort into helping you. Open source is made by people like you: one issue, pull request, comment, or high-five at a time. diff --git a/_articles/zh-CN/leadership-and-governance.md b/_articles/zh-CN/leadership-and-governance.md new file mode 100644 index 00000000000..0abf5b2077f --- /dev/null +++ b/_articles/zh-CN/leadership-and-governance.md @@ -0,0 +1,161 @@ +--- +locale: zh-CN +title: 领导力和治理 +description: Growing open source projects can benefit from formal rules for making decisions. +class: leadership +toc: + what-are-examples-of-formal-roles-used-in-open-source-projects: "What are examples of formal roles used in open source projects?" + how-do-i-formalize-these-leadership-roles: "How do I formalize these leadership roles?" + when-should-i-give-someone-commit-access: "When should I give someone commit access?" + what-are-some-of-the-common-governance-structures-for-open-source-projects: "What are some of the common governance structures for open source projects?" + do-i-need-governance-docs-when-i-launch-my-project: "Do I need governance docs when I launch my project?" + what-happens-if-corporate-employees-start-submitting-contributions: "What happens if corporate employees start submitting contributions?" + do-i-need-a-legal-entity-to-support-my-project: "Do I need a legal entity to support my project?" +order: 6 +image: /assets/images/cards/leadership.png +--- + +## Understanding governance for your growing project + +Your project is growing, people are engaged, and you're committed to keeping this thing going. At this stage, you may be wondering how to incorporate regular project contributors into your workflow, whether it's giving someone commit access or resolving community debates. If you have questions, we've got answers. + +## What are examples of formal roles used in open source projects? + +Many projects follow a similar structure for contributor roles and recognition. + +What these roles actually mean, though, is entirely up to you. Here are a few types of roles you may recognize: + +* **Maintainer** +* **Contributor** +* **Committer** + +**For some projects, "maintainers"** are the only people in a project with commit access. In other projects, they're simply the people who are listed in the README as maintainers. + +A maintainer doesn't necessarily have to be someone who writes code for your project. It could be someone who's done a lot of work evangelizing your project, or written documentation that made the project more accessible to others. Regardless of what they do day-to-day, a maintainer is probably someone who feels responsibility over the direction of the project and is committed to improving it. + +**A "contributor" could be anyone** who comments on an issue or pull request, people who add value to the project (whether it's triaging issues, writing code, or organizing events), or anybody with a merged pull request (perhaps the narrowest definition of a contributor). + + + +**The term "committer"** might be used to distinguish commit access, which is a specific type of responsibility, from other forms of contribution. + +While you can define your project roles any way you'd like, [consider using broader definitions](../how-to-contribute/#what-it-means-to-contribute) to encourage more forms of contribution. You can use leadership roles to formally recognize people who have made outstanding contributions to your project, regardless of their technical skill. + + + +## How do I formalize these leadership roles? + +Formalizing your leadership roles helps people feel ownership and tells other community members who to look to for help. + +For a smaller project, designating leaders can be as simple as adding their names to your README or a CONTRIBUTORS text file. + +For a bigger project, if you have a website, create a team page or list your project leaders there. For example, [PostgreSQL](https://github.com/postgres/postgres/) has a [comprehensive team page](https://www.postgresql.org/community/contributors/) with short profiles for each contributor. + +If your project has a very active contributor community, you might form a "core team" of maintainers, or even subcommittees of people who take ownership of different issue areas (ex. security, issue triaging, or community conduct). Let people self-organize and volunteer for the roles they're most excited about, rather than assigning them. + + + +Leadership teams may want to create a designated channel (like on IRC) or meet regularly to discuss the project (like on Gitter or Google Hangout). You can even make those meetings public so other people can listen. [Cucumber-ruby](https://github.com/cucumber/cucumber-ruby), for example, [hosts office hours every week](https://github.com/cucumber/cucumber-ruby/blob/master/CONTRIBUTING.md#talking-with-other-devs). + +Once you've established leadership roles, don't forget to document how people can attain them! Establish a clear process for how someone can become a maintainer or join a subcommittee in your project, and write it into your GOVERNANCE.md. + +Tools like [Vossibility](https://github.com/icecrime/vossibility-stack) can help you publicly track who is (or isn't) making contributions to the project. Documenting this information avoids the community perception that maintainers are a clique that makes its decisions privately. + +Finally, if your project is on GitHub, consider moving your project from your personal account to an Organization and adding at least one backup admin. [GitHub Organizations](https://help.github.com/articles/creating-a-new-organization-account/) make it easier to manage permissions and multiple repositories and protect your project's legacy through [shared ownership](../building-community/#share-ownership-of-your-project). + +## When should I give someone commit access? + +Some people think you should give commit access to everybody who makes a contribution. Doing so could encourage more people to feel ownership of your project. + +On the other hand, especially for bigger, more complex projects, you may want to only give commit access to people who have demonstrated their commitment. There's no one right way of doing it - do what makes you most comfortable! + +If your project is on GitHub, you can use [protected branches](https://help.github.com/articles/about-protected-branches/) to manage who can push to a particular branch, and under which circumstances. + + + +## What are some of the common governance structures for open source projects? + +There are three common governance structures associated with open source projects. + +* **BDFL:** BDFL stands for "Benevolent Dictator for Life". Under this structure, one person (usually the initial author of the project) has final say on all major project decisions. [Python](https://github.com/python) is a classic example. Smaller projects are probably BDFL by default, because there are only one or two maintainers. A project that originated at a company might also fall into the BDFL category. + +* **Meritocracy:** **(Note: the term "meritocracy" carries negative connotations for some communities and has a [complex social and political history](http://geekfeminism.wikia.com/wiki/Meritocracy).)** Under a meritocracy, active project contributors (those who demonstrate "merit") are given a formal decision making role. Decisions are usually made based on pure voting consensus. The meritocracy concept was pioneered by the [Apache Foundation](http://www.apache.org/); [all Apache projects](http://www.apache.org/index.html#projects-list) are meritocracies. Contributions can only be made by individuals representing themselves, not by a company. + +* **Liberal contribution:** Under a liberal contribution model, the people who do the most work are recognized as most influential, but this is based on current work and not historic contributions. Major project decisions are made based on a consensus seeking process (discuss major grievances) rather than pure vote, and strive to include as many community perspectives as possible. Popular examples of projects that use a liberal contribution model include [Node.js](https://nodejs.org/en/foundation/) and [Rust](https://www.rust-lang.org/en-US/). + +Which one should you use? It's up to you! Every model has advantages and tradeoffs. And although they may seem quite different at first, all three models have more in common than they seem. If you're interested in adopting one of these models, check out these templates: + +* [BDFL model template](http://oss-watch.ac.uk/resources/benevolentdictatorgovernancemodel) +* [Meritocracy model template](http://oss-watch.ac.uk/resources/meritocraticgovernancemodel) +* [Node.js's liberal contribution policy](https://medium.com/the-javascript-collection/healthy-open-source-967fa8be7951#.m9ht26e79) + +## Do I need governance docs when I launch my project? + +There is no right time to write down your project's governance, but it's much easier to define once you've seen your community dynamics play out. The best (and hardest) part about open source governance is that it is shaped by the community! + +Some early documentation will inevitably contribute to your project's governance, however, so start writing down what you can. For example, you can define clear expectations for behavior, or how your contributor process works, even at your project's launch. + +If you're part of a company launching an open source project, it's worth having an internal discussion before launch about how your company expects to maintain and make decisions about the project moving forward. You may also want to publicly explain anything particular to how your company will (or won't!) be involved with the project. + + + +## What happens if corporate employees start submitting contributions? + +Successful open source projects get used by many people and companies, and some companies may eventually have revenue streams eventually tied to the project. For example, a company may use the project's code as one component in a commercial service offering. + +As the project gets more widely used, people who have expertise in it become more in-demand - you may be one of them! - and will sometimes get paid for work they do in the project. + +It's important to treat commercial activity as normal and as just another source of development energy. Paid developers shouldn't get special treatment over unpaid ones, of course; each contribution must be evaluated on its technical merits. However, people should feel comfortable engaging in commercial activity, and feel comfortable stating their use cases when arguing in favor of a particular enhancement or feature. + +"Commercial" is completely compatible with "open source". "Commercial" just means there is money involved somewhere - that the software is used in commerce, which is increasingly likely as a project gains adoption. (When open source software is used as part of a non-open-source product, the overall product is still "proprietary" software, though, like open source, it might be used for commercial or non-commercial purposes.) + +Like anyone else, commercially-motivated developers gain influence in the project through the quality and quantity of their contributions. Obviously, a developer who is paid for her time may be able to do more than someone who is not paid, but that's okay: payment is just one of many possible factors that could affect how much someone does. Keep your project discussions focused on the contributions, not on the external factors that enable people to make those contributions. + +## Do I need a legal entity to support my project? + +You don't need a legal entity to support your open source project unless you're handling money. + +For example, if you want to create a commercial business, you'll want to set up a C Corp or LLC (if you're based in the US). If you're just doing contract work related to your open source project, you can accept money as a sole proprietor, or set up an LLC (if you're based in the US). + +If you want to accept donations for your open source project, you can set up a donation button (using PayPal or Stripe, for example), but the money won't be tax-deductible unless you are a qualifying nonprofit (a 501c3, if you're in the US). + +Many projects don't wish to go through the trouble of setting up a nonprofit, so they find a nonprofit fiscal sponsor instead. A fiscal sponsor accepts donations on your behalf, usually in exchange for a percentage of the donation. [Software Freedom Conservancy](https://sfconservancy.org/), [Apache Foundation](http://www.apache.org/), [Eclipse Foundation](https://eclipse.org/org/foundation/), [Linux Foundation](https://www.linuxfoundation.org/projects) and [Open Collective](https://opencollective.com/opensource) are examples of organizations that serve as fiscal sponsors for open source projects. + + + +If your project is closely associated with a certain language or ecosystem, there may also be a related software foundation you can work with. For example, the [Python Software Foundation](https://www.python.org/psf/) helps support [PyPI](https://pypi.python.org/pypi), the Python package manager, and the [Node.js Foundation](https://nodejs.org/en/foundation/) helps support [Express.js](http://expressjs.com/), a Node-based framework. diff --git a/_articles/zh-CN/legal.md b/_articles/zh-CN/legal.md new file mode 100644 index 00000000000..9ab10a5e7bc --- /dev/null +++ b/_articles/zh-CN/legal.md @@ -0,0 +1,162 @@ +--- +locale: zh-CN +title: 开源的法律保护 +description: Everything you've ever wondered about the legal side of open source, and a few things you didn't. +class: legal +toc: + why-do-people-care-so-much-about-the-legal-side-of-open-source: "Why do people care so much about the legal side of open source?" + are-public-github-projects-open-source: "Are public GitHub projects open source?" + just-give-me-the-tldr-on-what-i-need-to-protect-my-project: "Just give me the TL;DR on what I need to protect my project" + which-open-source-license-is-appropriate-for-my-project: "Which open source license is appropriate for my project?" + what-if-i-want-to-change-the-license-of-my-project: "What if I want to change the license of my project?" + does-my-project-need-an-additional-contributor-agreement: "Does my project need an additional contributor agreement?" + what-does-my-companys-legal-team-need-to-know: "What does my company’s legal team need to know?" +order: 10 +image: /assets/images/cards/legal.png +--- + +## Understanding the legal implications of open source + +Sharing your creative work with the world can be an exciting and rewarding experience. It can also mean a bunch of legal things you didn't know you had to worry about. Thankfully, you don't have to start from scratch. We've got your legal needs covered. (Before you dig in, be sure to read our [disclaimer](../notices/).) + +## Why do people care so much about the legal side of open source? + +Glad you asked! When you make a creative work (such as writing, graphics, or code), that work is under exclusive copyright by default. That is, the law assumes that as the author of your work, you have a say in what others can do with it. + +In general, that means nobody else can use, copy, distribute, or modify your work without being at risk of take-downs, shake-downs, or litigation. + +Open source is an unusual circumstance, however, because the author expects that others will use, modify, and share the work. But because the legal default is still exclusive copyright, you need a license that explicitly states these permissions. + +If you don't apply an open source license, everybody who contributes to your project also becomes an exclusive copyright holder of their work. That means nobody can use, copy, distribute, or modify their contributions -- and that "nobody" includes you. + +Finally, your project may have dependencies with license requirements that you weren't aware of. Your project's community, or your employer's policies, may also require your project to use specific open source licenses. We'll cover these situations below. + +## Are public GitHub projects open source? + +When you [create a new project](https://help.github.com/articles/creating-a-new-repository/) on GitHub, you have the option to make the repository **private** or **public**. + +![create repository](/assets/images/legal/repo-create-name.png) + +**Making your GitHub project public is not the same as licensing your project.** Public projects are covered by [GitHub's Terms of Service](https://help.github.com/articles/github-terms-of-service/#f-copyright-and-content-ownership), which allows others to view and fork your project, but your work otherwise comes with no permissions. + +If you want others to use, copy, modify, or contribute back to your project, you need to include an open source license. For example, someone cannot legally use any part of your GitHub project in their code, even if it's public, unless you explicitly give them the right to do so. + +## Just give me the TL;DR on what I need to protect my project. + +You're in luck, because today, open source licenses are standardized and easy to use. You can copy-paste an existing license directly into your project. + +[MIT](https://choosealicense.com/licenses/mit/), [Apache 2.0](https://choosealicense.com/licenses/apache-2.0/), and [GPLv3](https://choosealicense.com/licenses/gpl-3.0/) are the most popular open source licenses, but there are other options to choose from. You can find the full text of these licenses, and instructions on how to use them, on [choosealicense.com](https://choosealicense.com/). + +When you create a new project on GitHub, you'll be [asked to add a license](https://help.github.com/articles/open-source-licensing/). + + + +## Which open source license is appropriate for my project? + +If you're starting from a blank slate, it's hard to go wrong with the [MIT License](https://choosealicense.com/licenses/mit/). It's short, very easy to understand, and allows anyone to do anything so long as they keep a copy of the license, including your copyright notice. You'll be able to release the project under a different license if you ever need to. + +Otherwise, picking the right open source license for your project depends on your objectives. + +Your project very likely has (or will have) **dependencies**. For example, if you're open sourcing a Node.js project, you'll probably use libraries from the Node Package Manager (npm). Each of those libraries you depend on will have its own open source license. If each of their licenses is "permissive" (gives the public permission to use, modify, and share, without any condition for downstream licensing), you can use any license you want. Common permissive licenses include MIT, Apache 2.0, ISC, and BSD. + +On the other hand, if any of your dependencies' licenses are "strong copyleft" (also gives public same permissions, subject to condition of using the same license downstream), then your project will have to use the same license. Common strong copyleft licenses include GPLv2, GPLv3, and AGPLv3. + +You may also want to consider the **communities** you hope will use and contribute to your project: + +* **Do you want your project to be used as a dependency by other projects?** Probably best to use the most popular license in your relevant community. For example, [MIT](https://choosealicense.com/licenses/mit/) is the most popular license for [npm libraries](https://libraries.io/npm). +* **Do you want your project to appeal to large businesses?** A large business will likely want an express patent license from all contributors. In this case, [Apache 2.0](https://choosealicense.com/licenses/apache-2.0/) has you (and them) covered. +* **Do you want your project to appeal to contributors who do not want their contributions to be used in closed source software?** [GPLv3](https://choosealicense.com/licenses/gpl-3.0/) or (if they also do not wish to contribute to closed source services) [AGPLv3](https://choosealicense.com/licenses/agpl-3.0/) will go over well. + +Your **company** may have specific licensing requirements for its open source projects. For example, it may require a permissive license so that the company can use your project in the company's closed source product. Or your company may require a strong copyleft license and an additional contributor agreement (see below) so that only your company, and nobody else, can use your project in closed source software. Or your company may have certain needs related to standards, social responsibility, or transparency, any of which could require a particular licensing strategy. Talk to your [company's legal department](#what-does-my-companys-legal-team-need-to-know). + +When you create a new project on GitHub, you are given the option to select a license. Including one of the licenses mentioned above will make your GitHub project open source. If you'd like to see other options, check out [choosealicense.com](https://choosealicense.com) to find the right license for your project, even if it [isn't software](https://choosealicense.com/non-software/). + +## What if I want to change the license of my project? + +Most projects never need to change licenses. But occasionally circumstances change. + +For example, as your project grows it adds dependencies or users, or your company changes strategies, any of which could require or want a different license. Also, if you neglected to license your project from the start, adding a license is effectively the same as changing licenses. There are three fundamental things to consider when adding or changing a your project's license: + +**It's complicated.** Determining license compatibility and compliance and who holds copyright can get complicated and confusing very quickly. Switching to a new but compatible license for new releases and contributions is different from relicensing all existing contributions. Involve your legal team the first hint of any desire to change licenses. Even if you have or can obtain permission from your project's copyright holders for a license change, consider the impact of the change on your project's other users and contributors. Think of a license change as a "governance event" for your project that will more likely go smoothly with clear communications and consultation with your project's stakeholders. All the more reason to choose and use an appropriate license for your project from its inception! + +**Your project's existing license.** If your project's existing license is compatible with the license you want to change to, you could just start using the new license. That's because if license A is compatible with license B, you'll comply with the terms of A while complying with the terms of B (but not necessarily vice versa). So if you're currently using a permissive license (e.g., MIT), you could change to a license with more conditions, so long as you retain a copy of the MIT license and any associated copyright notices (i.e., continue to comply with the MIT license's minimal conditions). But if your current license is not permissive (e.g., copyleft, or you don't have a license) and you aren't the sole copyright holder, you couldn't just change your project's license to MIT. Essentially, with a permissive license the project's copyright holders have given permission in advance to change licenses. + +**Your project's existing copyright holders.** If you're the sole contributor to your project then either you or your company is the project's sole copyright holder. You can add or change to whatever license you or your company wants to. Otherwise there may be other copyright holders that you need agreement from in order to change licenses. Who are they? People who have commits in your project is a good place to start. But in some cases copyright will be held by those people's employers. In some cases people will have only made _de minimis_ contributions, but there's no hard and fast rule that contributions under some number of lines of code are not subject to copyright. What to do? It depends. For a relatively small and young project, it may be feasible to get all existing contributors to agree to a license change in an issue or pull request. For large and long-lived projects, you may have to seek out many contributors and even their heirs. Mozilla took years (2001-2006) to relicense Firefox, Thunderbird, and related software. + +Alternatively, you can have contributors agree in advance (via an additional contributor agreement -- see below) to certain license changes under certain conditions, beyond those allowed by your existing open source license. This shifts the complexity of changing licenses a bit. You'll need more help from your lawyers up front, and you'll still want to clearly communicate with your project's stakeholders when executing a license change. + +## Does my project need an additional contributor agreement? + +Probably not. For the vast majority of open source projects, an open source license implicitly serves as both the inbound (from contributors) and outbound (to other contributors and users) license. If your project is on GitHub, the GitHub Terms of Service make "inbound=outbound" the [explicit default](https://help.github.com/articles/github-terms-of-service/#6-contributions-under-repository-license). + +An additional contributor agreement -- often called a Contributor License Agreement (CLA) -- can create administrative work for project maintainers. How much work an agreement adds depends on the project and implementation. A simple agreement might require that contributors confirm, with a click, that they have the rights necessary to contribute under the project open source license. A more complicated agreement might require legal review and sign-off from contributors' employers. + +Also, by adding "paperwork" that some believe is unnecessary, hard to understand, or unfair (when the agreement recipient gets more rights than contriubtors or the public do via the project's open source license), an additional contributor agreement may be perceived as unfriendly to the project's community. + + + +Some situations where you may want to consider an additional contributor agreement for your project include: + +* Your lawyers want all contributors to expressly accept (_sign_, online or offline) contribution terms, perhaps because they feel the open source license itself is not enough (even though it is!). If this is the only concern, a contributor agreement that affirms the project's open source license should be enough. The [jQuery Individual Contributor License Agreement](https://contribute.jquery.org/CLA/) is a good example of a lightweight additional contributor agreement. For some projects, a [Developer Certificate of Origin](http://developercertificate.org/) can be an even simpler alternative. +* Your project uses an open source license that does not include an express patent grant (such as MIT), and you need a patent grant from all contributors, some of whom may work for companies with large patent portfolios that could be used to target you or the project's other contributors and users. The [Apache Individual Contributor License Agreement](https://www.apache.org/licenses/icla.txt) is a commonly used additional contributor agreement that has a patent grant mirroring the one found in the Apache License 2.0. +* Your project is under a copyleft license, but you also need to distribute a proprietary version of the project. You'll need every contributor to assign copyright to you or grant you (but not the public) a permissive license. The [MongoDB Contributor Agreement](https://www.mongodb.com/legal/contributor-agreement) is an example this type of agreement. +* You think your project might need to change licenses over its lifetime and want contributors to agree in advance to such changes. + +If you do need to use an additional contributor agreement with your project, consider using an integration such as [CLA assistant](https://github.com/cla-assistant/cla-assistant) to minimize contributor distraction. + +## What does my company's legal team need to know? + +If you're releasing an open source project as a company employee, first, your legal team should know that you're open sourcing a project. + +For better or worse, consider letting them know even if it's a personal project. You probably have an "employee IP agreement" with your company that gives them some control of your projects, especially if they are at all related to the company's business or you use any company resources to develop the project. Your company _should_ easily give you permission, and maybe already has through an employee-friendly IP agreement or a company policy. If not, you can negotiate (for example, explain that your project serves the company's professional learning and development objectives for you), or avoid working on your project until you find a better company. + +**If you're open sourcing a project for your company,** then definitely let them know. Your legal team probably already has policies for what open source license (and maybe additional contributor agreement) to use based on the company's business requirements and expertise around ensuring your project complies with the licenses of its dependencies. If not, you and they are in luck! Your legal team should be eager to work with you to figure this stuff out. Some things to think about: + +* **Third party material:** Does your project have dependencies created by others or otherwise include or use others' code? If these are open source, you'll need to comply with the materials' open source licenses. That starts with choosing a license that works with the third party open source licenses (see above). If your project modifies or distributes third party open source material, then your legal team will also want to know that you're meeting other conditions of the third party open source licenses such as retaining copyright notices. If your project uses others' code that doesn't have an open source license, you'll probably have to ask the third party maintainers to [add an open source license](https://choosealicense.com/no-license/#for-users), and if you can't get one, stop using their code in your project. + +* **Trade secrets:** Consider whether there is anything in the project that the company does not want to make available to the general public. If so, you could open source the rest of your project, after extracting the material the you want to keep private. + +* **Patents:** Is your company applying for a patent of which open sourcing your project would constitute [public disclosure](https://en.wikipedia.org/wiki/Public_disclosure)? Sadly, you might be asked to wait (or maybe the company will reconsider the wisdom of the application). If you're expecting contributions to your project from employees of companies with large patent portfolios, your legal team may want you to use a license with an express patent grant from contributors (such as Apache 2.0 or GPLv3), or an additional contributor agreement (see above). + +* **Trademarks:** Double check that your project's name [does not conflict with any existing trademarks](../starting-a-project/#avoiding-name-conflicts). If you use your own company trademarks in the project, check that it does not cause any conflicts. [FOSSmarks](http://fossmarks.org/) is a practical guide to understanding trademarks in the context of free and open source projects. + +* **Privacy:** Does your project collect data on users? "Phone home" to company servers? Your legal team can help you comply with company policies and external regulations. + +If you're releasing your company's first open source project, the above is more than enough to get through (but don't worry, most projects shouldn't raise any major concerns). + +Longer term, your legal team can do more to help the company get more from its involvement in open source, and stay safe: + +* **Employee contribution policies:** Consider developing a corporate policy that specifies how your employees contribute to open source projects. A clear policy will reduce confusion among your employees and help them contribute to open source projects in the company's best interest, whether as part of their jobs or in their free time. A good example is Rackspace's [Model IP and Open Source Contribution Policy](https://processmechanics.com/a-model-ip-and-open-source-contribution-policy/). + + + +* **What to release:** [(Almost) everything?](http://tom.preston-werner.com/2011/11/22/open-source-everything.html) If your legal team understands and is invested in your company's open source strategy, they'll be best able to help rather than hinder your efforts. +* **Compliance:** Even if your company doesn't release any open source projects, it uses others' open source software. [Awareness and process](https://www.linux.com/blog/why-companies-use-open-source-need-compliance-program) can prevent headaches, product delays, and lawsuits. + + + +* **Patents:** Your company may wish to join the [Open Invention Network](http://www.openinventionnetwork.com/), a shared defensive patent pool to protect members' use of major open source projects, or explore other [alternative patent licensing](https://www.eff.org/document/hacking-patent-system-2016). +* **Governance:** Especially if and when it makes sense to move a project to a [legal entity outside of the company](../leadership-and-governance/#do-i-need-a-legal-entity-to-support-my-project). diff --git a/_articles/zh-CN/metrics.md b/_articles/zh-CN/metrics.md new file mode 100644 index 00000000000..627c9ce8a65 --- /dev/null +++ b/_articles/zh-CN/metrics.md @@ -0,0 +1,129 @@ +--- +locale: zh-CN +title: 开源衡量标准 +description: Make informed decisions to help your open source project thrive by measuring and tracking its success. +class: metrics +toc: + why-measure-anything: "Why measure anything?" + discovery: "Discovery" + usage: "Usage" + retention: "Retention" + maintainer-activity: "Maintainer activity" +order: 9 +image: /assets/images/cards/metrics.png +--- + +## Why measure anything? + +Data, when used wisely, can help you make better decisions as an open source maintainer. + +With more information, you can: + +* Understand how users respond to a new feature +* Figure out where new users come from +* Identify, and decide whether to support, an outlier use case or functionality +* Quantify your project's popularity +* Understand how your project is used +* Raise money through sponsorships and grants + +For example, [Homebrew](https://github.com/Homebrew/brew/blob/bbed7246bc5c5b7acb8c1d427d10b43e090dfd39/docs/Analytics.md) finds that Google Analytics helps them prioritize work: + +> Homebrew is provided free of charge and run entirely by volunteers in their spare time. As a result, we do not have the resources to do detailed user studies of Homebrew users to decide on how best to design future features and prioritise current work. Anonymous aggregate user analytics allow us to prioritise fixes and features based on how, where and when people use Homebrew. + +Popularity isn't everything. Everybody gets into open source for different reasons. If your goal as an open source maintainer is to show off your work, be transparent about your code, or just have fun, metrics may not be important to you. + +If you _are_ interested in understanding your project on a deeper level, read on for ways to analyze your project's activity. + +## Discovery + +Before anybody can use or contribute back to your project, they need to know it exists. Ask yourself: _are people finding this project?_ + +![traffic graph](/assets/images/metrics/repo_traffic_graphs_tooltip.png) + +If your project is hosted on GitHub, [you can view](https://help.github.com/articles/about-repository-graphs/#traffic) how many people land on your project and where they come from. From your project's page, click "Graphs", then "Traffic". On this page, you can see: + +* **Total pageviews:** Tells you how many times your project was viewed + +* **Total unique visitors:** Tells you how many people viewed your project + +* **Referring sites:** Tells you where visitors came from. This metric can help you figure out where to reach your audience and whether your promotion efforts are working. + +* **Popular content:** Tells you where visitors go on your project, broken down by pageviews and unique visitors. + +[GitHub stars](https://help.github.com/articles/about-stars/) can also help provide a baseline measure of popularity. While GitHub stars don't necessarily correlate to downloads and usage, they can tell you how many people are taking notice of your work. + +You may also want to [track discoverability in specific places](https://opensource.com/business/16/6/pirate-metrics): for example, Google PageRank, referral traffic from your project's website, or referrals from other open source projects or websites. + +## Usage + +People are finding your project on this wild and crazy thing we call the internet. Ideally, when they see your project, they'll feel compelled to do something. The second question you'll want to ask is: _are people using this project?_ + +If you use a package manager, such as npm or RubyGems.org, to distribute your project, you may be able to track your project's downloads. + +Each package manager may use a slightly different definition of "download", and downloads do not necessarily correlate to installs or use, but it provides some baseline for comparison. Try using [Libraries.io](https://libraries.io/) to track usage statistics across many popular package managers. + +If your project is on GitHub, navigate again to the "Traffic" page. You can use the [clone graph](https://github.com/blog/1873-clone-graphs) to see how many times your project has been cloned on a given day, broken down by total clones and unique cloners. + +![clone graph](/assets/images/metrics/clone_graph.png) + +If usage is low compared to the number of people discovering your project, there are two issues to consider. Either: + +* Your project isn't successfully converting your audience, or +* You're attracting the wrong audience + +For example, if your project lands on the front page of Hacker News, you'll probably see a spike in discovery (traffic), but a lower conversion rate, because you're reaching everyone on Hacker News. If your Ruby project is featured at a Ruby conference, however, you're more likely to see a high conversion rate from a targeted audience. + +Try to figure out where your audience is coming from and ask others for feedback on your project page to figure out which of these two issues you're facing. + +Once you know that people are using your project, you might want to try to figure out what they are doing with it. Are they building on it by forking your code and adding features? Are they using it for science or business? + +## Retention + +People are finding your project and they're using it. The next question you'll want to ask yourself is: _are people contributing back to this project?_ + +It's never too early to start thinking about contributors. Without other people pitching in, you risk putting yourself into an unhealthy situation where your project is _popular_ (many people use it) but not _supported_ (not enough maintainer time to meet demand). + +Retention also requires an [inflow of new contributors](http://blog.abigailcabunoc.com/increasing-developer-engagement-at-mozilla-science-learning-advocacy#contributor-pathways_2), as previously active contributors will eventually move on to other things. + +Examples of community metrics that you may want to regularly track include: + +* **Total contributor count and number of commits per contributor:** Tells you how many contributors you have, and who's more or less active. On GitHub, you can view this under "Graphs" -> "Contributors." Right now, this graph only counts contributors who have committed to the default branch of the repository. + +![contributor graph](/assets/images/metrics/repo_contributors_specific_graph.png) + +* **First time, casual, and repeat contributors:** Helps you track whether you're getting new contributors, and whether they come back. (Casual contributors are contributors with a low number of commits. Whether that's one commit, less than five commits, or something else is up to you.) Without new contributors, your project's community can become stagnant. + +* **Number of open issues and open pull requests:** If these numbers get too high, you might need help with issue triaging and code reviews. + +* **Number of _opened_ issues and _opened_ pull requests:** Opened issues means somebody cares enough about your project to open an issue. If that number increases over time, it suggests people are interested in your project. + +* **Types of contributions:** For example, commits, fixing typos or bugs, or commenting on an issue. + + + +## Maintainer activity + +Finally, you'll want to close the loop by making sure your project's maintainers are able to handle the volume of contributions received. The last question you'll want to ask yourself is: _am I (or are we) responding to our community?_ + +Unresponsive maintainers become a bottleneck for open source projects. If someone submits a contribution but never hears back from a maintainer, they may feel discouraged and leave. + +[Research from Mozilla](https://docs.google.com/presentation/d/1hsJLv1ieSqtXBzd5YZusY-mB8e1VJzaeOmh8Q4VeMio/edit#slide=id.g43d857af8_0177) suggests that maintainer responsiveness is a critical factor in encouraging repeat contributions. + +Consider tracking how long it takes for you (or another maintainer) to respond to contributions, whether an issue or a pull request. Responding doesn't require taking action. It can be as simple as saying: _"Thanks for your submission! I'll review this within the next week."_ + +You could also measure the time it takes to move between stages in the contribution process, such as: + +* Average time an issue remains open +* Whether issues get closed by PRs +* Whether stale issues get closed +* Average time to merge a pull request + +## Use 📊 to learn about people + +Understanding metrics will help you build an active, growing open source project. Even if you don't track every metric on a dashboard, use the framework above to focus your attention on the type of behavior that will help your project thrive. diff --git a/_articles/zh-CN/starting-a-project.md b/_articles/zh-CN/starting-a-project.md new file mode 100644 index 00000000000..4d4a6973e84 --- /dev/null +++ b/_articles/zh-CN/starting-a-project.md @@ -0,0 +1,366 @@ +--- +locale: zh-CN +title: 开启一个开源项目 +description: Learn more about the world of open source and get ready to launch your own project. +class: beginners +toc: + the-what-and-why-of-open-source: "The what and why of open source" + should-i-launch-my-own-open-source-project: "Should I launch my own open source project?" + launching-your-own-open-source-project: "Launching your own open source project" + naming-and-branding-your-project: "Naming and branding your project" + your-pre-launch-checklist: "Your pre-launch checklist" +order: 2 +image: /assets/images/cards/beginner.png +--- + +## The "what" and "why" of open source + +So you're thinking about getting started with open source? Congratulations! The world appreciates your contribution. Let's talk about what open source is and why people do it. + +### What does "open source" mean? + +When a project is open source, that means **anybody can view, use, modify, and distribute your project for any purpose.** These permissions are enforced through [an open source license](https://opensource.org/licenses). + +Open source is powerful because it lowers the barriers to adoption, allowing ideas to spread quickly. + +To understand how it works, imagine your friend is having a potluck, and you bring a cherry pie. + +* Everybody tries the pie (_use_) +* The pie is a hit! They ask you for the recipe, which you provide (_view_) +* One friend, Alex, who's a pastry chef, suggests reducing the sugar (_modify_) +* Another friend, Lisa, asks to use it for a dinner next week (_distribute_) + +By comparison, a closed source process would be going to a restaurant and ordering a slice of cherry pie. You must pay a fee to eat the pie, and the restaurant probably won't give you their recipe. If you copied their pie exactly and sold it under your own name, the restaurant could take action against you. + +### Why do people open source their work? + + + +[There are many reasons](http://ben.balter.com/2015/11/23/why-open-source/) why a person or organization would want to open source a project. Some examples include: + +* **Collaboration:** Open source projects can accept changes from anybody in the world. [Exercism](https://github.com/exercism/), for example, is a programming exercise platform with over 350 contributors. + +* **Adoption and remixing:** Open source projects can be used by anyone for nearly any purpose. People can even use it to build other things. [WordPress](https://github.com/WordPress), for example, started as a fork of an existing project called [b2](https://github.com/WordPress/book/blob/master/Content/Part%201/2-b2-cafelog.md). + +* **Transparency:** Anyone can inspect an open source project for errors or inconsistencies. Transparency matters to governments like [Bulgaria](https://medium.com/@bozhobg/bulgaria-got-a-law-requiring-open-source-98bf626cf70a) or the [United States](https://sourcecode.cio.gov/), regulated industries like banking or healthcare, and security software like [Let's Encrypt](https://github.com/letsencrypt). + +Open source isn't just for software, either. You can open source everything from datasets to books. Check out [GitHub Explore](https://github.com/explore) for ideas on what else you can open source. + +### Does open source mean "free of charge"? + +One of open source's biggest draws is that it does not cost money. "Free of charge", however, is a byproduct of open source's overall value. + +Because [an open source license requires](https://opensource.org/osd-annotated) that anyone can use, modify, and share your project for nearly any purpose, projects themselves tend to be free of charge. If the project cost money to use, anyone could legally make a copy and use the free version instead. + +As a result, most open source projects are free, but "free of charge" is not part of the open source definition. There are ways to charge for open source projects indirectly through dual licensing or limited features, while still complying with the official definition of open source. + +## Should I launch my own open source project? + +The short answer is yes, because no matter the outcome, launching your own project is a great way to learn how open source works. + +If you've never open sourced a project before, you might be nervous about what people will say, or whether anyone will notice at all. If this sounds like you, you're not alone! + +Open source work is like any other creative activity, whether it's writing or painting. It can feel scary to share your work with the world, but the only way to get better is to practice - even if you don't have an audience. + +If you're not yet convinced, take a moment to think about what your goals might be. + +### Setting your goals + +Goals can help you figure out what to work on, what to say no to, and where you need help from others. Start by asking yourself, _why am I open sourcing this project?_ + +There is no one right answer to this question. You may have multiple goals for a single project, or different projects with different goals. + +If your only goal is to show off your work, you may not even want contributions, and even say so in your README. On the other hand, if you do want contributors, you'll invest time into clear documentation and making newcomers feel welcome. + + + +As your project grows, your community may need more than just code from you. Responding to issues, reviewing code, and evangelizing your project are all important tasks in an open source project. + +While the amount of time you spend on non-coding tasks will depend on the size and scope of your project, you should be prepared as a maintainer to address them yourself or find someone to help you. + +**If you're part of a company open sourcing a project,** make sure your project has the internal resources it needs to thrive. You'll want to identify who's responsible for maintaining the project after launch, and how you'll share those tasks with your community. + +If you need a dedicated budget or staffing for promotion, operations and maintaining the project, start those conversations early. + + + +### Contributing to other projects + +If your goal is to learn how to collaborate with others or understand how open source works, consider contributing to an existing project. Start with a project that you already use and love. Contributing to a project can be as simple as fixing typos or updating documentation. + +If you're not sure how to get started as a contributor, check out our [How to Contribute to Open Source guide](../how-to-contribute/). + +## Launching your own open source project + +There is no perfect time to open source your work. You can open source an idea, a work in progress, or after years of being closed source. + +Generally speaking, you should open source your project when you feel comfortable having others view, and give feedback on, your work. + +No matter which stage you decide to open source your project, every project should include the following documentation: + +* [Open source license](https://help.github.com/articles/open-source-licensing/#where-does-the-license-live-on-my-repository) +* [README](https://help.github.com/articles/create-a-repo/#commit-your-first-change) +* [Contributing guidelines](https://help.github.com/articles/setting-guidelines-for-repository-contributors/) +* [Code of conduct](../code-of-conduct/) + +As a maintainer, these components will help you communicate expectations, manage contributions, and protect everyone's legal rights (including your own). They significantly increase your chances of having a positive experience. + +If your project is on GitHub, putting these files in your root directory with the recommended filenames will help GitHub recognize and automatically surface them to your readers. + +### Choosing a license + +An open source license guarantees that others can use, copy, modify, and contribute back to your project without repercussions. It also protects you from sticky legal situations. **You must include a license when you launch an open source project.** + +Legal work is no fun. The good news is that you can copy and paste an existing license into your repository. It will only take a minute to protect your hard work. + +[MIT](https://choosealicense.com/licenses/mit/), [Apache 2.0](https://choosealicense.com/licenses/apache-2.0/), and [GPLv3](https://choosealicense.com/licenses/gpl-3.0/) are the most popular open source licenses, but [there are other options](https://choosealicense.com) to choose from. + +When you create a new project on GitHub, you are given the option to select a license. Including an open source license will make your GitHub project open source. + +![pick a license](/assets/images/starting-a-project/repository-license-picker.png) + +If you have other questions or concerns around the legal aspects of managing an open source project, [we've got you covered](../legal/). + +### Writing a README + +READMEs do more than explain how to use your project. They also explain why your project matters, and what your users can do with it. + +In your README, try to answer the following questions: + +* What does this project do? +* Why is this project useful? +* How do I get started? +* Where can I get more help, if I need it? + +You can use your README to answer other questions, like how you handle contributions, what the goals of the project are, and information about licenses and attribution. If you don't want to accept contributions, or your project is not yet ready for production, write this information down. + + + +Sometimes, people avoid writing a README because they feel like the project is unfinished, or they don't want contributions. These are all very good reasons to write one. + +For more inspiration, try using @18F's ["Making READMEs Readable"](https://pages.18f.gov/open-source-guide/making-readmes-readable/) or @PurpleBooth's [README template](https://gist.github.com/PurpleBooth/109311bb0361f32d87a2) to write a complete README. + +When you include a README file in the root directory, GitHub will automatically display it on the repository homepage. + +### Writing your contributing guidelines + +A CONTRIBUTING file tells your audience how to participate in your project. For example, you might include information on: + +* How to file a bug report (try using [issue and pull request templates](https://github.com/blog/2111-issue-and-pull-request-templates)) +* How to suggest a new feature +* How to set up your environment and run tests + +In addition to technical details, a CONTRIBUTING file is an opportunity to communicate your expectations for contributions, such as: + +* The types of contributions you're looking for +* Your roadmap or vision for the project +* How contributors should (or should not) get in touch with you + +Using a warm, friendly tone and offering specific suggestions for contributions (such as writing documentation, or making a website) can go a long way in making newcomers feel welcomed and excited to participate. + +For example, [Active Admin](https://github.com/activeadmin/activeadmin/) starts [its contributing guide](https://github.com/activeadmin/activeadmin/blob/master/CONTRIBUTING.md) with: + +> First off, thank you for considering contributing to Active Admin. It's people like you that make Active Admin such a great tool. + +In the earliest stages of your project, your CONTRIBUTING file can be simple. You should always explain how to report bugs or file issues, and any technical requirements (like tests) to make a contribution. + +Over time, you might add other frequently asked questions to your CONTRIBUTING file. Writing down this information means fewer people will ask you the same questions over and over again. + +For more help with writing your CONTRIBUTING file, check out @nayafia's [contributing guide template](https://github.com/nayafia/contributing-template/blob/master/CONTRIBUTING-template.md) or @mozilla's ["How to Build a CONTRIBUTING.md"](http://mozillascience.github.io/working-open-workshop/contributing/). + +Link to your CONTRIBUTING file from your README, so more people see it. If you [place the CONTRIBUTING file in your project's repository](https://help.github.com/articles/setting-guidelines-for-repository-contributors/), GitHub will automatically link to your file when a contributor creates an issue or opens a pull request. + +![contributing guidelines](/assets/images/starting-a-project/Contributing-guidelines.jpg) + +### Establishing a code of conduct + + + +Finally, a code of conduct helps set ground rules for behavior for your project's participants. This is especially valuable if you're launching an open source project for a community or company. A code of conduct empowers you to facilitate healthy, constructive community behavior, which will reduce your stress as a maintainer. + +For more information, check out our [Code of Conduct guide](../code-of-conduct/). + +In addition to communicating _how_ you expect participants to behave, a code of conduct also tends to describe who these expectations apply to, when they apply, and what to do if a violation occurs. + +Much like open source licenses, there are also emerging standards for codes of conduct, so you don't have to write your own. The [Contributor Covenant](http://contributor-covenant.org/) is a drop-in code of conduct that is used by [over 40,000 open source projects](http://contributor-covenant.org/adopters/), including Kubernetes, Rails, and Swift. No matter which text you use, you should be prepared to enforce your code of conduct when necessary. + +Paste the text directly into a CODE_OF_CONDUCT file in your repository. Keep the file in your project's root directory so it's easy to find, and link to it from your README. + +## Naming and branding your project + +Branding is more than a flashy logo or catchy project name. It's about how you talk about your project, and who you reach with your message. + +### Choosing the right name + +Pick a name that is easy to remember and, ideally, gives some idea of what the project does. For example: + +* [Sentry](https://github.com/getsentry/sentry) monitors apps for crash reporting +* [Thin](https://github.com/macournoyer/thin) is a fast and simple Ruby web server + +If you're building upon an existing project, using their name as a prefix can help clarify what your project does (ex. [node-fetch](https://github.com/bitinn/node-fetch) brings `window.fetch` to Node.js). + +Consider clarity above all. Puns are fun, but remember that some jokes might not translate to other cultures or people with different experiences from you. Some of your potential users might be company employees: you don't want to make them uncomfortable when they have to explain your project at work! + +### Avoiding name conflicts + +[Check for open source projects with a similar name](http://ivantomic.com/projects/ospnc/), especially if you share the same language or ecosystem. If your name overlaps with a popular existing project, you might confuse your audience. + +If you want a website, Twitter handle, or other properties to represent your project, make sure you can get the names you want. Ideally, [reserve those names now](https://instantdomainsearch.com/) for peace of mind, even if you don't intend to use them just yet. + +Make sure that your project's name doesn't infringe upon any trademarks. A company might ask you to take down your project later on, or even take legal action against you. It's just not worth the risk. + +You can check the [WIPO Global Brand Database](http://www.wipo.int/branddb/en/) for trademark conflicts. If you're at a company, this is one of the things your [legal team can help you with](../legal/). + +Finally, do a quick Google search for your project name. Will people be able to easily find your project? Does something else appear in the search results that you wouldn't want them to see? + +### How you write (and code) affects your brand, too! + +Throughout the life of your project, you'll do a lot of writing: READMEs, tutorials, community documents, responding to issues, maybe even newsletters and mailing lists. + +Whether it's official documentation or a casual email, your writing style is part of your project's brand. Consider how you might come across to your audience and whether that is the tone you wish to convey. + + + +Using warm, inclusive language (such as "them", even when referring to the single person) can go a long way in making your project feel welcoming to new contributors. Stick to simple language, as many of your readers may not be native English speakers. + +Beyond how you write words, your coding style may also become part of your project's brand. [Angular](https://github.com/johnpapa/angular-styleguide) and [jQuery](http://contribute.jquery.org/style-guide/js/) are two examples of projects with rigorous coding styles and guidelines. + +It isn't necessary to write a style guide for your project when you're just starting out, and you may find that you enjoy incorporating different coding styles into your project anyway. But you should anticipate how your writing and coding style might attract or discourage different types of people. The earliest stages of your project are your opportunity to set the precedent you wish to see. + +## Your pre-launch checklist + +Ready to open source your project? Here's a checklist to help. Check all the boxes? You're ready to go! [Click "publish"](https://help.github.com/articles/making-a-private-repository-public/) and pat yourself on the back. + +**Documentation** + +
+ + +
+ +
+ + +
+ +
+ + +
+ +
+ + +
+ +**Code** + +
+ + +
+ +
+ + +
+ +
+ + +
+ +**People** + +If you're an individual: + +
+ + +
+ +If you're a company or organization: + +
+ + +
+ +
+ + +
+ +
+ + +
+ +
+ + +
+ +## You did it! + +Congratulations on open sourcing your first project. No matter the outcome, working in public is a gift to the community. With every commit, comment, and pull request, you're creating opportunities for yourself and for others to learn and grow. From ec4aa56e9a3d644a24174907345189cfdfb890d7 Mon Sep 17 00:00:00 2001 From: LiJiansheng Date: Mon, 6 Mar 2017 11:42:11 +0800 Subject: [PATCH 005/156] translated description of all articles. Signed-off-by: LiJiansheng --- _articles/zh-CN/best-practices.md | 18 +++++++------- _articles/zh-CN/building-community.md | 14 +++++------ _articles/zh-CN/code-of-conduct.md | 2 +- _articles/zh-CN/getting-paid.md | 2 +- _articles/zh-CN/how-to-contribute.md | 26 ++++++++++---------- _articles/zh-CN/leadership-and-governance.md | 2 +- _articles/zh-CN/legal.md | 2 +- _articles/zh-CN/metrics.md | 2 +- _articles/zh-CN/starting-a-project.md | 23 ++++++++--------- 9 files changed, 46 insertions(+), 45 deletions(-) diff --git a/_articles/zh-CN/best-practices.md b/_articles/zh-CN/best-practices.md index b84eb9624f2..5a933b5cdbd 100644 --- a/_articles/zh-CN/best-practices.md +++ b/_articles/zh-CN/best-practices.md @@ -1,20 +1,20 @@ --- locale: zh-CN title: 维护者最佳实践 -description: Making your life easier as an open source maintainer, from documenting processes to leveraging your community. +description: 身为开源的维护者，如何轻松驾驭项目？本指南从文档流程到有效利用社区来展开。 class: best-practices toc: - what-does-it-mean-to-be-a-maintainer: "What does it mean to be a maintainer?" - documenting-your-processes: "Documenting your processes" - learning-to-say-no: "Learning to say no" - leverage-your-community: "Leverage your community" + what-does-it-mean-to-be-a-maintainer: "身为一名维护者意味着什么？" + documenting-your-processes: "将流程撰文档化" + learning-to-say-no: "学会拒绝他人" + leverage-your-community: "有效利用社区" bring-in-the-robots: "Bring in the robots" its-okay-to-hit-pause: "It’s okay to hit pause" order: 5 image: /assets/images/cards/best-practices.png --- -## What does it mean to be a maintainer? +## 身为一名维护者意味着什么？ If you maintain an open source project that a lot of people use, you may have noticed you're coding less and responding to issues more. @@ -22,7 +22,7 @@ In the early stages of a project, you're experimenting with new ideas and making Maintaining a project requires more than code. These tasks are often unexpected, but they're just as important to a growing project. We've gathered a few ways to make your life easier, from documenting processes to leveraging your community. -## Documenting your processes +## 将流程撰文档化 Writing things down is one of the most important things you can do as a maintainer. @@ -77,7 +77,7 @@ If you meet with other maintainers, or make a major decision in private, documen That way, anybody who joins your community will have access to the same information as someone who's been there for years. -## Learning to say no +## 学会拒绝他人 You've written things down. Ideally, everybody would read your documentation, but in reality, you'll have to remind others that this knowledge exists. @@ -159,7 +159,7 @@ Maybe someone in your community regularly submits contributions that don't meet If you see that someone is enthusiastic about your project, but needs a bit of polish, be patient. Explain clearly in each situation why their contributions don't meet the expectations of the project. Try pointing them to an easier or less ambiguous task, like an issue marked _"good first bug,"_ to get their feet wet. If you have time, consider mentoring them through their first contribution, or find someone else in your community who might be willing to mentor them. -## Leverage your community +## 有效利用社区 You don't have to do everything yourself. Your project's community exists for a reason! Even if you don't yet have an active contributor community, if you have a lot of users, put them to work. diff --git a/_articles/zh-CN/building-community.md b/_articles/zh-CN/building-community.md index b7843b58304..aa72e9a109c 100644 --- a/_articles/zh-CN/building-community.md +++ b/_articles/zh-CN/building-community.md @@ -1,17 +1,17 @@ --- locale: zh-CN title: 打造受欢迎的社区 -description: Building a community that encourages people to use, contribute to, and evangelize your project. +description: 打造人们愿意使用、贡献、并主动宣传的人气社区。 class: building toc: - setting-your-project-up-for-success: "Setting your project up for success" - growing-your-community: "Growing your community" - resolving-conflicts: "Resolving conflicts" + setting-your-project-up-for-success: "设置项目" + growing-your-community: "社区生长" + resolving-conflicts: "解决冲突" order: 4 image: /assets/images/cards/building.png --- -## Setting your project up for success +## 设置项目 You've launched your project, you're spreading the word, and people are checking it out. Awesome! Now, how do you get them to stick around? @@ -103,7 +103,7 @@ Public communication can be as simple as directing people to open an issue inste Notable exceptions to public communication are: 1) security issues and 2) sensitive code of conduct violations. You should always have a way for people to report these issues privately. If you don't want to use your personal email, set up a dedicated email address. -## Growing your community +## 社区生长 Communities are extremely powerful. That power can be a blessing or a curse, depending on how you wield it. As your project's community grows, there are ways to help it become a force of construction, not destruction. @@ -181,7 +181,7 @@ While you may not always find someone to answer the call, putting a signal out t

-## Resolving conflicts +## 解决冲突 In the early stages of your project, making major decisions is easy. When you want to do something, you just do it. diff --git a/_articles/zh-CN/code-of-conduct.md b/_articles/zh-CN/code-of-conduct.md index aee84181e68..1d5c2b21b96 100644 --- a/_articles/zh-CN/code-of-conduct.md +++ b/_articles/zh-CN/code-of-conduct.md @@ -1,7 +1,7 @@ --- locale: zh-CN title: 行为准则 -description: Facilitate healthy and constructive community behavior by adopting and enforcing a code of conduct. +description: 社区的长远发展和健康成长，离不开一些行为准则，需要遵守并执行。 class: coc toc: why-do-i-need-a-code-of-conduct: "Why do I need a code of conduct?" diff --git a/_articles/zh-CN/getting-paid.md b/_articles/zh-CN/getting-paid.md index 3f3c57c53b7..fb0312e5779 100644 --- a/_articles/zh-CN/getting-paid.md +++ b/_articles/zh-CN/getting-paid.md @@ -1,7 +1,7 @@ --- locale: zh-CN title: 通过为开源工作获得报酬 -description: Sustain your work in open source by getting financial support for your time or your project. +description: 为了让你能够持续的为开源项目，理应得到相应的经济上的报酬。 class: getting-paid toc: why-some-people-seek-financial-support: "Why some people seek financial support" diff --git a/_articles/zh-CN/how-to-contribute.md b/_articles/zh-CN/how-to-contribute.md index c0eeb47edf8..cb10ef221fc 100644 --- a/_articles/zh-CN/how-to-contribute.md +++ b/_articles/zh-CN/how-to-contribute.md @@ -1,20 +1,20 @@ --- locale: zh-CN title: 如何为开源做贡献 -description: Want to contribute to open source? A guide to making open source contributions, for first-timers and for veterans. +description: 想为开源贡献力量？本指南针为“菜鸟”和初学者而准备！ class: contribute toc: - why-contribute-to-open-source: "Why contribute to open source?" - what-it-means-to-contribute: "What it means to contribute" - orienting-yourself-to-a-new-project: "Orienting yourself to a new project" - finding-a-project-to-contribute-to: "Finding a project to contribute to" - how-to-submit-a-contribution: "How to submit a contribution" - what-happens-after-you-submit-a-contribution: "What happens after you submit a contribution" + why-contribute-to-open-source: "为何要为开源贡献力量？" + what-it-means-to-contribute: "贡献的具体含义是什么" + orienting-yourself-to-a-new-project: "根据项目定位自我" + finding-a-project-to-contribute-to: "寻找打算做贡献的项目" + how-to-submit-a-contribution: "如何提交成果" + what-happens-after-you-submit-a-contribution: "在提交完之后需要善后事宜" order: 1 image: /assets/images/cards/contribute.png --- -## Why contribute to open source? +## 为何要为开源贡献力量？ -### Do you like planning events? +### 是否热衷于规划事件？ * Organize workshops or meetups about the project, [like @fzamperin did for NodeSchool](https://github.com/nodeschool/organizers/issues/406) * Organize the project's conference (if they have one) * Help community members find the right conferences and submit proposals for speaking -### Do you like to design? +### 是否偏向于设计？ * Restructure layouts to improve the project's usability * Conduct user research to reorganize and refine the project's navigation or menus * Put together a style guide to help the project have a consistent visual design * Create art for t-shirts or a new logo, [like hapi.js's contributors did](https://github.com/hapijs/contrib/issues/68) -### Do you like to write? +### 你是否热衷于写作？ -* Write and improve the project's documentation +* 撰写和改进项目的文档 * Curate a folder of examples showing how the project is used * Start a newsletter for the project, or curate highlights from the mailing list * Write tutorials for the project, [like pypa's contributors did](https://github.com/pypa/python-packaging-user-guide/issues/194) @@ -109,36 +109,36 @@ Even if you are a developer, non-code contributions are a great way to get invol

-### Do you like organizing? +### 你喜欢组织活动吗？ * Link to duplicate issues, and suggest new issue labels, to keep things organized * Go through open issues and suggest closing old ones, [like @nzakas did for eslint](https://github.com/eslint/eslint/issues/6765) * Ask clarifying questions on recently opened issues to move the discussion forward -### Do you like to code? +### 享受编码的乐趣？ * Find an open issue to tackle, [like @dianjin did for Leaflet](https://github.com/Leaflet/Leaflet/issues/4528#issuecomment-216520560) * Ask if you can help write a new feature * Automate project setup * Improve tooling and testing -### Do you like helping people? +### 热衷于帮助他人？ * Answer questions about the project on e.g., Stack Overflow ([like this Postgres example](http://stackoverflow.com/questions/18664074/getting-error-peer-authentication-failed-for-user-postgres-when-trying-to-ge)) or reddit * Answer questions for people on open issues * Help moderate the discussion boards or conversation channels -### Do you like helping others code? +### 在编码方面是否喜欢帮助他人？ * Review code on other people's submissions * Write tutorials for how a project can be used * Offer to mentor another contributor, [like @ereichert did for @bronzdoc on Rust](https://github.com/rust-lang/book/issues/123#issuecomment-238049666) -### You don't just have to work on software projects! +### 其实不必一定是软件项目！ While "open source" often refers to software, you can collaborate on just about anything. There are books, recipes, lists, and classes that get developed as open source projects. -For example: +举例来说： * @sindresorhus curates a [list of "awesome" lists](https://github.com/sindresorhus/awesome) * @h5bp maintains a [list of potential interview questions](https://github.com/h5bp/Front-end-Developer-Interview-Questions) for front-end developer candidates @@ -160,9 +160,9 @@ For anything more than a typo fix, contributing to open source is like walking u Before jumping in blindly with your own suggestions, start by learning how to read the room. Doing so increases the chances that your ideas will be noticed and heard. -### Anatomy of an open source project +### 分析感兴趣的开源项目 -Every open source community is different. +每一个开源社区都是不一样的。 Spending years on one open source project means you've gotten to know one open source project. Move to a different project, and you might find the vocabulary, norms, and communication styles are completely different. @@ -170,11 +170,11 @@ That said, many open source projects follow a similar organizational structure. A typical open source project has the following types of people: -* **Author:** The person/s or organization that created the project -* **Owner:** The person/s who has administrative ownership over the organization or repository (not always the same as the original author) -* **Maintainers:** Contributors who are responsible for driving the vision and managing the organizational aspects of the project. (They may also be authors or owners of the project.) -* **Contributors:** Everyone who has contributed something back to the project. -* **Community Members:** People who use the project. They might be active in conversations or express their opinion on the project's direction. +* **作者:** The person/s or organization that created the project +* **归属者:** The person/s who has administrative ownership over the organization or repository (not always the same as the original author) +* **维护者:** Contributors who are responsible for driving the vision and managing the organizational aspects of the project. (They may also be authors or owners of the project.) +* **贡献者:** Everyone who has contributed something back to the project. +* **社区成员:** People who use the project. They might be active in conversations or express their opinion on the project's direction. Bigger projects may also have subcommittees or working groups focused on different tasks, such as tooling, triage, community moderation, and event organizing. Look on a project's website for a "team" page, or in the repository for governance documentation, to find this information. @@ -221,7 +221,7 @@ You can also use one of the following resources to help you discover new project * [Up For Grabs](http://up-for-grabs.net/) * [Contributor-ninja](https://contributor.ninja) -### A checklist before you contribute +### 提交贡献之前应做的检查列表 When you've found a project you'd like to contribute to, do a quick scan to make sure that the project is suitable for accepting contributions. Otherwise, your hard work may never get a response. @@ -379,7 +379,7 @@ A project that is friendly and welcoming signals that they will be receptive to You've found a project you like, and you're ready to make a contribution. Finally! Here's how to get your contribution in the right way. -### Communicating effectively +### 有效沟通 Whether you're a one-time contributor or trying to join a community, working with others is one of the most important skills you'll develop in open source. @@ -431,7 +431,7 @@ Before you open an issue or pull request, or ask a question in chat, keep these **Above all, keep it classy.** Open source is made up of collaborators from all over the world. Context gets lost across languages, cultures, geographies, and time zones. In addition, written communication makes it harder to convey a tone or mood. Assume good intentions in these conversations. It's fine to politely push back on an idea, ask for more context, or further clarify your position. Just try to leave the internet a better place than when you found it. -### Gathering context +### 收集上下文 Before doing anything, do a quick check to make sure your idea hasn't been discussed elsewhere. Skim the project's README, issues (open and closed), mailing list, and Stack Overflow. You don't have to spend hours going through everything, but a quick search for a few key terms goes a long way. @@ -453,7 +453,7 @@ If you want to make a substantial contribution, open an issue to ask before work

-### Opening an issue +### 创建 issue You should usually open an issue in the following situations: @@ -467,7 +467,7 @@ Tips for communicating on issues: * **If an issue was opened awhile ago,** it's possible that it's being addressed somewhere else, or has already been resolved, so comment to ask for confirmation before starting work. * **If you opened an issue, but figured out the answer later on your own,** comment on the issue to let people know, then close the issue. Even documenting that outcome is a contribution to the project. -### Opening a pull request +### 创建 pull request You should usually open a pull request in the following situations: @@ -491,9 +491,9 @@ If this is your first pull request, check out [Make a Pull Request](http://makea You did it! Congratulations on becoming an open source contributor. We hope it's the first of many. -After you submit a contribution, one of the following will happen: +在你提交了贡献之后，下面集中情形中的某种是可能发生的： -### 😭 You don't get a response. +### 😭 没有人响应你。 Hopefully you [checked the project for signs of activity](#a-checklist-before-you-contribute) before making a contribution. Even on an active project, however, it's possible that your contribution won't get a response. @@ -503,7 +503,7 @@ If you haven't gotten a response in over a week, it's fair to politely respond i If you make a polite bump and still nobody responds, it's possible that nobody will respond, ever. It's not a great feeling, but don't let that discourage you. It's happened to everyone! There are many possible reasons why you didn't get a response, including personal circumstances that may be out of your control. Try to find another project or way to contribute. If anything, this is a good reason not to invest too much time in making a contribution before other community members are engaged and responsive. -### 🚧 Someone requests changes to your contribution. +### 🚧 其他人的要求变更了你的贡献。 It's common that you'll be asked to make changes to your contribution, whether that's feedback on the scope of your idea, or changes to your code. @@ -511,14 +511,14 @@ When someone requests changes, be responsive. They've taken the time to review y If you don't have time to work on the issue anymore (for example, if the conversation has been going on for months, and your circumstances have changed), let the maintainer know so they're not expecting a response. Someone else may be happy to take over. -### 👎 Your contribution doesn't get accepted. +### 👎 你的贡献没有获得通过。 Your contribution may or may not be accepted in the end. Hopefully you didn't put too much work into it already. If you're not sure why it wasn't accepted, it's perfectly reasonable to ask the maintainer for feedback and clarification. Ultimately, however, you'll need to respect that this is their decision. Don't argue or get hostile. You're always welcome to fork and work on your own version if you disagree! -### 🎉 Your contribution gets accepted. +### 🎉 你的贡献被接收。 Hooray! You've successfully made an open source contribution! -## You did it! +## 你已经做到了! Whether you just made your first open source contribution, or you're looking for new ways to contribute, we hope you're inspired to take action. Even if your contribution wasn't accepted, don't forget to say thanks when a maintainer put effort into helping you. Open source is made by people like you: one issue, pull request, comment, or high-five at a time. From 12999047ee1a1f63d2055106caf8ea3d7ae492f1 Mon Sep 17 00:00:00 2001 From: LiJiansheng Date: Thu, 9 Mar 2017 06:23:53 +0800 Subject: [PATCH 007/156] fix merged error of file _config.yml. Signed-off-by: LiJiansheng --- _config.yml | 5 ----- 1 file changed, 5 deletions(-) diff --git a/_config.yml b/_config.yml index 34c73256929..992ea8404aa 100644 --- a/_config.yml +++ b/_config.yml @@ -1,4 +1,3 @@ -<<<<<<< HEAD title: "开源指南" description: "为开放源代码的初学者提供的向导，基于社区合著的形式存在。" @@ -7,10 +6,6 @@ translations: - locale: zh-CN name: 简体中文 (zh-CN) repository: github/open-source-guide -======= -title: "Open Source Guides" -description: "Learn how to launch and grow your project." ->>>>>>> upstream/gh-pages exclude: - bin From 81cbddf55d92b7c864c59675c89f469be96a8232 Mon Sep 17 00:00:00 2001 From: LiJiansheng Date: Thu, 9 Mar 2017 17:06:22 +0800 Subject: [PATCH 008/156] translated chapte of how-to-contribute. Signed-off-by: LiJiansheng --- _articles/zh-CN/how-to-contribute.md | 91 ++++++++++++++-------------- 1 file changed, 46 insertions(+), 45 deletions(-) diff --git a/_articles/zh-CN/how-to-contribute.md b/_articles/zh-CN/how-to-contribute.md index dcb8f0622b3..36ef411e248 100644 --- a/_articles/zh-CN/how-to-contribute.md +++ b/_articles/zh-CN/how-to-contribute.md @@ -82,9 +82,9 @@ Even if you are a developer, non-code contributions are a great way to get invol ### 是否热衷于规划事件？ -* Organize workshops or meetups about the project, [like @fzamperin did for NodeSchool](https://github.com/nodeschool/organizers/issues/406) -* Organize the project's conference (if they have one) -* Help community members find the right conferences and submit proposals for speaking +* 为项目组织研讨会或线下分享，[一如 @fzamperin 为 NodeSchool 所做的那样](https://github.com/nodeschool/organizers/issues/406) +* 为项目组织大型会议（假如它有的话） +* 帮助社区成员寻找合适的技术会议，且帮助有实力的成员提交演讲的拟稿 ### 是否偏向于设计？ @@ -130,35 +130,35 @@ Even if you are a developer, non-code contributions are a great way to get invol ### 在编码方面是否喜欢帮助他人？ -* Review code on other people's submissions -* Write tutorials for how a project can be used -* Offer to mentor another contributor, [like @ereichert did for @bronzdoc on Rust](https://github.com/rust-lang/book/issues/123#issuecomment-238049666) +* 为他人的提交审核代码 +* 为如何利用项目撰写教程 +* 为其他贡献者做导师， [正如 @ereichert 为 @bronzdoc 所做的那样，哦，是 Rust 项目](https://github.com/rust-lang/book/issues/123#issuecomment-238049666) ### 其实不必一定是软件项目！ -While "open source" often refers to software, you can collaborate on just about anything. There are books, recipes, lists, and classes that get developed as open source projects. +尽管人们一提起“开源”二字，默认就是指开源软件，其实不尽然，开源可以是任何事情的修饰，而不仅仅是指软件而言的。比如图书、食谱、列表、以及任何可以开源的项目类。 举例来说： -* @sindresorhus curates a [list of "awesome" lists](https://github.com/sindresorhus/awesome) -* @h5bp maintains a [list of potential interview questions](https://github.com/h5bp/Front-end-Developer-Interview-Questions) for front-end developer candidates -* @stuartlynn and @nicole-a-tesla made a [collection of fun facts about puffins](https://github.com/stuartlynn/puffin_facts) +* @sindresorhus 创建了 ["惊奇" 列表](https://github.com/sindresorhus/awesome) +* @h5bp 维护了针对前端开发者的[面试题](https://github.com/h5bp/Front-end-Developer-Interview-Questions) +* @stuartlynn 和 @nicole-a-tesla 制作了[收集关于海雀的有趣的事实](https://github.com/stuartlynn/puffin_facts) -Even if you're a software developer, working on a documentation project can help you get started in open source. It's often less intimidating to work on projects that don't involve code, and the process of collaboration will build your confidence and experience. +尽管你是一名软件开发者，也可以去撰写一些文档去帮助新的入门者。其实项目中那些看起来令人生畏的项目并不是写代码，做开发者总得挑战自己，其实在做得过程中可以增强信心和获得全新的体验。 ## 根据项目定位自我 -For anything more than a typo fix, contributing to open source is like walking up to a group of strangers at a party. If you start talking about llamas, while they were deep in a discussion about goldfish, they'll probably look at you a little strangely. +为开源做贡献，除了单词拼写错误之外，大多数时候就像是走在陌生人中间，浑身上下不适。这就像人们已经在西边讨论的非常深入了，你突然开始讲东，肯定会让人感到不舒服。 -Before jumping in blindly with your own suggestions, start by learning how to read the room. Doing so increases the chances that your ideas will be noticed and heard. +与其盲目的在项目中游荡，不如静下心来学习规则。这样反而会让你的想法被注意到，也会有人听到你的声音。 ### 分析感兴趣的开源项目 @@ -211,15 +211,15 @@ You might scan a README and find a broken link or a typo. Or you're a new user a > [28% of casual contributions](http://www.igor.pro.br/publica/papers/saner2016.pdf) to open source are documentation, such as a typo fix, reformatting, or writing a translation. -You can also use one of the following resources to help you discover new projects: +你也可以利用如下列出的资源来找到合适的新项目： -* [GitHub Explore](https://github.com/explore/) +* [GitHub 探索](https://github.com/explore/) * [First Timers Only](http://www.firsttimersonly.com/) -* [Your First PR](https://yourfirstpr.github.io/) +* [你的第一个 PR](https://yourfirstpr.github.io/) * [CodeTriage](https://www.codetriage.com/) * [24 Pull Requests](https://24pullrequests.com/) * [Up For Grabs](http://up-for-grabs.net/) -* [Contributor-ninja](https://contributor.ninja) +* [像忍者一样贡献](https://contributor.ninja) ### 提交贡献之前应做的检查列表 @@ -227,143 +227,144 @@ When you've found a project you'd like to contribute to, do a quick scan to make Here's a handy checklist to evaluate whether a project is good for new contributors. -**Meets the definition of open source** +**符合开源的定义**
-**Project actively accepts contributions** +**项目被接收的提交活跃度** -Look at the commit activity on the master branch. On GitHub, you can see this information on a repository's homepage. +在主干上确认提交的活跃度。在GitHub上托管的开源项目，你可以在仓库主页上看到这些信息。
-Next, look at the project's issues. +接下来，就是看项目的 issue 数量。
-Now do the same for the project's pull requests. +同样再来看看 PR的情形。
-**Project is welcoming** +**项目的受欢迎程度** + +一个项目的友好程度和受欢迎意味着更能吸引新的贡献者。 -A project that is friendly and welcoming signals that they will be receptive to new contributors.
@@ -371,7 +372,7 @@ A project that is friendly and welcoming signals that they will be receptive to avatar Whenever you see a long thread, spot check responses from core developers coming late in the thread. Are they summarizing constructively, and taking steps to bring the thread to a decision while remaining polite? If you see a lot of flame wars going on, that's often a sign that energy is going into argument instead of into development.

-— @kfogel, [_Producing OSS_](http://producingoss.com/en/evaluating-oss-projects.html) +— @kfogel, [_开源软件生产力_](http://producingoss.com/en/evaluating-oss-projects.html)

From 188dbfb3e55fb69b43a17d538e97f5bbe8935008 Mon Sep 17 00:00:00 2001 From: LiJiansheng Date: Thu, 16 Mar 2017 22:24:12 +0800 Subject: [PATCH 009/156] update translated some paragraphs. Signed-off-by: LiJiansheng --- _articles/zh-CN/how-to-contribute.md | 34 ++++++++++++++-------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/_articles/zh-CN/how-to-contribute.md b/_articles/zh-CN/how-to-contribute.md index 36ef411e248..c9e23a0cc2d 100644 --- a/_articles/zh-CN/how-to-contribute.md +++ b/_articles/zh-CN/how-to-contribute.md @@ -38,7 +38,7 @@ image: /assets/images/cards/contribute.png ### 寻找导师，并且尝试帮助他人 -Working with others on a shared project means you'll have to explain how you do things, as well as ask other people for help. The acts of learning and teaching can be a fulfilling activity for everyone involved. +和他人共同在一个共享的项目下工作，这意味着需要向他人解释清楚自己是如何做的，同理，也需要向他人求助，询问别人是如何做的。相互学习和彼此教学对于每位参与者都能满载而归。 ### 在公众间建立你的声誉（职业口碑） @@ -46,37 +46,37 @@ Working with others on a shared project means you'll have to explain how you do ### 学习领导和管理的艺术 -Open source offers opportunities to practice leadership and management skills, such as resolving conflicts, organizing teams of people, and prioritizing work. +开源为实践领导力和管理技能提供了很好的机会，比如解决冲突、组织团队、工作的优先级排列。 ### 鼓励作出改变，哪怕改变是很微小的 -You don't have to become a lifelong contributor to enjoy participating in open source. Have you ever seen a typo on a website, and wished someone would fix it? On an open source project, you can do just that. Open source helps people feel agency over their lives and how they experience the world, and that in itself is gratifying. +在开源的世界里，作出贡献的不一定非得是花了很长时间拥有大量经验的人。你是否遇到过浏览某些网站发现有拼写错误，希望有人能修改它？其实，在开源的项目中，你只需要做就可以了。没有那么多的顾忌，开源让人们在很舒服的状态做事，而这才是这个世界应有的体验。 ## 贡献的具体含义是什么 -If you're a new open source contributor, the process can be intimidating. How do you find the right project? What if you don't know how to code? What if something goes wrong? +如果你是一名开源界的新手，可能会对贡献的流程心生畏惧。比如：该如何找到正确的项目？不懂编码又想参与怎么办？万一做错事情了怎么办？ -Not to worry! There are all sorts of ways to get involved with an open source project, and a few tips will help you get the most out of your experience. +其实没有关系的啦！条条大路通罗马，开源项目有太多的路径可以参与！以下是一些实用的技巧，帮助你快速的获得经验。 ### 你不具备编码的能力 -A common misconception about contributing to open source is that you need to contribute code. In fact, it's often the non-code parts of a project that are [most neglected or overlooked](https://github.com/blog/2195-the-shape-of-open-source). You'll do the project a _huge_ favor by offering to pitch in with non-code contributions! +对于为开源做贡献常见的误解就是：为开源做贡献必须得提交代码。事实上，代码固然重要，但是项目中不需编码的重要部分[经常被忽视](https://github.com/blog/2195-the-shape-of-open-source)。你若做了这部分，对于项目来说可是莫大的贡献，而这根本就不需要什么撰写代码！ -Even if you are a developer, non-code contributions are a great way to get involved with a project and meet other community members. Building those relationships will give you opportunities to work on other parts of the project. +即使你是以为开发者，非代码的贡献对于项目来说也是举足轻重的，尤其是对于社区的其他成员来说。用心维系这些关系能够让你有工作到项目其它部分的机会。 @@ -96,16 +96,16 @@ Even if you are a developer, non-code contributions are a great way to get invol ### 你是否热衷于写作？ * 撰写和改进项目的文档 -* Curate a folder of examples showing how the project is used -* Start a newsletter for the project, or curate highlights from the mailing list -* Write tutorials for the project, [like pypa's contributors did](https://github.com/pypa/python-packaging-user-guide/issues/194) -* Write a translation for the project's documentation +* 能够以实例来展示项目该如何使用的 +* 为项目撰写新闻稿，或者到邮件列表高调布道 +* 为项目撰写教程， [一如 pypa 的贡献者所做的](https://github.com/pypa/python-packaging-user-guide/issues/194) +* 翻译项目的文档为本土语言 From 53818c8f220c0ce2d052aa7c8a06172da4956625 Mon Sep 17 00:00:00 2001 From: jtr109 Date: Fri, 17 Mar 2017 00:18:57 +0800 Subject: [PATCH 010/156] complete translating the section 2 of how-to-contribute --- _articles/zh-CN/how-to-contribute.md | 30 +++++++++++++--------------- 1 file changed, 14 insertions(+), 16 deletions(-) diff --git a/_articles/zh-CN/how-to-contribute.md b/_articles/zh-CN/how-to-contribute.md index c9e23a0cc2d..fad639ccda1 100644 --- a/_articles/zh-CN/how-to-contribute.md +++ b/_articles/zh-CN/how-to-contribute.md @@ -87,11 +87,10 @@ image: /assets/images/cards/contribute.png * 帮助社区成员寻找合适的技术会议，且帮助有实力的成员提交演讲的拟稿 ### 是否偏向于设计？ - -* Restructure layouts to improve the project's usability -* Conduct user research to reorganize and refine the project's navigation or menus -* Put together a style guide to help the project have a consistent visual design -* Create art for t-shirts or a new logo, [like hapi.js's contributors did](https://github.com/hapijs/contrib/issues/68) +* 重新布置布局以提高项目的可用性 +* 进行用户研究以重新组织和完善项目的导航或菜单 +* 整理一个风格指南，以帮助项目有一致的视觉设计 +* 创建t恤的艺术或一个新的标志，[就像 hapi.js 的贡献者那样](https://github.com/hapijs/contrib/issues/68) ### 你是否热衷于写作？ @@ -110,23 +109,22 @@ image: /assets/images/cards/contribute.png ### 你喜欢组织活动吗？ - -* Link to duplicate issues, and suggest new issue labels, to keep things organized -* Go through open issues and suggest closing old ones, [like @nzakas did for eslint](https://github.com/eslint/eslint/issues/6765) -* Ask clarifying questions on recently opened issues to move the discussion forward +* 链接重复的问题，并建议新的问题标签，使事物井井有条 +* 通过开放的问题，并建议关闭旧的，[就像 @nzakas 为 eslint 做的](https://github.com/eslint/eslint/issues/6765) +* 把最近开放的问题阐述清晰，以推动讨论 ### 享受编码的乐趣？ -* Find an open issue to tackle, [like @dianjin did for Leaflet](https://github.com/Leaflet/Leaflet/issues/4528#issuecomment-216520560) -* Ask if you can help write a new feature -* Automate project setup -* Improve tooling and testing +* 找到一个开放的问题并解决它，[就像 @dianjin 为 Leaflet 做的](https://github.com/Leaflet/Leaflet/issues/4528#issuecomment-216520560) +* 想一想你是否可以帮忙写一个新的功能 +* 自动化项目设置 +* 改进工具和测试 ### 热衷于帮助他人？ -* Answer questions about the project on e.g., Stack Overflow ([like this Postgres example](http://stackoverflow.com/questions/18664074/getting-error-peer-authentication-failed-for-user-postgres-when-trying-to-ge)) or reddit -* Answer questions for people on open issues -* Help moderate the discussion boards or conversation channels +* 回答关于项目的问题，例如在 Stack Overflow（[像 Postgres 的这个示例](http://stackoverflow.com/questions/18664074/getting-error-peer-authentication-failed-for-user-postgres-when-to-ge)）或者 reddit 上 +* 为人们解答公开的问题 +* 帮助缓和讨论板或对话渠道 ### 在编码方面是否喜欢帮助他人？ From 5c5fa6b2fcec9b2139acbb8f06dda2852bc19bee Mon Sep 17 00:00:00 2001 From: jtr109 Date: Fri, 17 Mar 2017 20:47:23 +0800 Subject: [PATCH 011/156] translate a part of starting a project --- _articles/zh-CN/starting-a-project.md | 34 +++++++++++++-------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/_articles/zh-CN/starting-a-project.md b/_articles/zh-CN/starting-a-project.md index 6773e8e844a..574fb3caf3e 100644 --- a/_articles/zh-CN/starting-a-project.md +++ b/_articles/zh-CN/starting-a-project.md @@ -16,42 +16,42 @@ image: /assets/images/cards/beginner.png ## 什么是开源，为什么要开源 -So you're thinking about getting started with open source? Congratulations! The world appreciates your contribution. Let's talk about what open source is and why people do it. +所以你在考虑开始参与开源？恭喜！世界赞赏你的贡献。让我们来谈谈开源是什么，以及人们这样做。 ### What does "open source" mean? -When a project is open source, that means **anybody can view, use, modify, and distribute your project for any purpose.** These permissions are enforced through [an open source license](https://opensource.org/licenses). +当一个项目被开源，这意味着**任何人都可以出于任何目的查看，使用，修改和分发你的项目**。 这些权限通过[开源许可](https://opensource.org/licenses)强制实施。 -Open source is powerful because it lowers the barriers to adoption, allowing ideas to spread quickly. +开源是强大的，因为它降低了事物被采纳的障碍，允许想法迅速传播。 -To understand how it works, imagine your friend is having a potluck, and you bring a cherry pie. +要了解它的工作原理，想象你的朋友组织了一场聚餐，而你带去了一个樱桃派。 -* Everybody tries the pie (_use_) -* The pie is a hit! They ask you for the recipe, which you provide (_view_) -* One friend, Alex, who's a pastry chef, suggests reducing the sugar (_modify_) -* Another friend, Lisa, asks to use it for a dinner next week (_distribute_) +* 每个人都尝了那个派（_使用_) +* 派的味道棒极了！大家请你分享它的配方（_view_） +* 一个叫 Alex 的朋友是个糕点师，他建议少放点糖（_modify_） +* 一个叫 Lisa 的朋友想要用它作为下周的晚餐（_distribute_） -By comparison, a closed source process would be going to a restaurant and ordering a slice of cherry pie. You must pay a fee to eat the pie, and the restaurant probably won't give you their recipe. If you copied their pie exactly and sold it under your own name, the restaurant could take action against you. +相比之下，一个闭源过程就像去一家餐厅订购一个樱桃派。你必须为了吃饼支付费用，餐厅恐怕不会给你他们的食谱。如果你准确地复制了他们的馅饼，并以你自己的名义出售，餐厅可以对你采取措施。 -### Why do people open source their work? +### 人们为什么把他们的作品开源？ -[There are many reasons](http://ben.balter.com/2015/11/23/why-open-source/) why a person or organization would want to open source a project. Some examples include: +个人或组织为何想要开源一个项目，[有各种各样的的原因](http://ben.balter.com/2015/11/23/why-open-source/)，例如： -* **Collaboration:** Open source projects can accept changes from anybody in the world. [Exercism](https://github.com/exercism/), for example, is a programming exercise platform with over 350 contributors. +* **协作：** 开源项目可以接受世界各地人们的修改。 例如 [Exercism](https://github.com/exercism/) 就是一个拥有350多个贡献者的练习平台。 -* **Adoption and remixing:** Open source projects can be used by anyone for nearly any purpose. People can even use it to build other things. [WordPress](https://github.com/WordPress), for example, started as a fork of an existing project called [b2](https://github.com/WordPress/book/blob/master/Content/Part%201/2-b2-cafelog.md). +* **采用和重组：** 任何人几乎可以出于任何目的使用开源项目。人们甚至可以使用它来构建其他东西。例如，[WordPress](https://github.com/WordPress) 就是派生自一个名为 [b2](https://github.com/WordPress/book/blob/master/Content/Part%201/2-b2-cafelog.md) 的现有项目。 -* **Transparency:** Anyone can inspect an open source project for errors or inconsistencies. Transparency matters to governments like [Bulgaria](https://medium.com/@bozhobg/bulgaria-got-a-law-requiring-open-source-98bf626cf70a) or the [United States](https://sourcecode.cio.gov/), regulated industries like banking or healthcare, and security software like [Let's Encrypt](https://github.com/letsencrypt). +* **透明度：** 任何人都可以检查开源项目是否有错误或不一致。 透明度对[保加利亚](https://medium.com/@bozhobg/bulgaria-got-a-law-requiring-open-source-98bf626cf70a) 或[美国](https://sourcecode.cio.gov/)等政府，银行或医疗保健等受监管行业以及 [Let's Encrypt](https://github.com/letsencrypt) 等安全软件都很重要。 -Open source isn't just for software, either. You can open source everything from datasets to books. Check out [GitHub Explore](https://github.com/explore) for ideas on what else you can open source. +开源并不仅仅限于软件。您可以开源任何事物，从数据集到书本。查看 [GitHub Explore](https://github.com/explore) 开找找有什么是你可以开源的。 ### Does open source mean "free of charge"? From 5438d5b0e8723e11b37b39e2c52d9b4e49d9fb85 Mon Sep 17 00:00:00 2001 From: jtr109 Date: Mon, 20 Mar 2017 00:06:40 +0800 Subject: [PATCH 012/156] trans the section: Should I launch my own open source project? --- _articles/zh-CN/starting-a-project.md | 50 +++++++++++++-------------- 1 file changed, 25 insertions(+), 25 deletions(-) diff --git a/_articles/zh-CN/starting-a-project.md b/_articles/zh-CN/starting-a-project.md index 574fb3caf3e..a0520313b7b 100644 --- a/_articles/zh-CN/starting-a-project.md +++ b/_articles/zh-CN/starting-a-project.md @@ -18,7 +18,7 @@ image: /assets/images/cards/beginner.png 所以你在考虑开始参与开源？恭喜！世界赞赏你的贡献。让我们来谈谈开源是什么，以及人们这样做。 -### What does "open source" mean? +### “开源”是什么意思？ 当一个项目被开源，这意味着**任何人都可以出于任何目的查看，使用，修改和分发你的项目**。 这些权限通过[开源许可](https://opensource.org/licenses)强制实施。 @@ -53,61 +53,61 @@ image: /assets/images/cards/beginner.png 开源并不仅仅限于软件。您可以开源任何事物，从数据集到书本。查看 [GitHub Explore](https://github.com/explore) 开找找有什么是你可以开源的。 -### Does open source mean "free of charge"? +### 开源是指“免费”吗？ -One of open source's biggest draws is that it does not cost money. "Free of charge", however, is a byproduct of open source's overall value. +开源最大的吸引之一是它不花钱。 但是，“免费”只是开源的总体价值的一个副产品。 -Because [an open source license requires](https://opensource.org/osd-annotated) that anyone can use, modify, and share your project for nearly any purpose, projects themselves tend to be free of charge. If the project cost money to use, anyone could legally make a copy and use the free version instead. +因为[开源许可证要求](https://opensource.org/osd-annotated)任何人可以几乎出于任何目使用，修改和共享您的项目，项目本身往往是免费的。 如果该项目花钱使用，任何人也都可以合法地复制和使用免费版本。 -As a result, most open source projects are free, but "free of charge" is not part of the open source definition. There are ways to charge for open source projects indirectly through dual licensing or limited features, while still complying with the official definition of open source. +因此，大多数开源项目是免费的，但“免费”不是开源定义的一部分。 有些方法可以通过双重许可或有限功能间接地为开源项目收费，同时仍然遵守开源的官方定义。 -## 我有必要去发起开源项目? +## 我是否应该发起我自己的开源项目? -The short answer is yes, because no matter the outcome, launching your own project is a great way to learn how open source works. +简单来说，答案是肯定的，因为无论结果如何，启动您自己的项目来了解开源的工作原理是一个好方法。 -If you've never open sourced a project before, you might be nervous about what people will say, or whether anyone will notice at all. If this sounds like you, you're not alone! +如果你从来没有创建过一个项目，你可能会担心人们会说什么，或者是否有人会注意到。 如果这听起来像你现在的状态，别担心，你并不孤独！ -Open source work is like any other creative activity, whether it's writing or painting. It can feel scary to share your work with the world, but the only way to get better is to practice - even if you don't have an audience. +开源工作就像任何其他充满创意的活动，无论是写作还是绘画。 向世界分享你的作品会让你提心吊胆，但唯有练习能够让你的感觉变好的方法 - 即使你没有观众。 -If you're not yet convinced, take a moment to think about what your goals might be. +如果你还不确信，请花一点时间思考你的目标可能是什么。 -### Setting your goals +### 设置你的目标 -Goals can help you figure out what to work on, what to say no to, and where you need help from others. Start by asking yourself, _why am I open sourcing this project?_ +目标可以帮助你弄清该做什么，不应该说什么，以及你在哪方面需要其他人的帮助。 首先问自己，_我是为什么开源这个项目？_ -There is no one right answer to this question. You may have multiple goals for a single project, or different projects with different goals. +这个问题没有标准答案。 对于一个项目你可以有多个目标，或者具有不同目标的不同项目。 -If your only goal is to show off your work, you may not even want contributions, and even say so in your README. On the other hand, if you do want contributors, you'll invest time into clear documentation and making newcomers feel welcome. +如果你唯一的目标是炫耀你的工作，你甚至可能不需要他人的贡献，甚至在你的README中说明这点。但另一方面，如果你需要贡献者，你会投入时间来使文档清晰，好让新的参与者感到欢迎。 -As your project grows, your community may need more than just code from you. Responding to issues, reviewing code, and evangelizing your project are all important tasks in an open source project. +随着你的项目增长，你的社区可能不仅需要你的代码。回应问题，审查代码和传播你的项目都会成为开源项目中的重要任务。 -While the amount of time you spend on non-coding tasks will depend on the size and scope of your project, you should be prepared as a maintainer to address them yourself or find someone to help you. +而你在非编码的任务上花费的时间将取决于项目的大小和范围，你应该准备好作为维护者来自己解决或找人帮助你。 -**If you're part of a company open sourcing a project,** make sure your project has the internal resources it needs to thrive. You'll want to identify who's responsible for maintaining the project after launch, and how you'll share those tasks with your community. +**如果你是公司开源项目的一部分，**确保你的项目有它需要茁壮成长的内部资源。 你需要确定谁在启动后负责维护项目，以及如何与你的社区共享这些任务。 -If you need a dedicated budget or staffing for promotion, operations and maintaining the project, start those conversations early. +如果你需要专门的预算或人员来促进，操作和维护项目，请尽早提出。 -### Contributing to other projects +###加入其他项目 -If your goal is to learn how to collaborate with others or understand how open source works, consider contributing to an existing project. Start with a project that you already use and love. Contributing to a project can be as simple as fixing typos or updating documentation. +如果你的目标是学习如何与他人合作或了解开源的工作方式，请考虑为现有项目做出贡献。从你已经使用并喜欢的项目开始。像修复拼写错误或更新文档简单的事也能为项目做出贡献。 -If you're not sure how to get started as a contributor, check out our [How to Contribute to Open Source guide](../how-to-contribute/). +如果你不知道如何开始作为贡献者，请查看我们的[如何贡献开源指南](../how-to-contribute/)。 ## 发起自己的开源项目 From b3cf6dab1c18cc079cc94d5f79a87e85606a637d Mon Sep 17 00:00:00 2001 From: jtr109 Date: Mon, 20 Mar 2017 00:26:53 +0800 Subject: [PATCH 013/156] fix: fix some bugs because of syntax of markdown --- _articles/zh-CN/starting-a-project.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/_articles/zh-CN/starting-a-project.md b/_articles/zh-CN/starting-a-project.md index a0520313b7b..f6abef02b4d 100644 --- a/_articles/zh-CN/starting-a-project.md +++ b/_articles/zh-CN/starting-a-project.md @@ -77,7 +77,7 @@ image: /assets/images/cards/beginner.png 这个问题没有标准答案。 对于一个项目你可以有多个目标，或者具有不同目标的不同项目。 -如果你唯一的目标是炫耀你的工作，你甚至可能不需要他人的贡献，甚至在你的README中说明这点。但另一方面，如果你需要贡献者，你会投入时间来使文档清晰，好让新的参与者感到欢迎。 +如果你唯一的目标是炫耀你的工作，你甚至可能不需要他人的贡献，甚至在你的 README 中说明这点。但另一方面，如果你需要贡献者，你会投入时间来使文档清晰，好让新的参与者感到欢迎。 -###加入其他项目 +### 加入其他项目 如果你的目标是学习如何与他人合作或了解开源的工作方式，请考虑为现有项目做出贡献。从你已经使用并喜欢的项目开始。像修复拼写错误或更新文档简单的事也能为项目做出贡献。 From a5c91f11211d98f3abadfdec46a6d024050b075f Mon Sep 17 00:00:00 2001 From: LiJiansheng Date: Tue, 21 Mar 2017 22:10:11 +0800 Subject: [PATCH 014/156] translated how to contribute 3 parts. Signed-off-by: LiJiansheng --- _articles/zh-CN/how-to-contribute.md | 74 ++++++++++++++-------------- 1 file changed, 37 insertions(+), 37 deletions(-) diff --git a/_articles/zh-CN/how-to-contribute.md b/_articles/zh-CN/how-to-contribute.md index fad639ccda1..ac146b03405 100644 --- a/_articles/zh-CN/how-to-contribute.md +++ b/_articles/zh-CN/how-to-contribute.md @@ -162,52 +162,52 @@ image: /assets/images/cards/contribute.png 每一个开源社区都是不一样的。 -Spending years on one open source project means you've gotten to know one open source project. Move to a different project, and you might find the vocabulary, norms, and communication styles are completely different. +在某一个开源项目扎根多年，这意味着你只是对这一个开源项目无比的熟悉。若是切换到不同的项目，可能会发现完全是另外一回事，所谓的使用词汇、习惯用语、沟通方式都发生了变化。 -That said, many open source projects follow a similar organizational structure. Understanding the different community roles and overall process will help you get quickly oriented to any new project. +然而，很多的开源项目还是遵循类似的组织结构的。理解不同的社区角色和全部的流程，可以很好的帮助你快速的切入新的项目。 -A typical open source project has the following types of people: +一个典型的开源项目均会有如下类型的人： -* **作者:** The person/s or organization that created the project -* **归属者:** The person/s who has administrative ownership over the organization or repository (not always the same as the original author) -* **维护者:** Contributors who are responsible for driving the vision and managing the organizational aspects of the project. (They may also be authors or owners of the project.) -* **贡献者:** Everyone who has contributed something back to the project. -* **社区成员:** People who use the project. They might be active in conversations or express their opinion on the project's direction. +* **作者:** 项目的创始人或创始组织 +* **归属者:** 代码仓库或组织的管理员（不一定和作者是同一个人） +* **维护者:** 贡献者，负责项目的未来走向和组织的管理（他们通常也是项目的作者或归属者。） +* **贡献者:** 只要是为项目做出了贡献，就算。 +* **社区成员:** 那些实用项目的人们。他们或许是积极的讨论者，又或者是为项目的方向提出意见的人。 -Bigger projects may also have subcommittees or working groups focused on different tasks, such as tooling, triage, community moderation, and event organizing. Look on a project's website for a "team" page, or in the repository for governance documentation, to find this information. +一个较大的项目，可能下面还会细分子社区，或者是针对不同的任务分成不同的小组，比如工具小组、分流、社区事务、以及活动组织等。径直到项目到web站点，找到“团队”页面，或者是查看治理文档，从而获得类似到信息。 -A project also has documentation. These files are usually listed in the top level of a repository. +靠谱的开源项目，一般都会有一个文档的，这些文档文件通常会在代码仓库的顶级目录列出。 -* **LICENSE:** By definition, every open source project must have an [open source license](https://choosealicense.com). If the project does not have a license, it is not open source. -* **README:** The README is the instruction manual that welcomes new community members to the project. It explains why the project is useful and how to get started. -* **CONTRIBUTING:** Whereas READMES help people _use_ the project, contributing docs help people _contribute_ to the project. It explains what types of contributions are needed and how the process works. While not every project has a CONTRIBUTING file, its presence signals that this is a welcoming project to contribute to. -* **CODE_OF_CONDUCT:** The code of conduct sets ground rules for participants' behavior associated and helps to facilitate a friendly, welcoming environment. While not every project has a CODE_OF_CONDUCT file, its presence signals that this is a welcoming project to contribute to. -* **Other documentation:** There might be additional documentation, such as tutorials, walkthroughs, or governance policies, especially on bigger projects. +* **许可协议:** 根据开源软件的定义，每一个开源项目必须是有[开源许可协议](https://choosealicense.com)的. 可以这么认为：假如说某个项目源码开放，但是没有任何的许可协议，那么它就不能叫做开源。 +* **README:** README 是一个介绍性的说明文件，对初次光临社区对人们表示欢迎，它通常会解释项目有何用处，为何发起，以及如何快速入门等。 +* **贡献:** READMES 帮助人们来认识项目，贡献这个文件则是帮助对项目如何做贡献。它解释了目前项目需要什么样类型对贡献者，社区对流程是啥样的。并非所有的项目都会有这个文件，它某种程度上也是展示项目对于贡献者的友好程度。 +* **行为准则:** 顾名思义，即是一些参与社区时的一些礼仪、说话方式、行为等，帮助形成一种友好的氛围，不是所有的项目都会撰写行为准则文件，它某种程度上也是展示项目对于贡献者的友好程度。 +* **其它文档:** 有些项目也许还有其它文档，例如教程、导游，或者是治理规则，这在大型项目中常见。 -Finally, open source projects use the following tools to organize discussion. Reading through the archives will give you a good picture of how the community thinks and works. +此外，开源项目还会利用如下一些工具来进行组织讨论，阅读这些归档对于理解社区的想法、是如何工作的有非常大的作用。 -* **Issue tracker:** Where people discuss issues related to the project. -* **Pull requests:** Where people discuss and review changes that are in progress. -* **Discussion forums or mailing lists:** Some projects may use these channels for conversational topics (ex. _"How do I..."_ or _"What do you think about..."_ instead of bug reports or feature requests). Others use the issue tracker for all conversations. -* **Synchronous chat channel:** Some projects use chat channels (such as Slack or IRC) for casual conversation, collaboration, and quick exchanges. +* **问题追踪:** 这里是人们讨论项目相关问题的地方。 +* **Pull requests:** 审核代码、以及相关的问题讨论。 +* **论坛或邮件列表:** 一些项目会实用会话式的主题（例如 _"How do I..."_ 或 _"What do you think about..."_ 来替代Bug报告或特性请求）。然而有一些项目关于讨论全部实用问题追踪。 +* **即时在线聊天:** 有一些项目会实用聊天频道（诸如 Slack 或 IRC），从而能够随意的谈话、协作和快速交流。 ## 寻找打算做贡献的项目 -Now that you've figured out how open source projects work, it's time to find a project to contribute to! +你读到这里，说明已经对于一个开源项目如何运作的有了清晰的认识，是该找一个合适的项目做贡献的时候了！ -If you've never contributed to open source before, take some advice from U.S. President John F. Kennedy, who once said, _"Ask not what your country can do for you - ask what you can do for your country."_ +假如你之前从来都没有为开源做过贡献的话，那么请记住来自美国总统约翰 F.肯尼迪的这段话：**不要问你的国家能为你做什么，要问你能为国家做什么。** -Contributing to open source happens at all levels, across projects. You don't need to overthink what exactly your first contribution will be, or how it will look. +开源项目的方方面面都需要贡献者，你先不要通盘考虑该往哪里贡献，或者是它将如何看。 -Instead, start by thinking about the projects you already use, or want to use. The projects you'll actively contribute to are the ones you find yourself coming back to. +相反，从你已经使用到的或者打算用到项目开启贡献之路，在你积极的贡献过程中，项目也会反馈给你，让你更好的定位自己。 -Within those projects, whenever you catch yourself thinking that something could be better or different, act on your instinct. +一旦进入某项目，不论何时，你都要听从自己的直觉，做你认为更好或者不同的事情。 -Open source isn't an exclusive club; it's made by people just like you. "Open source" is just a fancy term for treating the world's problems as fixable. +开源并不是高级俱乐部；它就是由你这样的人所浇铸和打造。**“开源”只是针对这个世界的需要修复的问题的一个梦幻术语罢了。** -You might scan a README and find a broken link or a typo. Or you're a new user and you noticed something is broken, or an issue that you think should really be in the documentation. Instead of ignoring it and moving on, or asking someone else to fix it, see whether you can help out by pitching in. That's what open source is all about! +你或许在查看 README的时候，发现了损坏的链接，又或者拼写错误。又或者是你是一名新手，使用的过程中发现了问题，又或者是某问题应该在文档中注明。请不要坐视不理，径直绕开，或者是请求他人修复，伸出你的援助之手，解决这些你能看到的问题。而这正是开源的精髓之所在！ -> [28% of casual contributions](http://www.igor.pro.br/publica/papers/saner2016.pdf) to open source are documentation, such as a typo fix, reformatting, or writing a translation. +> [28% 的随意贡献](http://www.igor.pro.br/publica/papers/saner2016.pdf) 就是说明了文档的开源，诸如拼写错误，段落语句调整、或者是翻译。 你也可以利用如下列出的资源来找到合适的新项目： @@ -221,9 +221,9 @@ You might scan a README and find a broken link or a typo. Or you're a new user a ### 提交贡献之前应做的检查列表 -When you've found a project you'd like to contribute to, do a quick scan to make sure that the project is suitable for accepting contributions. Otherwise, your hard work may never get a response. +当你找到了你打算贡献的项目时，在进一步行动之前，作一个快速的扫描工作，以确保项目是否接受贡献的。否则，你煞费苦心的工作可能没有任何的回报。 -Here's a handy checklist to evaluate whether a project is good for new contributors. +这是一个简易的检查表，用来评估一个项目是否适合新的贡献者。 **符合开源的定义** @@ -368,7 +368,7 @@ Here's a handy checklist to evaluate whether a project is good for new contribut -## What are some of the common governance structures for open source projects? +## 对于开源项目来说有那些常见的治理结构？ There are three common governance structures associated with open source projects. @@ -112,7 +112,7 @@ Which one should you use? It's up to you! Every model has advantages and tradeof * [Meritocracy model template](http://oss-watch.ac.uk/resources/meritocraticgovernancemodel) * [Node.js's liberal contribution policy](https://medium.com/the-javascript-collection/healthy-open-source-967fa8be7951#.m9ht26e79) -## Do I need governance docs when I launch my project? +## 当我创建开源项目时，需要专门撰写一份治理文档吗？ There is no right time to write down your project's governance, but it's much easier to define once you've seen your community dynamics play out. The best (and hardest) part about open source governance is that it is shaped by the community! @@ -128,7 +128,7 @@ If you're part of a company launching an open source project, it's worth having

-## What happens if corporate employees start submitting contributions? +## 公司员工该如何开启提交贡献之旅？ Successful open source projects get used by many people and companies, and some companies may eventually have revenue streams eventually tied to the project. For example, a company may use the project's code as one component in a commercial service offering. @@ -140,7 +140,7 @@ It's important to treat commercial activity as normal and as just another source Like anyone else, commercially-motivated developers gain influence in the project through the quality and quantity of their contributions. Obviously, a developer who is paid for her time may be able to do more than someone who is not paid, but that's okay: payment is just one of many possible factors that could affect how much someone does. Keep your project discussions focused on the contributions, not on the external factors that enable people to make those contributions. -## Do I need a legal entity to support my project? +## 我是否需要一个法律实体来支持我的项目? You don't need a legal entity to support your open source project unless you're handling money. From 4041af08818cf9e0e187b58463e4137b450ef555 Mon Sep 17 00:00:00 2001 From: LiJiansheng Date: Sat, 25 Mar 2017 21:46:58 +0800 Subject: [PATCH 017/156] translated done how to contribute. great job. Signed-off-by: LiJiansheng --- _articles/zh-CN/getting-paid.md | 22 +++++++++++----------- _articles/zh-CN/how-to-contribute.md | 20 ++++++++++---------- 2 files changed, 21 insertions(+), 21 deletions(-) diff --git a/_articles/zh-CN/getting-paid.md b/_articles/zh-CN/getting-paid.md index fb0312e5779..4d7fcf1d53a 100644 --- a/_articles/zh-CN/getting-paid.md +++ b/_articles/zh-CN/getting-paid.md @@ -4,15 +4,15 @@ title: 通过为开源工作获得报酬 description: 为了让你能够持续的为开源项目，理应得到相应的经济上的报酬。 class: getting-paid toc: - why-some-people-seek-financial-support: "Why some people seek financial support" - funding-your-own-time: "Funding your own time" - finding-funding-for-your-project: "Finding funding for your project" - building-a-case-for-financial-support: "Building a case for financial support" + why-some-people-seek-financial-support: "为何会有人寻求经济上的支持" + funding-your-own-time: "你的时间是最宝贵的，理应得到资助" + finding-funding-for-your-project: "为你的项目寻找资助" + building-a-case-for-financial-support: "建立经济上的支持" order: 7 image: /assets/images/cards/getting-paid.png --- -## Why some people seek financial support +## 为何会有人寻求经济上的支持 Much of open source work is volunteered. For example, someone might come across a bug in a project they use and submit a quick fix, or they might enjoy tinkering with an open source project in their spare time. @@ -62,7 +62,7 @@ Paid work also enables people from different walks of life to make meaningful co If you're looking for financial support, there are two paths to consider. You can fund your own time as a contributor, or you can find organizational funding for the project. -## Funding your own time +## 你的时间是最宝贵的，理应得到资助 Today, many people get paid to work part- or full-time on open source. The most common way to get paid for your time is to talk to your employer. @@ -106,7 +106,7 @@ Finally, depending on your personal circumstances, you can try raising money ind * @gaearon funded his work on [Redux](https://github.com/reactjs/redux) through a [Patreon crowdfunding campaign](http://redux.js.org/) * @andrewgodwin funded work on Django schema migrations [through a Kickstarter campaign](https://www.kickstarter.com/projects/andrewgodwin/schema-migrations-for-django) -## Finding funding for your project +## 为你的项目寻找资助 Beyond arrangements for individual contributors, sometimes projects raise money from companies, individuals, or others to fund ongoing work. @@ -126,17 +126,17 @@ As open source's popularity increases, finding funding for projects is still exp For more detailed options and case studies, @nayafia [wrote a guide](https://github.com/nayafia/lemonade-stand) to getting paid for open source work. Different types of funding require different skills, so consider your strengths to figure out which option works best for you. -## Building a case for financial support +## 建立经济上的支持 Whether your project is a new idea, or has been around for years, you should expect to put significant thought into identifying your target funder and making a compelling case. Whether you're looking to pay for your own time, or fundraise for a project, you should be able to answer the following questions. -### Impact +### 影响 Why is this project useful? Why do your users, or potential users, like it so much? Where will it be in five years? -### Traction +### 牵引 Try to collect evidence that your project matters, whether it's metrics, anecdotes, or testimonials. Are there any companies or noteworthy people using your project right now? If not, has a prominent person endorsed it? @@ -160,7 +160,7 @@ Does the funder have any requirements around disbursal? For example, you may nee

-## Experiment and don't give up +## 尝试，不要放弃 Raising money isn't easy, whether you're an open source project, a nonprofit, or a software startup, and in most cases require you to get creative. Identifying how you want to get paid, doing your research, and putting yourself in your funder's shoes will help you build a convincing case for funding. diff --git a/_articles/zh-CN/how-to-contribute.md b/_articles/zh-CN/how-to-contribute.md index 54855d788c8..82954a8e2c5 100644 --- a/_articles/zh-CN/how-to-contribute.md +++ b/_articles/zh-CN/how-to-contribute.md @@ -490,29 +490,29 @@ image: /assets/images/cards/contribute.png 很不错，你做到了！恭贺你成为开源贡献者。我们希望这是一个良好的开端。 -在你提交了贡献之后，下面集中情形中的某种是可能发生的： +在你提交了贡献之后，下面几种情形中的某种是可能发生的： ### 😭 没有人响应你。 -Hopefully you [checked the project for signs of activity](#a-checklist-before-you-contribute) before making a contribution. Even on an active project, however, it's possible that your contribution won't get a response. +希望你确认在开始工作之前[检查过了项目的活跃度](#a-checklist-before-you-contribute)，不过即使检查过了，也不保证一个活跃的项目，没有人理会你的贡献也是很正常的。 -If you haven't gotten a response in over a week, it's fair to politely respond in that same thread, asking someone for a review. If you know the name of the right person to review your contribution, you can @-mention them in that thread. +如果过去了一周，依旧没有人响应，请心平气和的在后面跟帖，询求他人帮助你审核下。如果你熟悉某个人可以审核你的贡献，你可以使用@+名字，直接提醒他一下。 -**Don't** reach out to that person privately; remember that public communication is vital to open source projects. +**千万不要** 私下里去联系他人；一定要记住，开源项目所有的沟通都应该是公开的。 -If you make a polite bump and still nobody responds, it's possible that nobody will respond, ever. It's not a great feeling, but don't let that discourage you. It's happened to everyone! There are many possible reasons why you didn't get a response, including personal circumstances that may be out of your control. Try to find another project or way to contribute. If anything, this is a good reason not to invest too much time in making a contribution before other community members are engaged and responsive. +如果你做了所有该做的事情，还是没有人理你，那就是真的没有人对你的贡献做出响应。这可能感觉上不太好受，但是千万不要灰心。每个人都会遇到这样的情况。其实有太多种原因没有人响应你的提交了，包括很多个人情形都是不在你控制范围的。再接再厉，换一种方法去提交，或者换一个项目。这年头，很多社区成员都在积极的参与和响应他人，都在抢夺优秀的人才，若没有人搭理你，你换地方是没有任何不对的地方的。 -### 🚧 其他人的要求变更了你的贡献。 +### 🚧 其他人的要求你对自己的提交做出变更。 -It's common that you'll be asked to make changes to your contribution, whether that's feedback on the scope of your idea, or changes to your code. +对于自己的提交作出变更这件事非常的普遍，可能是你获得了反馈，也可能是变更了代码。 -When someone requests changes, be responsive. They've taken the time to review your contribution. Opening a PR and walking away is bad form. If you don't know how to make changes, research the problem, then ask for help if you need it. +当有人提出变更时，请表现出大度的地方，要及时响应。他们花时间审核了你的提交，要尊重他们。开启了PR，然后一走了之，是一种恶习。如果你不知道如何修改，请花时间深入研究问题的所在，如果还是没有想到好的办法，那么是该向他人求助的时候了。 -If you don't have time to work on the issue anymore (for example, if the conversation has been going on for months, and your circumstances have changed), let the maintainer know so they're not expecting a response. Someone else may be happy to take over. +如果你因为没有时间而无法继续在此issue继续工作（举例来说，如果对话已经过去了一个月了，没有任何的回复和进度，环境肯定变得不一样了），那么请向维护者告知你无法在及时的响应了，肯定有人非常乐意接替你的工作的。 ### 👎 你的贡献没有获得通过。 -Your contribution may or may not be accepted in the end. Hopefully you didn't put too much work into it already. If you're not sure why it wasn't accepted, it's perfectly reasonable to ask the maintainer for feedback and clarification. Ultimately, however, you'll need to respect that this is their decision. Don't argue or get hostile. You're always welcome to fork and work on your own version if you disagree! +你的提交最后可能没有被接受。真心希望你没有在此作出过多的努力。如果你不确定为什么没有被接收的话，这正是一个很好的询问维护者反馈和澄清的机会。最终，无论如何，你都要对他们的决定表示尊重。不要去做过多无谓的争论或者是充满敌意的谩骂。如果你坚持自己，你可以随意的fork项目，按照自己的思路发展出分支来。 ### 🎉 你的贡献被接收。 From 5b274fbc258b8247d48407530dad75376d31a4e0 Mon Sep 17 00:00:00 2001 From: jtr109 Date: Sun, 26 Mar 2017 19:58:50 +0800 Subject: [PATCH 018/156] trans(starting-a-project): trans a part --- _articles/zh-CN/starting-a-project.md | 44 +++++++++++++-------------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/_articles/zh-CN/starting-a-project.md b/_articles/zh-CN/starting-a-project.md index f6abef02b4d..666d2386ace 100644 --- a/_articles/zh-CN/starting-a-project.md +++ b/_articles/zh-CN/starting-a-project.md @@ -111,53 +111,53 @@ image: /assets/images/cards/beginner.png ## 发起自己的开源项目 -There is no perfect time to open source your work. You can open source an idea, a work in progress, or after years of being closed source. +即使你没有很好的时间来开源你的工作。你也可以开源一个想法，正在进行中的工作，或是关闭了多年的源码。 -Generally speaking, you should open source your project when you feel comfortable having others view, and give feedback on, your work. +一般来说，如果你乐意于他人对你工作的查看和反馈，你就应该开源你的项目。 -No matter which stage you decide to open source your project, every project should include the following documentation: +无论您决定开展项目的哪个阶段，每个项目都应包括以下文档： * [Open source license](https://help.github.com/articles/open-source-licensing/#where-does-the-license-live-on-my-repository) * [README](https://help.github.com/articles/create-a-repo/#commit-your-first-change) * [Contributing guidelines](https://help.github.com/articles/setting-guidelines-for-repository-contributors/) * [Code of conduct](../code-of-conduct/) -As a maintainer, these components will help you communicate expectations, manage contributions, and protect everyone's legal rights (including your own). They significantly increase your chances of having a positive experience. +作为维护者，这些组件将帮助你交流你的期望，管理贡献并保护每个人的合法权益（也包括您自己的）。他们能够大大增加你积极体验的机会。 -If your project is on GitHub, putting these files in your root directory with the recommended filenames will help GitHub recognize and automatically surface them to your readers. +如果您的项目在 GitHub 上，则将这些文件放在您的根目录中，并使用推荐的文件名将有助于 GitHub 识别并自动将其显示给读者。 -### Choosing a license +### 选择一个许可证 (license) -An open source license guarantees that others can use, copy, modify, and contribute back to your project without repercussions. It also protects you from sticky legal situations. **You must include a license when you launch an open source project.** +开源许可证保证其他人可以使用，复制，修改和贡献给您的项目，而不会产生不良后果。 它也可以保护您免受繁琐的法律影响。**启动开源项目时，请务必包含许可证。** -Legal work is no fun. The good news is that you can copy and paste an existing license into your repository. It will only take a minute to protect your hard work. +法律工作是非常无趣的。但好消息是，您可以将现有许可证复制并粘贴到存储库中。只需要花这么一点时间，就能保护你的辛苦工作。 -[MIT](https://choosealicense.com/licenses/mit/), [Apache 2.0](https://choosealicense.com/licenses/apache-2.0/), and [GPLv3](https://choosealicense.com/licenses/gpl-3.0/) are the most popular open source licenses, but [there are other options](https://choosealicense.com) to choose from. +[MIT](https://choosealicense.com/licenses/mit/), [Apache 2.0](https://choosealicense.com/licenses/apache-2.0/), 和 [GPLv3](https://choosealicense.com/licenses/gpl-3.0/) 都是非常流行的开源许可证， 但你可以选择[其他选项](https://choosealicense.com). -When you create a new project on GitHub, you are given the option to select a license. Including an open source license will make your GitHub project open source. +当你在GitHub上创建新项目时，你可以选择许可证。包括开源许可证将使你的GitHub项目成为开源。 -![pick a license](/assets/images/starting-a-project/repository-license-picker.png) +![挑选一个许可证](/assets/images/starting-a-project/repository-license-picker.png) -If you have other questions or concerns around the legal aspects of managing an open source project, [we've got you covered](../legal/). +如果您在管理开放源码项目的法律方面有其他问题或疑虑，我们已经[在这里](../legal/)介绍了。 -### Writing a README +### 编写自述文件 (README) -READMEs do more than explain how to use your project. They also explain why your project matters, and what your users can do with it. +自述文件不仅仅是用于说明如何使用你的项目。他们还可以解释你的项目为什么重要，以及它可以为你的用户做什么。 -In your README, try to answer the following questions: +在您的自述文件中，尝试回答以下问题： -* What does this project do? -* Why is this project useful? -* How do I get started? -* Where can I get more help, if I need it? +* 这个项目做什么？ +* 为什么这个项目有用？ +* 如何开始？ +* 如果需要，我可以在哪里获得更多的帮助？ -You can use your README to answer other questions, like how you handle contributions, what the goals of the project are, and information about licenses and attribution. If you don't want to accept contributions, or your project is not yet ready for production, write this information down. +您可以使用自己的README回答其他问题，例如处理贡献，项目的目标以及许可证和归属信息。 如果您不想接受他人的贡献，或者您的项目尚未准备好作为产品提供使用，请将这些信息写下来。 From df6bf441b3ac99534872730d4444561caf0f1dea Mon Sep 17 00:00:00 2001 From: LiJiansheng Date: Sat, 8 Apr 2017 15:59:39 +0800 Subject: [PATCH 019/156] translated first and second section. Signed-off-by: LiJiansheng --- _articles/zh-CN/getting-paid.md | 44 ++++++++++++++++----------------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/_articles/zh-CN/getting-paid.md b/_articles/zh-CN/getting-paid.md index 4d7fcf1d53a..a713ccbe82b 100644 --- a/_articles/zh-CN/getting-paid.md +++ b/_articles/zh-CN/getting-paid.md @@ -14,57 +14,57 @@ image: /assets/images/cards/getting-paid.png ## 为何会有人寻求经济上的支持 -Much of open source work is volunteered. For example, someone might come across a bug in a project they use and submit a quick fix, or they might enjoy tinkering with an open source project in their spare time. +很多开源的工作都是来自志愿者的辛勤付出。例如，有些人在使用项目的过程中遇到了问题，然后快速的修复了；也有些人是利用他们的业余时间在开源项目中需求挑战。 -There are many reasons why a person would not want to be paid for their open source work. +人们从事开源相关的工作，却没有得到报酬，这事一点都不奇怪，让我们来看看缘由： -* **They may already have a full-time job that they love,** which enables them to contribute to open source in their spare time. -* **They enjoy thinking of open source as a hobby** or creative escape and don't want to feel financially obligated to work on their projects. -* **They get other benefits from contributing to open source,** such as building their reputation or portfolio, learning a new skill, or feeling closer to a community. +* **他们本来就有一份自己热爱的全职工作,** 这可以让他们在没有后顾之忧的情况下利用业余空闲时间来为开源做贡献。 +* **他们热衷于沉浸在开源的思考中** 又或者是创造逃避环境，只是不想在他们的项目中获得金钱上的回报。 +* **他们能够从开源的贡献中获得其它好处，** 比如收获名誉、投资，又或者是学习到新的技能，又或者是能够感觉到和社区很接近。 -For others, especially when contributions are ongoing or require significant time, getting paid to contribute to open source is the only way they can participate, either because the project requires it, or for personal reasons. +但是，很多时候，尤其是正在进行的或者是需要花费大量时间的付出时，能够取得报酬是人们积极参与开源的唯一理由，无论是项目需求还是个人原因。 -Maintaining popular projects can be a significant responsibility, taking up 10 or 20 hours per week instead of a few hours per month. +维护颇流行的项目是一项很重要的责任，需要在每周花10～20小时，而不是每个月的几个小时。 -Paid work also enables people from different walks of life to make meaningful contributions. Some people cannot afford to spend unpaid time on open source projects, based on their current financial position, debt, or family or other caretaking obligations. That means the world never sees contributions from talented people who can't afford to volunteer their time. This has ethical implications, as @ashedryden [has described](https://www.ashedryden.com/blog/the-ethics-of-unpaid-labor-and-the-oss-community), since work that is done is biased in favor of those who already have advantages in life, who then gain additional advantages based on their volunteer contributions, while others who are not able to volunteer then don't get later opportunities, which reinforces the current lack of diversity in the open source community. +有偿工作也使人们从不同的各行各业做出有意义的贡献。有些人无法承受为开源项目做没有金钱回报的工作，他们自身的情况，如当前的财务收入、债务、或者来自家庭等其它的照顾义务。这也就意外着这个世界再也无法看到那些拥有天分但是有心无力的人们的贡献了。这是一个伦理上的问题，正如 @ashedryden 在 [无偿劳动的伦理和开源软件社区](https://www.ashedryden.com/blog/the-ethics-of-unpaid-labor-and-the-oss-community) 一文中所描述的，因此开源的很多工作是由那些已经在生活上取得成就的人们所贡献的，通过志愿的贡献进一步让他们获得了更加丰富的回报，而那些无法承受时间的人们错失了这样的机会，这就导致了开源社区越发的缺乏多样性。 -If you're looking for financial support, there are two paths to consider. You can fund your own time as a contributor, or you can find organizational funding for the project. +如果你在寻找金钱上的支持，可以考虑两条路径。你可以作为贡献者来将你的时间作为资金，或者是找一家能够为项目提供资金的组织。 ## 你的时间是最宝贵的，理应得到资助 -Today, many people get paid to work part- or full-time on open source. The most common way to get paid for your time is to talk to your employer. +在今天，有很多人在开源中获得了报酬，无论是兼职或全职。最为常见的做法就是，有些老板愿意为你付出的时间和工作成果掏腰包。 It's easier to make a case for open source work if your employer actually uses the project, but get creative with your pitch. Maybe your employer doesn't use the project, but they use Python, and maintaining a popular Python project help attract new Python developers. Maybe it makes your employer look more developer-friendly in general. @@ -78,7 +78,7 @@ It's easier to make a case for open source work if your employer actually uses t If you don't have an existing open source project you'd like to work on, but would rather that your current work output is open sourced, make a case for your employer to open source some of their internal software. -Many companies are developing open source programs to build their brand and recruit quality talent. +很多公司都在开发开源项目，从而能够打造自己的品牌，以及雇佣到高质量的人才。 @hueniverse, for example, found that there were financial reasons to justify [Walmart's investment in open source](https://hueniverse.com/2014/08/15/open-source-aint-charity/). And @jamesgpearce found that Facebook's open source program [made a difference](https://opensource.com/business/14/10/head-of-open-source-facebook-oscon) in recruiting: @@ -112,7 +112,7 @@ Beyond arrangements for individual contributors, sometimes projects raise money Organizational funding might go towards paying current contributors, covering the costs of running the project (such as hosting fees), or investing into new features or ideas. -A few examples of projects with organizational funding include: +一些获得组织资助的项目案例： * **[webpack](https://github.com/webpack),** which raises money from companies and individuals [through OpenCollective](https://opencollective.com/webpack) * **[Vue](https://github.com/vuejs/vue),** created by @yyx990803, which is [funded through Patreon](https://github.com/open-source/stories/yyx990803) @@ -134,7 +134,7 @@ Whether you're looking to pay for your own time, or fundraise for a project, you ### 影响 -Why is this project useful? Why do your users, or potential users, like it so much? Where will it be in five years? +为什么说这个项目有实际用处？你的用户或潜在的用户会喜欢它？5年之后它会是什么样子？ ### 牵引 @@ -162,6 +162,6 @@ Does the funder have any requirements around disbursal? For example, you may nee ## 尝试，不要放弃 -Raising money isn't easy, whether you're an open source project, a nonprofit, or a software startup, and in most cases require you to get creative. Identifying how you want to get paid, doing your research, and putting yourself in your funder's shoes will help you build a convincing case for funding. +赚更多的钱不是件容易的事情，无论你是在开源项目，亦或是在非盈利组织，又或者是软件的创业公司，但是无论在哪里，挣更多钱的秘密就是更多的创造力。当确定了你想如何获得报酬的时候，请继续你的研究，将自己放在投资人的角度来看问题，可以帮助你更好的构建一个更加令人信服的赚钱之道。 > From e0252654046d841c0a7bb458d1920bda3e3fd31a Mon Sep 17 00:00:00 2001 From: LiJiansheng Date: Wed, 26 Apr 2017 22:04:35 +0800 Subject: [PATCH 020/156] translated get-paid second and third paragraph. Signed-off-by: LiJiansheng --- _articles/zh-CN/finding-users.md | 28 +++++++-------- _articles/zh-CN/getting-paid.md | 58 ++++++++++++++++---------------- _articles/zh-CN/metrics.md | 22 ++++++------ 3 files changed, 54 insertions(+), 54 deletions(-) diff --git a/_articles/zh-CN/finding-users.md b/_articles/zh-CN/finding-users.md index d958932c32e..7d6586725b4 100644 --- a/_articles/zh-CN/finding-users.md +++ b/_articles/zh-CN/finding-users.md @@ -4,21 +4,21 @@ title: 为项目寻找适合的用户 description: 通过找到诚心如意的用户，帮助开源项目成长。 class: finding toc: - spreading-the-word: "Spreading the word" - figure-out-your-message: "Figure out your message" - help-people-find-and-follow-your-project: "Help people find and follow your project" - go-where-your-projects-audience-is-online: "Go where your project’s audience is (online)" - go-where-your-projects-audience-is-offline: "Go where your project’s audience is (offline)" + spreading-the-word: "四处传播" + figure-out-your-message: "发出自己的声音" + help-people-find-and-follow-your-project: "帮助人们找到并关注你的项目" + go-where-your-projects-audience-is-online: "到项目成员线上经常去的地方" + go-where-your-projects-audience-is-offline: "到项目成员线下经常去的地方" build-a-reputation: "Build a reputation" order: 3 image: /assets/images/cards/finding.png --- -## Spreading the word +## 四处传播 -There's no rule that says you have to promote an open source project when you launch. There are many fulfilling reasons to work in open source that have nothing to do with popularity. If you are hoping others will find and use your open source project, however, it's time to tell everybody about your hard work! +还没有规定说应该怎么去倡导刚创建的开源项目。但没有任何理由说必须默默无闻的在开源项目上工作。相反，如果你向有更多的人发现和使用你的开源项目，你就应该让所有人知道你所努力的成果！ -## Figure out your message +## 发出自己的声音 Before you start the actual work of promoting your project, you should be able to explain what it does, and why it matters. @@ -32,7 +32,7 @@ For example, @robb uses code examples to clearly communicate why his project, [C For a deeper diver into messaging, check out Mozilla's ["Personas and Pathways"](http://mozillascience.github.io/working-open-workshop/personas_pathways/) exercise for developing user personas. -## Help people find and follow your project +## 帮助人们找到并关注你的项目 -## Build a reputation +## 赢得口碑 In addition to the strategies outlined above, the best way to invite people to share and contribute to your project is to share and contribute to their projects. @@ -157,6 +157,6 @@ There is no overnight solution to building an audience. Gaining the trust and re

-## Keep at it! +## 保持精进 Sometimes, it takes a long time before people notice your open source project. That's okay! Some of the most popular projects today took years to reach high levels of activity. Focus on building relationships instead of a magic bullet. Be patient, and keep sharing your work with those who appreciate it. diff --git a/_articles/zh-CN/getting-paid.md b/_articles/zh-CN/getting-paid.md index a713ccbe82b..f2a9421a0dc 100644 --- a/_articles/zh-CN/getting-paid.md +++ b/_articles/zh-CN/getting-paid.md @@ -54,7 +54,7 @@ image: /assets/images/cards/getting-paid.png