Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 4 Next »

Forks are a standard open source approach to 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.

Terminology

Fork: On GitHub, fork means making a copy of a repo into 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. We are talking about the gentle GitHub term, not the aggressive governance term.

Upstream: the repo you are ultimately contributing to.

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. The normal flow will be:

  1. Pull from the upstream’s master branch into your fork’s master branch to get the latest code.

  2. Make a feature branch in your repo from your repo’s master branch. Don’t work directly

  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):

    • edx will be listed in the drop-down, with “insufficient permission”

    • DO NOT FORK INTO edx EVEN IF YOU CAN. Use your personal account.

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. 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

  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 remote repos (your fork and the openedx core repo) that you might need to get changes from.

  1. Get all the changes locally: git fetch --all.

  2. Switch to master: git switch master.

  3. Merge the changes from upstream: git merge upstream. If everything has been done right, this will be a fast-forward merge, with no explicit merge commit.

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

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/feature-name.

  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.

Source material

These pages were helpful:

  • No labels