In some documents or blogs about development in open source projects, you can read stuff like 'upstream developer' or 'upstream fix'. What does that mean?

up vote 22 down vote accepted

Consider the obvious analogy (from which the term flows - pun intended) ... water in a river flows 'downstream' and thus 'upstream' is the source from which the water comes.

This analogy is deeply embedded in software development, so it's no mere coincidence that we use terms like 'head', 'source', 'upstream', 'downstream' and even 'flow' extensively in the field.

In the context of a forked software project, the 'upstream' is the source from which a particular project was forked. This might not be the absolute origin.

If project A is forked to produce project B which is then forked to produce project C, then B is 'upstream' of C and A is upstream of B (and C).

Thus, an upstream developer is one who works on an upstream project. An upstream fix is one which exists in the upstream (parent) project.

When working with Git, especially in the context of Github, it is not uncommon for a developer to set two remotes

  • origin points to their own fork of a project
  • upstream is conventionally used to point to the project from which they forked.

This allows the owner of the fork to pull fixes and enhancements directly from the original project, thus keeping theirs in sync with it.

On Github, I have a fork of the official json-c repository. My local repo is setup thus:

$ git remote -v
origin  ssh://git@github.com/kdopen/json-c (fetch)
origin  ssh://git@github.com/kdopen/json-c (push)
upstream    git@github.com:json-c/json-c.git (fetch)
upstream    ssh://git@github.com/json-c/json-c.git (push)

I prepare changes in a local branch, regularly update my own fork with

$ git pull upstream master
$ git push origin master

and then rebase my own branches on the results.

If I have changes in my fork which I would like to see in the upstream version, then I create a "pull request" asking for them to accept my contribution. This process is referred to as "pushing a change upstream" which, for many projects, reflects the fact that its more work going upstream than down.

Upstream is not completely unique to open source, in the closed source world they just call it a vendor. It is however better in open source because you don't have to wait for the vendor to fix bugs which is why the river analogy is so popular (although not perfect as rivers are much more likely to only flow in one direction). A project can get software from many sources, put them together and distribute through a single distribution channel. Upstream is the projects you use to build your project. Which in most cases is more than one.

  • The terms "upstream" and "downstream" are apparently even in use outside of software development in the context of supply chain management in an analogous sense. – anothernode Dec 15 '17 at 13:32

Besides forks as @kdopen said, the "upstream" terminology also applies to Linux distributions.

In this case, the "upstream" is the actual developer of the project and the "downstream" is the packager. Distros have to add the packaging scripts and sometimes have to patch build scripts or source files; these are all sent downstream but only some are sent upstream.

There can even be multiple levels, e.g. an Ubuntu package based on a Debian package of a fork of a project (libjpeg-turbo for example).

Upstream/downstream is the directional term describing the flow of data.

For example in software development, when you use centralized revision control system (like SVN), you always commit changes upstream, in decentralized VCS (such as Git) there is no inherent/absolute "upstream" or "downstream" in the system, but you can choose how the data flows (so the main repository is used as "upstream").

In most of the software development projects, the code fixed/changes are usually committed/pushed to upstream repository (towards the production: dev, test, stage, live) and the database is pulled downstream (from the production into development environment).

Related:

Your Answer

By clicking "Post Your Answer", you acknowledge that you have read our updated terms of service, privacy policy and cookie policy, and that your continued use of the website is subject to these policies.

Not the answer you're looking for? Browse other questions tagged or ask your own question.