Islandora Pull Request Instructions

So you want to contribute via a pull request! That's awesome. Here's how:

1. Create your own fork of the repository on Github

You will need to be signed into Github. From within any repository, 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

To create a fresh clone, use git clone to create a local copy. For example, (substituting modulename for the name of your desired module)

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

By default you will be on the 7.x branch, and if you just 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

For a release branch this will look like

$ git checkout 7.x-1.10
$ git pull origin

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. For example, if my github username is lobstersauce:

$ git remote add lobstersauce https://github.com/lobstersauce/islandora

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)
lobstersauce	https://github.com/lobstersauce/islandora (fetch)
lobstersauce	https://github.com/lobstersauce/islandora (push)

4. Create a new 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. The branch name should be the original branch (e.g. 7.x or 7.x-1.10) 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, if you're creating a new release issue branch (n.b. Make sure you went back to Step 2, and are currently on an updated release branch!)

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

5. Make and commit your changes.

After editing some files, use git diff and git status to display what changes have been done. 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."

A note on 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 lobstersauce 

will push the branch that you're currently on to your personal remote (as configured in Step 3).

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

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.