How To Create A Pull Request (Github 101)

If you encounter ANY issues with this or have suggestions, please tell a Committer or propose a fix! This is a working document and needs some polish. There is nothing too trivial, your feedback will make writing this worth it.

So you want to contribute via a pull request! That's awesome. You've got a CLA on file, right? OK, there are two ways:

Option 1:

Follow Github's instructions to edit a single file and make a pull request. This works if there's a single file to change, such as a README. But we suggest using the second option for most pull requests.

Option 2:

Put the code in an issue branch on your own fork of the repository, then pull against Islandora's code.

1. Create your own fork of the repository on Github

You will need to be signed into Github. From within any repository that's owned by Islandora, click "Fork". You'll watch your fork being made, or get taken directly to your forked version if you already have one.

2. Get a current local copy of the Islandora code.

You will need a computer with Git installed. Before you start a new branch, your code needs to be up to date with the upstream code in the github.com/Islandora repository.

If you're starting fresh:

If you don't have a local copy of the repo you want to change, use git clone to create one. For example:

$ git clone https://github.com/Islandora/islandora_scholar

By default you will be on the 7.x branch, and if you just now cloned it you know it's up to date.

If you already have the module locally:

For instance, if you're using the Vagrant box, or if you've already done a pull request. Navigate into that module's folder, change your branch to the desired target branch, and use git pull to update your code.

$ git checkout 7.x
$ git pull origin

Note: You probably got a message "Your branch is up-to-date with 'origin/7.x'" when you did the above line. Do not trust it, unless you have done a git pull or git fetch very recently.

3. Add your personal fork as an additional remote

Even if you have committer privileges, we never push directly to repositories owned by Islandora. Use the git remote add command to add the github repo that you created in Step 1 (i.e. your own personal fork) as a remote. Replace myname with your actual github username.

$ git remote add myname https://github.com/myname/islandora_scholar

Then, you can use git remote -v to see that there are two remote repositories attached:

$ git remote -v
origin	https://github.com/Islandora/islandora (fetch)
origin	https://github.com/Islandora/islandora (push)
myname	https://github.com/myname/islandora (fetch)
myname	https://github.com/myname/islandora (push)

4. Create a new Issue branch

Now that you're up to date, let's do all this issue work on an issue branch. Creating an issue branch is good in general because it keeps your code tidy, especially if you have multiple issues on the go. It also lets you update a pull request if changes are requested. Also, the naming scheme that we use links Github pull requests to JIRA issues. There should be a JIRA ticket accompanying your pull request, unless you have a very straightforward change (such as a typo or documentation or README update) in which case the branch name doesn't matter.

When you create a branch, it will start from wherever you are right now. Therefore, if you're already on an issue branch, DO NOT directly cut a new issue branch. Always start from 7.x or 7.x-1.releaseversion.

Islandora's Naming Scheme for Issue Branches:

The branch name should be the original branch (e.g. 7.x or 7.x-1.releaseversion) plus the JIRA ticket ID (e.g. ISLANDORA-1234). Use git checkout -b to create a new branch, for example:

$ git checkout -b 7.x-ISLANDORA-1234

or

$ git checkout -b 7.x-1.11-ISLANDORA-1234

5. Make and commit your changes to your local issue branch.

After editing some files, use git diff and git status to display what's been changed (keep it clean! No extraneous changes please). If you are happy with them, use git add . to "stage" the changes, and git commit to create a commit:

$ git add .
$ git commit -m "ISLANDORA-1234 Fix typo in README."

#### Islandora's Naming Scheme for Commit Messages

• Start with the issue name in all caps.
• Use the imperative to succinctly state what changed ("Fix bug" not "Fixed bug" or "Fixes bug")
• Keep the first line short (~50 characters).
• If you need to include a detailed description, leave a blank space after the first (summary) line and wrap your description at or below 72 characters per line. This blog post by Tim Pope explains why.

Tip: Using the git command line tool you can add multi-line commit messages by typing a \ at the end of a line and continuing to type. E.g.,

$ git commit -m "ISLANDORA-110 Cannot delete content model when there is only one left.\
\
Remove logic that prevents delete widget from being drawn."

6. Push your branch to your personal fork

Again, only ever push to your personal repositories, never to Islandora.

$ git push myname HEAD

will push the branch that you're currently on to your personal remote (as configured in Step 3). If you're lucky, git push myname may be a shortcut, but requires your git settings to be configured in a non-default way.

7. Create a Pull Request

If you load the github page for the repository that you forked from, you'll see a yellow bar. Follow the instructions and FILL OUT THE TEMPLATE then create the pull request. Also, go to JIRA and mark it as "Ready for test".

8. Repeat for Release (if needed!)

Now for the release branch! If you're in the release cycle AND your PR is solving a bug, documentation task, or code task, then you need to make a release PR. We don't do release PRs for new features or improvements.

Go back to your code.

$ git checkout 7.x-1.11

You should see Branch 7.x-1.11 set up to track remote branch 7.x-1.11 from origin. If, instead, you see error: pathspec '7.x-1.11' did not match any file(s) known to git. then do $ git fetch origin and try again.

Create your release issue branch. $ git checkout -b 7.x-1.11-ISLANDORA-9999

Cherry-pick the commits from your fix on the head branch. Go from oldest to newest, copying the SHA from github's list of commits, do

$ git cherry-pick 68e60028f99051910c0a7c95ecd45adde37bcaca // your SHA there.

These have now been committed to your local branch. Do

$ git push myname 7.x-1.11-ISLANDORA-9999

and repeat the steps where you create a pull request in Github, only this time as the "target" branch choose the appropriate release branch.

Now that you've created a pull request:

• someone needs to review it, to prove that the code works. Our branches are currently "protected", requiring a committer to give an approving review before it can be merged.
• 24h needs to pass, to give a sane amount of time for someone to speak up who think the pull request shouldn't go through.
• All concerns raised in the comments need to be addressed. If you push more commits to your topic branch, you can update your pull request.
• Someone who is an Islandora committer, and who does not work in the same organization as you, and who did not contribute code to the pull request, will merge it.