In open-source software, the term “upstream” refers to the main place of development. Many people talk about doing “upstream first” for open-source contributions, but what does that really mean?


Upstream is the place where open-source software lives. It is where it is continuously improved, it is where it is maintained, it is where people come to ask questions or report bugs.

If you download the source code of an open-source project, then you have a copy of the upstream code, either a released version or a development (unreleased) version.


If you modify the source code, you have diverged from upstream. Only when you contribute back to upstream, you have resolved that discrepancy.

There are many reasons why you would modify the source code: adaptations for your system, infrastructure, internal processes. A copy of upstream with modifications is called a fork.

Most forks track upstream by regularly merging in the upstream changes and applying their small adaptations on top of the upstream code.

The more changes you make in your fork, the more expensive it can become to maintain. You will find that the changes you are making are not exclusive to your company or infrastructure because the problems you solve with your changes are just as much of a problem to other people than they are to you.

Contributing Back

It can be frustrating that every time you merge in changes, it becomes more and more difficult to make them work with your adaptations. It would be so much easier, if the upstream project knew about your problem and needs. Then you begin to realize that open-source software is only available and free of charge to you because other people took the time to publish their ideas and code in the open. You know that you could do the same and avoid the upstream changes working against you. You realize it would be smart to contribute back.

Upstream First

Upstream First means that whenever you solve a problem in your copy of the upstream code which others could benefit from, you contribute these changes back upstream, i.e. you send a patch or open a pull request to the upstream repository.

In the course of contributing back, you may have to discuss with the community members of the upstream project. You may find there is already a solution you were not aware of. You may find your solution can be improved. Most importantly, when the upstream project releases a new version, you can delete your modifications from your fork and stop worrying about the adaptation work you would have to do if you hadn’t contributed back.

Does Upstream First just mean being kind?

Upstream First is more than just “being kind”. It means you have a say in the project. It means predictability. It means you are in control. It means you act rather than react. It means you understand open-source.