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 the develop branch reflecting the project (upstream) repo: develop branch
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 a story unless you actually going to start work)
2. Click on the "Start" button

Step 2: Update local repo develop branch

Reason: Your local repo develop branch needs to stay in sync with the project repo develop 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 develop
git fetch upstream
git merge upstream/develop

You should not have merge conflicts in this step , unless you’ve made changes to your local develop 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 develop 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 sprint number PT story. For example, if you're in sprint 14 and are going to work on PT story #781123 (which is, say, a new feature for ‘forgot password’ management):

    git checkout -b sprint14-forgot-password#781123
   

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

2. Push the new branch to your personal repo:

    git push -u origin sprint14-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 develop 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.

Mechanics (all in local repo):

git fetch upstream
git merge upstream/develop

Step 6: Rebase or merge 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 develop branch into the feature branch. This means taking changes that are present in the develop branch - that were added to develop after you created the feature branch in step 2 (and added to your local develop branch in the prior step) - and adding these changes into the feature branch.

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

Mechanics (all in local repo):

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

NOTE: If there have been a lot of changes to develop coming into your feature branch, and your feature branch contains many commits, it is sometimes easier t just merge the develop changes into your feature branch, e.g.:

git checkout <feature-branch-name>
git merge develop

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>

Note: If you rebased your feature branch (step 6) then you should force you push to origin - that is, the second command above would actually be:

git push -f 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 feature branch in the “Branch: “ pull-down menu

3. Click the “Compare” link

   On the next page, the “base fork” and “base” should be AgileVentures/shf-project and develop, respectively.

4. Confirm “head fork: is set to username/shf-project

5. Confirm “compare: “ is to your feature branch name (e.g. sprint14-forgot-password-#781123)

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

7. Click “Create Pull Request”

8. On the next page, give the PR a title, enter the URL to the PT story, and provide all other information as requested in the PR template.

9. Click “Create Pull Request”

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

10. Add the PR number (assigned by Github when the PR is created - it will appear in greyed-out text at the end of the PR title) as a prefix to the PT story title. That is, if the PT story title is "Allow user to request password reset", and the Github PR number is "123", then set the PT story title to "123 - Allow user to request password reset".