Developing a Feature (or bug, chore)

This is an overview of developing a feature (or fixing a bug, completing a chore, etc) - for the SHF project - focusing on how to effectively use git and Github.

It is assumed that the development environment has been previously setup as follows:

1. The project repo (https://github.com/AgileVentures/shf-project) has been forked into your personal repo (https://github.com/<username>/shf-project) (Replace "<username>" with your Github user name)
2. You have cloned your personal repo to your local development machine and thus have a local repo
3. You have established the project repo as a remote repo to your local git environment and named it upstream
4. You have established the personal repo as a remote repo to your local git environment and named it origin (this should have happened by default when you cloned your personal repo in step 1 here
5. Your local repo contains at least two branches reflecting the project (upstream) repo: master and development
6. You have access to the Pivotal Tracker (PT) Board associated with this project (https://www.pivotaltracker.com/n/projects/1904891)

Developing a new feature

Step 1: Update Pivotal Tracker

When you are ready to start work on a story (feature, bug or chore):

1. Assign the specific story that you will work on to yourself (please don’t assign yourself an issue unless you actually going to start work)
2. Click on the "Start" button

Step 2: Update local repo development branch

Reason: Your local repo development branch needs to stay in sync with the project repo development branch. This is because you want to have your feature branch (to be created below) to have the latest project code before you start adding code for the feature you’re working on.

Mechanics (all in local repo):

git checkout development
git fetch upstream
git merge upstream/development

You should not have merge conflicts in this step , unless you’ve made changes to your local development branch directly (which you should never do).

Step 3: Create the feature branch in local and personal repos

Reason: All of your development should occur in feature branches - ideally, one branch per PT ticket. This keeps your local development branch clean (reflecting upstream repo), allows you to abandon development approaches easily if required (e.g., simply delete the feature branch), and also allows you to maintain multiple work-in-process branches if you need to (e.g., work on a feature branch while also working own fixing a critical bug - each in its own branch).

Mechanics (all in local repo):

1. Create a branch whose name indicates the PT story. For example, if you are going to work on issue #781123 (which is, say, a new feature for ‘forgot password’ management):

    git checkout -b forgot-password#781123
   

   This both creates and checkouts that branch in one command.
   The feature name should provide a (short) description of the issue. It can be useful to include the PT story number in the branch name, as done here.

2. Push the new branch to your personal repo:

    git push -u origin forgot-password#781123
   

Step 4: Develop the Feature

Develop the code for your feature (or chore/bug) as usual. You can make interim commits to your local repo if this is a particularly large feature that takes a lot of time.

When you have completed development, make your final commit to the feature branch in your local repo.

Step 5: Update local repo development branch (if required)

Didn’t we just do this is step 2? Yes, but there may have been changes to the upstream repo in the meantime, and we want to incorporate those changes into your feature branch before you create a pull request.

so you really only need to do this if any commits have occurred to the development branch in the project repo since you performed step 1. You can check this by comparing the latest commit on that branch to the commit history in your development branch in your local repo.

The latest commit in the project repo can be seen on Github (make sure you select the development branch).

Mechanics (all in local repo):

git fetch upstream
git merge upstream/development

Step 6: Rebase development changes into feature branch (if required)

If no changes were pulled down from upstream repo in the prior step, then skip this step. Otherwise, you will need to rebase changes from the local repo development branch into the feature branch. This means taking changes that are present in the development branch - that were added to development after you created the feature branch in step 2 (and added to your local development branch in the prior step) - and adding these changes into the feature branch.

Reason: This step will add changes to your development branch that have already been applied to the project repo development branch.

Mechanics (all in local repo):

git checkout <feature-branch-name>
git rebase development

Run all tests (rspec, cucumber) to confirm that any changes brought in by rebasing did not break anything.
If there are errors, fix those and repeat steps 5 and 6.

Step 7: Push feature branch to personal repo

Reason: We will now push the feature branch code to github so that we can create a Pull Request against the project repo (next step).

Mechanics (all in local repo):

git checkout <feature-branch-name>
git push origin <feature-branch-name>

Step 8: Create Pull Request (PR)

Mechanics (all in personal repo on Github):

1. Go to your personal repo on Github

2. Select the development branch in the “Branch: “ pull-down menu

3. Click the “Compare” link

   On the next page, the “base fork” and “base” should be AgileVentures/MetPlus_PETS and development, respectively.

4. Confirm “head fork: is set to username/MetPlus_PETS

5. Set “compare: “ to your feature branch name (e.g. forgot-password-#78)

6. Review the file changes that are shown and confirm that all is OK.

7. Set the title of the pull request -

   If this PR closes a waffle issue:

    Closes AgileVentures/MetPlus_tracker#nn
   

   If this PR does not close a waffle issue:

    Connects to AgileVentures/MetPlus_tracker#nn
   

   where "nn" is the issue number in Waffle.

   This should cause github to automatically move the Waffle issue to the 'Done' column, once the PR is merged into the project repo (if closing an issue), or associate the PR with a waffle issue (if not closing the issue). (The "Closes" and "Connects to" portions of the title are critical and should be written verbatim)

8. Click “Create Pull Request”

This last step will kick off a CI (continuous integration) process that will configure a test environment, load your changes, run all code tests (rspec, cucumber) and perform other checks configured within the CI tool (this project is using Semaphore). If any problems arise you will see those at the end of the CI run and will need to address those before the Pull Request can be merged into the project repo.

Step 9: Confirm Waffle Status

Move the issue to the ‘Need Review’ column.