OcsDevelopmentSetup

Setting Up Your Workspace for OCS Development

Prerequisites

1. Install git on your machine. I believe this comes with installing the developer tools / Xcode.
2. Create a GitHub account and get somebody to add it to the Gemini HLSW organization team. Replace YOUR-USERNAME in the commands below with your user id.
3. (Optional) Cache your GitHub password in git so that you don't have to type in your password all the time. See the git help on caching your password.
4. (Optional) I recommend installing a couple of utilities that make working with git a little easier:
   • git command completion
   • git prompt feedback

Fork the Repository

We'll all work on our own individual forks of the main repository. The first step is to fork the repository at https://github.com/gemini-hlsw/ocs. In the upper-right corner of the page, click “Fork”. This will fork the repository to your personal account. Of course, you haven’t actually fetched any of the files to local disk yet. To do that, you’ll clone your fork on your local machine via the command line:

$ git clone https://github.com/YOUR-USERNAME/ocs

Next, set up git to be able to pull changes from the “central” ocs repository

$ cd ocs # change directories to the location of your fork
$ git remote add central https://github.com/gemini-hlsw/ocs.git
$ git remote -v

Set Up OCS Credentials

Emails and passwords are kept in a separate file in the build, project/OcsCredentials.scala. This file must not be checked in to the public git repository and in fact is included in our .gitignore (along with a couple of other sensitive files). Instead, find a top-level project called ocs-credentials in our old SVN repository. You should check this project out somewhere on disk and then run the link.sh script it contains to setup symlinks back to these files

$ svn co ... ocs-credentials
$ ocs-credentials/trunk/link.sh -v path/to/ocs 

Use the --dry-run argument if you want to check what it would do before actually committing to it.

Create Your First Feature Branch

All features and bug-fixes should be done in separate branches that are ultimately merged back to the “central” development repository via a pull request. This is different than our old svn-based work flow but a natural migration with git. To get started, from your cloned fork of the ocs repsitory, switch the development branch and bring it up to date

$ cd path/ocs
$ git checkout develop
$ git pull

Finally create a new branch for developing the latest feature request. If this is based on a JIRA ticket, reference it in the name. (If it isn’t, ask yourself if it should be based on a JIRA ticket and if so go create one). For example, say this is related to the JIRA REL project, issue 123:

$ git checkout -b feature/REL-123

Do some work, run your tests, commit the changes back to your fork:

$ vi somefile # or whatever
$ git commit -a -m “REL-123: foo”
$ git push origin feature/REL-123

Fetch Updates and Merge Them

As time passes your branch can get out of sync with development efforts pushed to the central repository by others on the team. Update it from time to time so that you aren't faced with a more difficult conflict resolution session than absolutely necessary. To get your work up-to-date, use git rebase rather than a simple merge. That will place your changes after those that have already been merged into the integration branch from which your branch was started.

$ git checkout develop # go back to develop branch
$ git pull central develop # incorporate the latest updates
$ git push origin # push them to your fork
$ git checkout feature/REL-123 # switch back to your feature branch
$ git rebase develop

If you've already opened a pull request for your feature, don't worry. It will be updated to reflect any changes that you make.

When push comes to shove

Assuming you've already pushed changes to your fork, a rebased local feature branch can no longer be pushed cleanly.

$ git push origin feature/REL-123
To https://github.com/swalker2m/ocs
 ! [rejected]        feature/REL-123 -> feature/REL-123 (non-fast-forward)
error: failed to push some refs to 'https://github.com/swalker2m/ocs'

You can get around this with a push -f or push --force

$ git push -f origin feature/REL-123
...
 + 7d1b7de...d02a552 feature/REL-123 -> feature/REL-123 (forced update)

This will keep the "network" graph commit/history clean when the PR is ultimately merged.