Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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

...

Terminology

Fork: On GitHub, a fork means making is a copy of a repo into 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.

...

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.

...

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

  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.

...