Welcome to the second article in the "Contributing to Open Source" series.
In the previous post I covered some of the benefits of contributing to open source as well as some guidance on how to find projects and items (or issues) to work on.

Open-source brings together people from all over the world to collaborate and find solutions to complex problems.
This post aims to help you improve your communication and collaboration skills. And at the same time, help make our community friendlier and safe for us all.

Communication and people skills

I have been contributing to open source for some years now, mainly because I love writing code and the communities I belong to. Over these years, I have had a mix of experiences and challenges. And in both cases, maintainers and fellow contributors have played a massive role in this.

These are my top recommendations when it comes to communicating and collaborating with other folks or projects:

• First thing first - before opening an issue, creating a Pull Request familiarise yourself with the project's Contribution Guidelines and their Code of Conduct. Make sure you know what the existing communication channels are and use them accordingly (e.g. Gitter, Slack, Github issues, Discourse). Read the documentation first - sometimes the answer is in the documentation. Go through the documentation and see if you can find an answer to your question.
• Before opening a new issue, make sure to check the existing ones, so you do not open a duplicate. If there is an open issue tackling the same problem you are reporting comment on it providing additional context. If there are issues that are related, make sure to reference them in your newly created issue. Pro tip: avoid the urge of asking: why has this not been fixed yet? Or similar.
• If you open an issue that you are not able to resolve yourself, please add a note about this. That way, maintainers can label this issue accordingly (e.g. "help wanted", "needs discussion"). If possible work on a reduced test case.
• When reporting issues or requesting features, please use the project's issue tracker. This allows for discussions to be open and visible to the broader community. Do not request features or raise issues by emailing/sending Twitter DMs to the maintainers.
• Keep your communications smart:
  • Only comment if you have something to add to the discussion.
  • Always provide context - I mentioned this before but minimise the cognitive burden on maintainers and contributors by absorbing the complexity on their behalf. Make it explicit what is being asked of them.
• Respect people's time - everyone has other responsibilities and need time to unwind and recharge their batteries. Do not ask maintainers for an ETA or ask them to prioritise your issue. Sometimes issues go silent for a while (as PRs do) so if needed make use of a gentle "bump". This is asking for concrete actions in a respectful manner. "Do you have a couple of minutes to look at this PR?", "I am having trouble with this test - do you have any pointers on what I might have missed?".
• Avoid shaming/guilting - sometimes your PR will not align with the project's roadmap, others your feature request might not be relevant, or the extra effort might not outweigh the benefits. You might not get an immediate response because sometimes maintainers are overworked and burned out. Remember: folks often work on open source voluntarily. Public shaming them for not having X feature, pointing out how this other project is much better than this one or "how bad their API decisions are" does not benefit anyone. Be gracious and thank folks for their work, avoid sending emails or start Twitter rages when you are frustrated and cannot solve your issues. Instead, consider contributing your solution (when you get there) and move on.
• Avoid entitlement - always be respectful when providing feedback or suggestions. If there is something that could be improved and you can help with this, offer your help.
• Don't be a bystander - have you noticed something that is in clear breach of the Code of Conduct? Report this immediately so that maintainers can take care of this situation. Disagreements can quickly escalate into very nasty problems, so the best you can do here is bring it to the attention of the core developers as soon as possible.
• Avoid unnecessary discussions - maybe folks have decided to adopt a specific style guide or use a code formatter. Though this might not align with your personal preferences, avoid the urge to convince folks on why they should change their style guide.

Workflow ettiquete

The next thing we can improve is our etiquette around the contribution itself:

• If the project has issues or Pull Request templates, please USE THEM. If it does not provide as much information as possible to help the maintainers and contributors:
  • Issues: steps to reproduce the problem, details about your environment and OS, any steps you tried to fix the issue, command line outputs and/or screenshots are great additions too. If you have suggestions on how to solve this problem, make sure to add them also.
  • Pull Request: what issue the PR relates to (use fixes/closes: ), what you did and how you tested your changes. Also, note if this introduces braking changes or requires dependencies upgrades. Make sure to also update the docs and add a note about this. If adding a new feature, make sure to add the relevant tests or edit existing ones.
  • Feature request: though this is usually raised as an issue make sure to provide enough context about WHY this feature might be useful for the community (rather than only yourself). If you have ideas on how this could be implemented or what skills would be needed, make sure to point it out. Pro tip: avoid asking questions like "Why does this do not exist already?"
• Ask for feedback early - as soon as you start working on a fix or feature create a PR and mark it as Work in Progress (WIP) on the title. If you get feedback early, it will be easier to align your work with the project vision, and you can ensure your PR will be merged.
• Use descriptive commit messages - "Fixes issue" does not provide context nor describe what you did "Ensure the correct variable is referenced" is a much better message.
• One issue one PR - make sure that your Pull Request tackles one single issue. This makes it easier for others to review your work and provide feedback. It also makes it easier to keep changelogs consistent.
• As soon as you decide to work on an issue, make sure to explicitly say you will work on it. This helps others to know what issues are actively being worked on without stepping on each others' toes.
• Familiarise with Gitflow and/or with the contribution guidelines for the project.
• Ask first - if you are planning to submit a huge PR to a project to which you do not contribute regularly, ask the maintainers first. Make sure that what you are planning to do aligns with their project roadmap or vision. If this can be split in smaller PR's, make sure to do this.

That is all for now. Do you have any other suggestions I missed in here? Make sure to add them to the comments.

And keep your eyes peeled for the third post on this series "What makes a good and meaningful contribution to open source projects?".