Working without write access

Author

Marie-Hélène Burle

There are two situations in which you do not have write access to projects:

  • you are an outsider (i.e. you are contributing to open source projects you are using, but you are not part of the team),
  • you are part of the team, but the person in charge wants a workflow via pull requests (PRs)—this is often the case in large teams with a more top-down organization.

Opening issues

The easiest thing to do is to open an issue.

This is a way to bring the attention of the maintainer(s) of the project to a particular question without attempting to directly address the problem.

You might open an issue for instance if:

  • you are having problems with an open source tool you are using,
  • you found a bug,
  • you want to suggest a new feature,
  • (more applicable to the research collaboration framework) you want your team to address some question relevant to the project—an issue is a way to keep something in the mind of everyone involved until it is resolved and closed.

If enabled by the maintainer of a project, the “Discussions” tab is the place where you want to ask for help or discuss topics less directly pertinent to improving the project.

Forking a project

Now, a more advanced approach is to actually make changes to the project.

If you want to develop your own version of the project, you can fork the GitHub repository: go to GitHub and fork the project by clicking on the “Fork” button in the top right corner.

You have all privileges on the forked project. So you can make any change you want there. You can clone it to your machine and develop the fork. But your fork does not get updated to the improvements made to the initial project. It is an independent project of its own.

Keeping a fork up to date

If you want to keep your fork up to date with the initial project, you need to:

1. Clone your fork on your machine

This will automatically set your fork on GitHub as the remote called origin:

# If you have set SSH for your GitHub account
git clone git@github.com:<user>/<repo>.git <name>

# If you haven't set SSH
git clone https://github.com/<user>/<repo>.git <name>

2. Add upstream

Add a second remote, this one pointing to the initial project. It is usual to call this remote upstream:

# If you have set SSH for your GitHub account
git remote add upstream git@github.com:<user>/<repo>.git

# If you haven't set SSH
git remote add upstream https://github.com/<user>/<repo>.git

3. Pull from upstream

You can now pull from upstream to keep your fork up to date:

git pull upstream

From there on, you can pull from and push to origin (your fork) and you can pull from upstream (the initial repo).

Of course, if your project and the initial one diverge in places, this will lead to conflicts that you will have to resolve as you merge the pulls from upstream.

Most of the time however, you don’t want to develop your own version of the project. Instead, you want to make the initial project better by contributing to it. But you can’t push changes to upstream directly since you are not part of that project. You don’t have write access to that repository. If anybody could push to any project, that would be utter chaos.

So how do you contribute code to someone else’s project?

Creating pull requests

  1. Pull from upstream to make sure that your contributions are made on an up-to-date version of the project.
  2. Create and checkout a new branch.
  3. Make and commit your changes on that branch.
  4. Push that branch to your fork (i.e. origin—remember that you do not have write access on upstream).
  5. Go to the original project GitHub’s page and open a pull request from your fork. Note that after you have pushed your branch to origin, GitHub will automatically offer you to do so.

The maintainer of the initial project may accept or decline the PR. They may also make comments and ask you to make changes. If so, make new changes and push additional commits to that branch until they are happy with the change.

Once the PR is merged by the maintainer, you can delete the branch on your fork and pull from upstream to update your local fork with the recently accepted changes.