Friday, October 09, 2020

6 tips for contributing to Open Source

 The following is based on a presentation I gave on the September 2020 WinUI community call.


Here are my tips

  1. Don't start with a Pull Request
  2. Follow the project's conventions
  3. Assume positive intentions
  4. Explain why. Don't say "should"!
  5. Focus
  6. Everything helps


Don't start with a Pull Request

If you're doing anything more complicated than fixing a typo or small spelling mistake, don't start with a pull request.
Engage with the project maintainers before you start doing any work.

You don't want to spend time on something that isn't wanted or that someone else is already working on. Nor do you want to build a solution that doesn't fit with what else is going on with the project.
It may also be beneficial to discuss possible ways to make the change, fix the bug, or add the proposed feature. You'll want to make the best use of your time, and maintainers or other people working on a project may have ideas and suggestions to help you.

You can "engage" with the appropriate people by creating an issue (if it's something new), commenting on an issue (if there is already on related to the work you want to do), commenting on a discussion, message board, email list, chatroom, or wherever else is appropriate for that project.
Aim to try and work the same way as others on that project already do.

Follow the project's conventions

Most projects include a document on how to contribute. Most of them include a note about not starting with a pull request. But there's more in there too. If a project has one, be sure to read the contributing.md document and follow what's written there.
If a project doesn't have a guide to contributing, ask how to get involved. And, maybe suggest a guide to contributing too.

As a general rule, code is easier to understand (and therefore review and maintain) if consistent in style, structure, and conventions. Anything you contribute should look like it belongs with the rest of the codebase.
Consistency applies to documentation too. It can be distracting for the reader when documentation uses differing tenses, styles, terminology, etc.

Many projects also use templates and checklists when creating issues and submitting pull requests. Always strive to provide the information and complete the desired tasks.

This isn't being done to be difficult.

Assume positive intentions

Projects ask for information because it helps. They're not asking for it to be difficult.
 
Project maintainers don't want you to waste your time. Also, they want to make the best use of their time. They ask for specific information to evaluate and accept a change or understand an issue. They don't do it to waste your time.

This point goes both ways.
Project maintainers need to remember that when an issue is raised with minimal details, it's not because someone is being difficult or lazy. They may not have been able to provide more information. They may not even speak the same language. 
Be kind.

Explain why. Don't say "should"!

If raising an issue, explain why you want a change, or how a new feature will help you. This helps others understand and allows appropriate prioritization.

Never say, "you should make it do X" without explaining why. 
I'm sure your opinions and ideas are great, but you need to do more than state them.
Is this currently causing you a problem? Or is it just something you think would be a "nice to have"? Why you're asking for or suggesting something can be essential to know.

Focus

And if you're raising issues about problems or suggesting new features, create separate issues for each problem or idea.

Breaking work down into discrete areas can help with understanding, prioritization, and associating changes.

It's much easier to triage and manage work when an issue only lists one problem.
It's easier to review a change that fixes one bug or adds one feature.

It's also useful when discussions remain focused.
Depending on the project, it may or may not be appropriate to have side discussions in issues or comments. I want to be more involved with several open-source projects, but I can't filter out all the seemingly unrelated discussions and so am unable to follow all the relevant discussions that occur.
Follow the conventions of the project regarding side discussions. 

Everything helps

The success of very few projects is predominantly decided by the code. Many other factors play their part, and you can contribute to these too.


This includes writing, expanding, or translating documentation. - There are projects I contribute to where they don't need other people writing code, but I can make a valuable contribution by writing docs.

The same goes for testing. - There are projects where others are paid to write code, but I can come in as an external contributor and make significant, valuable contributions by creating tests.


Again, there are projects where I add value by asking questions.

  • What about people who are using this for the first time?
  • Did you consider X?
  • Why did you do it that way?

This can be informal or as part of a code review.


Bringing different perspectives and experiences helps create something useful to more people and a wider variety of people.


Everything helps.


You can also support projects in other ways. For examples, see https://rapidxaml.dev/support


Financial support can be great if you can provide it, but not every project needs it.

Even if you can't provide a financial contribution, there are ways to support projects you use and value.

  • Leave a star on GitHub.
  • Leave a review or a star rating.
  • Spread the word through a tweet, blog post, stream, video, or whatever you use.


Feedback can be really encouraging for people investing in the creation of open-source projects and is a reminder that their effort is valued and appreciated.


Show you care. Show your support.




1 comment:

  1. This was also posted at https://dzone.com/articles/6-tips-for-contributing-to-open-source

    ReplyDelete