Contributing Guide 💯

Hello stranger! ✨ Please, read the Code Of Conduct, first!

“Every thought, every word, and every action that adds to the positive is a contribution to peace.
Each and every one of us is capable of making such a contribution.” ~ Aung San Suu Kyi

Firstly, a heartfelt thank you for making time to contribute to this project!

Table of Contents

• Are you new to Open Source?
• Communicating effectively
  • Give context
  • Do your homework beforehand
  • Keep requests short and direct
  • Keep all communication public
  • It's okay to ask questions
  • Respect community decisions
  • Above all, keep it classy
• Gathering context
• Opening an issue
  • Tips for communicating on issues
  • Include any/all relevant information
• Opening a pull request
  • How to submit a pull request
• What can I do while i'm waiting
  • Star the project
  • Tweet about it
  • Help others
• Thank You!

Are you new to Open Source?

If you’re a new open source contributor, the process can be intimidating.
What if you don’t know how to code? What if something goes wrong? Don't worry!

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 other parts of a project that are most neglected or overlooked. You’ll do the project a huge favor by offering to pitch in with these types of contributions!

Even if you like to write code, other types of 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.

⬆️ Back to top ⬆️

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..."

⬆️ Back to top ⬆️

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.

⬆️ Back to top ⬆️

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), opened pull requests, and the public support chat. 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. And because this project is on GitHub, you'll 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 support chat at Gitter or IRC.

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 a while (click the "Watch" button to be notified of all conversations), and get to know community members, before doing work that might not get accepted.

⬆️ Back to top ⬆️

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 a while 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.
• Please be patient and wait for a response from maintainer or somebody else. Check out "What to do next?".

Include Any/All Relevant Information in the Issue Description

• Please include as much relevant information as you can, such as versions and operating system.
• A good issue describes the idea in a concise and user-focused way.
• Never leave the issue description blank even when you are in a "rush" - the point of an issue is to communicate.

Why can't the description be empty? You wouldn't send a blank email to hundreds of your friends (unless you wanted to freak them out!), right? Submitting blank issues is doing exactly that! It sends a "I have no idea what I'm doing" message to your peers.

⬆️ Back to top ⬆️

Opening a pull request

If this is your first pull request, check out Make a Pull Request by @kentcdodds.

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.

How to submit a pull request

Make sure that you have the Yarn Package Manager installed on your system. With NPM you still can do the things, but tests may fail, due to different folder structures and resolving mechanisms.

There are just 8 easy steps you should do. Please, follow them in that exact order.

1. Fork the repository and clone it locally.
2. Create a branch for your edits.
3. Install dependencies by running the yarn install command.
4. Test if everything is working before you start doing anything with the yarn test command. If something is wrong, please report it first and don't continue if you can't skip the problem easily.
5. Reference any relevant issues, supporting documentation or information in your PR (ex. "Closes #37.")
6. Test again or add new ones! Run yarn test again to make sure your changes don't break existing tests. Try to write them, but don't worry to commit them failing! We can finish them together in the Pull Request.
7. Commit your changes by running yarn commit. It will lead you through what the commit message should look like and will run more tasks to ensure that code style and tests are okey. If there is no such command, consider suggesting the gitcommit package to the maintainers, which is interactive thin wrapper on top of original git commit.
8. Wait response! What to do in that time? Check out "What to do next?".

⭐️ You did it! ⭐️ Congratulations on becoming one of the Open Source contributors!

⬆️ Back to top ⬆️

What can I do while I'm waiting?

⭐️ Star the Project! ⭐️ (share the love!)

If you've found the project interesting, helpful or useful in any way, please star the repository on GitHub!
Stars show other members in the developer community that it's a worthwhile project or learning resource and one that can offer value to other developers like you! 🌟

❤️ Tweet about it! 💯

Ping your peers at Twitter about your thoughts on the project , about what you just contributed and what is coming soon to it! Twitter is great for these small bits.

🆘 Help others 👍

To help a lot: go on a treasure hunt for an issue that someone else created which has not had any comments... or has not been assigned to someone for investigation or work. This is quite easy to find by searching for a label: help wanted. It's always great to get a response, and so you may make someone very happy!

⬆️ Back to top ⬆️