Pull request workflow¶
Blocks development takes place on GitHub; developers (including project leads!) add new features by sending pull requests from their personal fork (we operate on the so-called fork & pull model).
This page serves as a “quick reference” for the recommended pull request workflow. It assumes you are working on a UNIX-like environment with Git already installed. It is not intended to be an exhaustive tutorial on Git; there are many of those available.
Before you begin¶
Create a GitHub account¶
If you don’t already have one, you should create yourself a GitHub account.
Fork the Blocks repository¶
Once you’ve set up your account and logged in, you should fork the Blocks repository to your account by clicking the “Fork” button on the official repository’s web page. More information on forking is available in the GitHub documentation.
Clone from your fork¶
In the side bar of your newly created fork of the Blocks repository, you should see a field that says HTTPS clone URL above it. Copy that to your clipboard and run, at the terminal,
$ git clone CLONE_URL
where CLONE_URL
is the URL you copied from your GitHub fork.
If you’re doing a lot of development with GitHub you should look into setting up SSH key authentication.
Add the official Blocks repository as a remote¶
In order to keep up with changes to the official Blocks repository, notify Git of its existence and location by running
$ git remote add upstream https://github.com/mila-udem/blocks.git
You only need to do this once.
Beginning a pull request¶
Verify that origin points to your fork¶
Running the command
$ git remote -v | grep origin
should display two lines. The URLs therein should contain your GitHub username.
Update your upstream remote¶
Your cloned repository stores a local history of the activity in remote
repositories, and only interacts with the Internet when certain commands
are invoked. In order to synchronize the activity in the official Blocks
repository (which Git now knows as upstream
) with the local mirror of
the history related to upstream
, run
$ git fetch upstream
You should do this before starting every pull request, for reasons that will become clear below.
Create a new branch for your pull request based on the latest development version of Blocks¶
In order to create a new branch starting from the latest commit in the
master branch of the official Blocks repository, make sure you’ve fetched
from upstream
(see above) and run
$ git checkout -b my_branch_name_for_my_cool_feature upstream/master
Obviously, you’ll probably want to choose a better branch name.
Note that doing this (rather than simply creating a new branch from some arbtirary point) may save you from a (possibly painful) rebase later on.
Working on your pull request¶
Make modifications, stage them, and commit them¶
Repeat until satisfied:
- Make some modifications to the code
- Stage them using
git add
(git add -p
is particularly useful) git commit
them, alternatelygit reset
to undo staging bygit add
.
Push the branch to your fork¶
$ git push -u origin my_branch_name_for_my_cool_feature
Submitting for review¶
Send a pull request¶
This can be done from the GitHub web interface for your fork. See this documentation from GitHub for more information.
Give your pull request an appropriate title which makes it obvious what the content is. If it is intended to resolve a specific ticket, put “Fixes #NNN.” in the pull request description field, where NNN is the issue number. By doing this, GitHub will know to automatically close the issue when your pull request is merged.
Blocks development occurs in two separate branches: The master
branch is the
development branch. If you want to contribute a new feature or change the
behavior of Blocks in any way, please make your pull request to this branch.
The stable
branch contains the latest release of Blocks. If you are fixing a
bug (that is present in the latest release), make a pull request to this branch.
If the bug is present in both the master
and stable
branch, two separate
pull requests are in order. The command git-cherry-pick_
could be useful here.
Incorporating feedback¶
In order to add additional commits responding to reviewer feedback, simply
follow the instructions above for using git add
and git commit
, and
finally git push
(after running the initial command with -u
, you should
simply be able to use git push
without any further arguments).
Rebasing¶
Occasionally you will be asked to rebase your branch against the latest master. To do this, run (while you have your branch checked out)
$ git fetch upstream && git rebase upstream/master
You may encounter an error message about one or more conflicts. See
GitHub’s help page on the subject. Note that after a rebase you will
usually have to overwrite previous commits on your fork’s copy of the
branch with git push --force
.