Git Workflow Suggestions

DRAFT BY ROSIE Oct 13 2016 I'd like to merge this into existing documentation; it's here for feedback.

Start with a copy of the code

Do you have a local copy of the repo you want to change?

• no: $ git clone https://github.com/Islandora/islandora_scholar
• yes: $ git remote -v // make sure that github.com/Islandora is named 'origin'.
• it's in my vagrant box: either ssh into your vagrant box and use command-line tools (like vim) to do all your editing, OR, use Shared Folders (a virtualbox feature that you can use by editing the Vagrantfile) following instructions here.

And a forked Islandora repo.

Do you have a personal fork of the repo you want to change?

• no: go to github and fork the repo to your personal github. Then do $ vagrant remote add myname https://github.com/myname/islandora_scholar
• yes: you just did $ git remote -v; make sure it's called 'myname'

Base your commits off of the most recent code.

Start by checking out the master branch, 7.x

$ git checkout 7.x

Then update your git so that it has the latest 7.x commits. (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.)

$ git pull origin 7.x

Create an issue branch.

Now that you're up to date, let's do all this issue work on an issue branch. This branch 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 HEAD (7.x or 7.x-1.releaseversion )

$ git checkout -b 7.x-ISLANDORA-9999 using your issue number there.

Code, commit, and push to your fork.

Now make your changes to code, and test them. When you're happy: Do this from the module folder, NOT from a sub-folder. pwd should return [...]/sites/all/modules/islandora_scholar.

$ git diff // see what you've changed. Keep it clean!

$ git add . // add all the files you've changed in the current folder and below.

$ git commit -m "ISLANDORA-9999 Add option to set derivative size."

$ git push myname 7.x-ISLANDORA-9999 // this is important! Do not push directly to the Islandora github; push to your own.

Create a pull request

In your browser, go to github. If you are on the repo you just changed, you'll see a convenient notification about "Your recently pushed branches" and an option to "Compare and pull request". Do that.

If it's been a while and that notification isn't there, click "pull requests" and "new pull request". You may also need to click "compare across forks".

• Base fork: islandora
• Head fork: your repo.

If you don't see a checkmark and "Able to merge" then you should go back and make sure you based your branch off of the correct branch (origin/7.x)

Click "Create pull request".

Edit the template, removing all example text for your own. When you're done, click "Create pull request"

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

You should see Branch 7.x-1.8 set up to track remote branch 7.x-1.8 from origin. If, instead, you see error: pathspec '7.x-1.8' 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.8-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.8-ISLANDORA-9999

and repeat the steps where you create a pull request in github.