Working with Personal Forks

Owned by Ned Batchelder (Deactivated)
Last updated: Jan 08, 2024
4 min read

Personal forks are a standard open source tool for making pull requests against repos where you don’t have write access. It’s a little more complicated than working directly in the repo, but it’s not difficult.

There are many git tools, and styles of working. These instructions focus on the git command line. There are other ways to accomplish the same workflow, including more GitHub GUI-centered, or the gh GitHub command-line tool. We welcome improvements to this page.

Terminology

Fork: On GitHub, a fork is a copy of a repo in your own account so that you have write permissions to push commits and branches to it. This is different than the broader open source term of forking a project because of a disagreement about direction. We are talking about the gentle GitHub term, not the aggressive governance term.

Upstream: the repo you are ultimately contributing to. In our world, this is likely in the openedx GitHub organization.

Remote: a server copy of a repo. A local repo on your machine can have a number of different remotes, and pull from them separately. Each remote has a name and a URL. The default remote is called “origin”. You can see your remotes' names and URLs with git remote -v.

The Ideal State

You will have a local repo with two remotes: “origin” will point to your fork in your account, and “upstream” will point to the repo in the openedx org. Very briefly, the normal flow will be:

  1. Pull from the upstream into your fork to get the latest code.

  2. Make a feature branch in your repo.

  3. Make your changes, and commit them.

  4. Push your branch to your fork (origin).

  5. Make a pull request against upstream.

  6. Once the review is complete, the owning team will approve and merge the pull request.

Creating a fork

Creating a fork is easy:

  • Visit the repo on GitHub.

  • In the upper-right corner is a Fork button. Click it.:

  • On the next screen, you will be asked where to fork it, called the Owner. Choose your own personal account (the default choice):

    • If you are a member of the edx organization, it will be listed in the drop-down, probably with “insufficient permission”, meaning you cannot choose “edx” as the Owner.

    • If you have permissions to fork into your company’s organization, you should check carefully with your process owners to see if you should.

      • The downsides to forking into your organization:

        • Now there will appear to be two sources of truth: openedx/repo and myorg/repo. Developers will have to be careful about which to clone, and which to merge into.

        • There’s now a shared task of keeping the two repos in sync.

Getting the fork locally

How you get the fork locally depends on whether you already have a local repo copy that you want to keep. If you have a local copy but don’t need it, you can delete the repo directory and use “I don’t have a local copy.”

A. I don’t have a local copy

  1. Clone the repo locally: git clone https://github.com/USER/REPO.git

  2. Change to the new repo directory: cd REPO

  3. Add a new remote for upstream: git remote add upstream https://github.com/openedx/REPO.git

B. I have a local copy I want to keep

The rename will change the remote of all your branches to upstream, which is not what you want. So, it is probably best to complete your work and remove the old copy, and then go with plan A.

  1. Rename the existing remote:

    1. Use git remote -v to check that the openedx repo is named “origin”

    2. Rename the remote to “upstream”: git remote rename origin upstream.

  2. Add a new remote for your fork:
    git remote add origin https://github.com/USER/REPO.git

Keeping your fork up to date

You now have two remotes: your fork called “origin” and the openedx core repo called “upstream”. Before beginning work on a change, you will want to get the latest code from upstream into your fork. Keep in mind that some repos use a “master” branch, others use “main”. If you are in a “main” repo, replace “master” with “main”:

  1. Switch the current branch to master: git switch master.

  2. Pull down the changes from upstream and update your master:
    git pull upstream master --ff-only

  3. If everything has been done right, this will be a fast-forward merge, with no explicit merge commit. You shouldn’t have changes on your master, but if you do, the git pull command will fail with “fatal: Not possible to fast-forward, aborting.” If this happens, you will need to fix your master branch before continuing. (TODO: explain how to do this.)

  4. Push the changes to your fork to keep it up to date: git push.

Now your master branch is in sync with upstream, both locally and in your fork on GitHub.

Making a pull request

Making a pull request is very similar to the simple one-remote workflow:

  1. Create a branch locally: git switch -c user/description.

  2. Make your changes and commit them.

  3. Push your branch to your fork: git push -u origin @.

  4. Make a pull request on GitHub. The base repository should automatically choose the upstream repo.

  5. Review and work on the pull request as usual. You can push new commits to your branch as usual.

  6. Ask the owning team to approve and merge your pull request.

Once your code has been merged, the steps in “Keeping your fork up to date” will get you ready for the next iteration of work. You can also use those steps if you need to rebase your pull request to base it on the latest changes on master.

Source material

These pages were helpful: