...

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:

...

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

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:

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 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. You can also use those steps if you need to rebase your pull request to base it on the latest changes on master.

...