我的开源之路

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.

Does it have a license? Usually, there is a file called LICENSE in the root of the repository.

Look at the commit activity on the master branch. On GitHub, you can see this information on a repository’s homepage.

When was the latest commit?

How many contributors does the project have?

How often do people commit? (On GitHub, you can find this by clicking "Commits" in the top bar.)

How many open issues are there?

Do maintainers respond quickly to issues when they are opened?

Is there active discussion on the issues?

Are the issues recent?

Are issues getting closed? (On GitHub, click the "closed" tab on the Issues page to see closed issues.)

How many open pull requests are there?

Do maintainers respond quickly to pull requests when they are opened?

Is there active discussion on the pull requests?

Are the pull requests recent?

How recently were any pull requests merged? (On GitHub, click the "closed" tab on the Pull Requests page to see closed PRs.)

A project that is friendly and welcoming signals that they will be receptive to new contributors.

Do the maintainers respond helpfully to questions in issues?

Are people friendly in the issues, discussion forum, and chat (for example, IRC or Slack)?

Do pull requests get reviewed?

Do maintainers thank people for their contributions?

Communicating effectively

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.

A checklist before you contribute

Communicating effectively

公告