-
Notifications
You must be signed in to change notification settings - Fork 66
Developing a feature (or bug, chore)
This is an overview of developing a feature (or fixing a bug, completing a chore, etc) - for the PetPlus PETS project - focusing on how to effectively use git and Github.
It is assumed that the development environment has been previously setup as follows:
- The project repo (https://github.com/AgileVentures/MetPlus_PETS) has been forked into your personal repo (https://github.com/username/MetPlus_PETS) (Replace "username" with your Github user name)
- You have cloned your personal repo to your local development machine and thus have a local repo
- You have established the project repo as a remote repo to your local git environment and named it upstream
- 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 2
- Your local repo contains at least two branches reflecting the project (upstream) repo: master and development
- You have access to the Waffle Board associated with this project (https://waffle.io/AgileVentures/MetPlus_tracker)
When you are ready to start work on a Waffle issue:
- Assign the specific issue that you will work on to yourself (please don’t assign yourself an issue unless you actually going to start work)
- Move the issue (drag and drop) to the ‘In Progress’ column
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 step 3, unless you’ve made changes to your local development branch directly (which you should not do).
Reason: All of your development should occur in feature branches - ideally, one branch per Waffle 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):
-
Create a branch whose name contains the Waffle issue number. For example, if you are going to work on issue #78 (which is, say, a new feature for ‘forgot password’ management):
git checkout -b forgot-password-#78
This both creates and checkouts that branch in one command.
The feature name should provide a (short) description of the issue, and should include the issue number. -
Push the new branch to your personal repo:
git push -u origin forgot-password-#78
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.
Didn’t we just do this is step 2? Yes, 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 checkout development
git log —oneline
The "log" command will show the commit history in descending (time) order.
If the commit history does not include the latest commit in the project repo, then do the following:
git fetch upstream
git merge upstream/development
If you did not have to update the local repo development branch 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 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. The result is that when you deliver your feature (that is, create a Pull Request), those changes will not be (needlessly) included in that Pull Request.
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.
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>
Mechanics (all in personal repo on Github):
-
Go to your personal repo on Github
-
Select the development branch in the “Branch: “ pull-down menu
-
Click the “Compare” link
On the next page, the “base fork” and “base” should be AgileVentures/MetPlus_PETS and development, respectively.
-
Confirm “head fork: is set to username/MetPlus_PETS
-
Set “compare: “ to your feature branch name (e.g. forgot-password-#78)
-
Review the file changes that are shown and confirm that all is OK.
-
Provide a short but informative title.
-
Note the Waffle issue in the "description" section -
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 will cause github to automatically move the Waffle issue to the 'Need Review' column once the PR is created, and move the 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 above are critical and should be written verbatim)
-
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.
Move the issue to the ‘Need Review’ column.
-
Backlog Container with all the stories that are not really ready or that are not prioritized
-
Sprint Creation Place where prioritized stories are, but are not 100% ready to start working, does not have enough context on them or are waiting for pointing
-
Ready Stories that are ready to be picked up. Also this is the entry point for the PR's that are not associated with a story
-
In Progress When you start a story you should move the story to that column
-
Needs Review Is a story with a PR that is waiting for a review to be merged. Also if you create a PR and use
closes AgileVentures/MetPlus_tracker#issue-number
then the story will move to this column Done: PR as been merge (automatically move to this column if the story is linked with the PR) or story was closed due to some other reasons