Hello everyone! It’s been a while since the last part but we made it! For those of you who haven’t read the previous parts or are wondering what I planned for the next parts: Table of contents: Intro Starting a project Documentation Publicity Issues and PRs Automation (WIP) Versions management (WIP) Recap In the previous chapter, we’ve talked about spreading the word, making your open source project more attractive, and several other topics that I recommend checking out above before you continue reading. Today we’ll be discussing the holy grail of every open source project. We’ll see what’s the best way to manage and organize contributions as well as how to treat them and more. contributions, The baseline for today is: You already have an open source project, it is available on GitHub, well documented and can be consumed easily via one of the package registries. What are contributions A contribution to an open source project is any change that’s done by a person other than the owner. In practice it comes in two forms: Issues Here’s what Github about issues: says You can collect user feedback, report software bugs, and organize tasks you'd like to accomplish with issues in a repository. Issues can act as more than just a place to report software bugs. In a nutshell, an issue is any piece of information that requires some sort of action. Pull requests (PRs) Here’s what Github about pull requests: says Pull requests let you tell others about changes you’ve pushed to a branch in a repository on GitHub. Once a pull request is opened, you can discuss and review the potential changes with collaborators and add follow-up commits before your changes are merged into the base branch. In a nutshell a pull request is an actual change to the project. Working with issues and PRs So how does one actually work with issues and PRs, how does one approach issues and PRs created by contributors and etc.? Personal example The best advise I can give you is to to incorporate a certain way of work. use a personal example This means that when you’re working on a new feature — create a PR for this and merge it once it meets all your standards. When you found a bug, or thought of some missing functionality — create an issue. Not only will it organize your work and bring order to your project, it will also give the contributors a reference from which they could learn and adapt their issues and PRs accordingly. Also, especially if you have high standards (every PR should come with proper documentation, test coverage etc.), you should treat yourself just like you would any other contributor. You can’t demand from others something that you’re not doing yourself. It is hypocrisy. Moreover, sometimes you should be even more lenient towards the contributors than to yourself. Especially if your project is at the early stage and doesn’t have a lot of contributors. This brings us to the following: All work is appreciated Collaborating with others is all about mutual respect. You should respect your contributors. Be patient when answering their questions (even the dumbest ones) and be polite when providing . constructive criticism But what’s vital is to appreciate your contributors work. If someone just created an issue (even without thorough research, even without reproduction) — thank him. They bothered to move their chair a bit closer to the table, they sat up straight and typed something they thought could be beneficial to you, Thank them and if needed, ask for additional details in a polite and respectful manner. If someone created a PR that doesn’t meet your high standards — thank them. Thank them and ask politely to make code changes/write tests/add documentation and etc. Give them a link to one of your PRs for reference or provide them with a link to the contribution guide. A constructive and positive conversation will give those contributors additional incentive to continue their work. Or it won’t… Quality Versus Quantity Eventually it’s almost always a tradeoff (unless you own a huge open source project, like Angular or React). You can decide that you’re not easing up your standards, not even for a little bit, and most probably you’ll end up implementing all of the work yourself or - you can decide that you’re lowering the standards for contributors, but this would make your standards futile as they’re not applied. I’ve learned that every contributor requires a different approach. It really depends on the person and their personal interest in their contribution. You should take into account such factors as the urgency of the issue, the experience of the contributor, the complexity of your code, the complexity of the required fix or feature, the contributor’s motivation and more. Usually, I politely ask for changes, wait for a few days, and if nothing happens I make the changes myself, given of course that the issue is considerably important. As for less important (nice-to-have) fixes or features — I usually leave them entirely to the community. Over time as the number of issues and PRs grows it becomes an ambitious task to keep track, prioritize and categorize them, therefore… Labels is a great tool for keeping your issues and PRs prioritized and organized. Github labels You can search by labels, filter by labels, but whats of substance here is that it helps to . visualize the overall state of your project Thus, you can enter the Issues page and see that most of your issues are labeled as — this means that you should stop pushing forward and instead focus on fixing them. bug Alternatively you can see that most of the issues are labeled as or required . is another useful label which helps you focus on the significant things first. enhancement features priority Not only you but also your contributors can (and will) benefit from you using labels. For example, going back to , one can enter the Issues page and visually identify the issues that require the help of the community ( , etc.) Getting collaborators help-wanted pr-welcome Aside the labels with single responsibility (like bug or enhancement ) I recommend you use labels for scoping an issue/PR or putting it on a certain scale. For example: , priority:low priority:high , , required:investigation required:tests required:docs or in the case of monorepo: , etc. packages:package1 packages:package2 Here is an example of the labeled issues page from my project: Labels make it pretty easy to distinguish from a quick glance what are the issues that require your (or contributors) attention, to which component these issues are related and what is required in order to proceed. PR and Issue templates I highly recommend you spend a few minutes of your time and define templates for and . Issues PRs With issue and pull request templates, you can customize and standardize the information you’d like contributors to include when they open issues and pull requests in your repository. This will save you a lot of time since you won’t have to respond to each issue or PR with a request for additional information or changes. You’ll still have to do that (because there are contributors that simply don’t pay attention to the templates) but it will happen far rarer then it would if you didn’t create templates. Here is an example of a default issue that you see when the corresponding template is defined in your repository: Github apps and actions There are quite a few that can help you manage PRs and Issues. Github Apps and Actions The list constantly grows, but I personally find these to be most useful: Stale bot WIP Autoapproval PR labeler Responsiveness If I open an issue or a PR to another open source project and it takes an eternity to get a response — I switch. is one example: Here The initial response was quite quick, it took only 2 days The discussion was pretty fruitful The PR is still open with no updates on what exactly is missing/wrong As a result I switched to another package. The same will hold true for your project if you’re not responsive: if it takes you 2 weeks to respond, if PRs are waiting , instead pending for contributor’s changes you’ll lose users, i.e. potential contributors. for you required by you — So do yourself a favor — be responsive. It doesn’t have to be an immediate solution to someones problem but even letting the user know that you’ll look into their issue next week already gives them some certainty and time frames. The bad news — you should stand by your promises. But if you didn’t, don’t worry — we all have personal lives and it’s understandable if you had some urgent matters which postponed your work on the open source. — it’s not a big deal, just write a word or two to let people know that the feature they’ve been waiting for is postponed. Give a short update Prioritization There are a few methods that can help you prioritize the most important issues. First, how does one identify the most important issues? As I see it, the most important issues are the ones that users want the most, be it a new feature, a bug-fix or something else. Sometimes a user will express their interest in the issue but most likely, they won’t… Therefore, I present to you quite a simple way to know what users are interested in. Every project on Github has an Insights tab, with a Traffic section: A the bottom of this section you can find the table which gives you insights into which pages are most viewed by your visitors: Popular Content The issues listed in this table are the most visited issues therefore most probably are important to the users. When you identified the most important issues you need to highlight them on the issues page. Here are a few ways to do that: Pin the issue You can have up to 3 pinned issue per repository. Pinned issues appear at the top of your issues page so it’s nearly impossible to miss them: Add a label We already talked about the labels and this is an excellent example for the as well as labels. Those labels will let the potential contributors know that this issue is important and any help is appreciated. using applying help-wanted priority:high Continuous Integration Having every Pull Request built and tested before it is merged into the master will give you (depending on the test coverage) a decent amount of confidence in the code you’re about to merge into your master branch. While I couldn’t but mention it as a part of the PR management process, it’s an of a task that otherwise you’ll have to do yourself, therefore it is not directly related to PR management. automation You can still checkout out every PR, build it locally, run the tests and merge if everything is green therefore Continuous Integration is not directly related to the PRs management. Don’t worry though, we’ll cover it in detail in the next chapter. Wrapping it up It is very important to keep your project clean and organized because as we all know — cleanliness is next to godliness. Not only does it make the management process more effective, but it also improves the overall impression of your project. PRs and issues along with the codebase are integral parts of your open source projects facade. Don’t underestimate their value. In the next part we’ll discuss , which is crucial for every open source project and can drastically reduce the time you have to invest into it. Automation If you enjoyed my writing, learned something new or insightful or if you just don’t want to miss the next part, make sure you’re following me on or here. Cheers! Twitter

Twitter

Follow my blog

Read My Stories

Too Long; Didn't Read

In your car, at home, or at work — Bosch technology shapes many areas of life.

Open Source Series: Issues and PRs

Too Long; Didn't Read

Company Mentioned

JeB

About Author

TOPICS

THIS ARTICLE WAS FEATURED IN...

Open Source Series: Issues and PRs

Too Long; Didn't Read

Company Mentioned

JeB

About Author

TOPICS

THIS ARTICLE WAS FEATURED IN...

RELATED STORIES