Working with Jira and Github Branches.

Owned by Andrew Watkins
08-04-2019
4 min read

We use Trunk Based Development. - This is a MUST READ.

A source-control branching model, where developers collaborate on code in a single branch called ‘trunk’ *, resist any pressure to create other long-lived development branches by employing documented techniques. They therefore avoid merge hell, do not break the build, and live happily ever after.

* master, in Git nomenclature

To do some work

1. Take a ticket from the Jira project.

Review the current Kanban board and the selected for development tickets. Take one you want to work on and assign it to yourself. Read it through - if it does not contain enough information to complete it - or even get started then contact the product lead or design lead.

2. Create a working branch

git branch <branchname>

e.g

git branch feat/VP-89/Landing_page
git branch bug/VP-92/Crash_on_load_markdown

name branches with the Jira ticket and type e.g. bug/VP-85/LandingPage

Publish (git push) your branch so that we can see it is in progress.

3. Commit code and issue a pull request

Edit the code, write tests, check it all works.

Run all the tests - npm test and verify that nothing else has been broken

Commit the code

Use smart commit messages

Smart Commits allow repository committers to perform actions such as transitioning Jira Software issues or creating Crucible (and Github) code reviews by embedding specific commands into their commit messages.

You can:

  • comment on issues
  • record time tracking information against issues
  • transition issues to any status defined in the Jira Software project's workflow.

https://confluence.atlassian.com/fisheye/using-smart-commits-960155400.html

The basic command line syntax for a Smart Commit message is:

<ignored text> <ISSUE_KEY> <ignored text> #<COMMAND> <optional COMMAND_ARGUMENTS>

Any text between the issue key and the Smart Commit command is ignored.

e.g git commit -m"VP-85  #comment updated readme. "

or git commit -m"VP-85 #done fixed 500 server error. "

add a progress comment or transitions the ticket to done respectively.

4. Issue a pull request

On commit the CI system on the server should validate your commit still runs. if it does you can issue a pull request.

  • Create the PR
  • Summarise what you have changed
  • Ask for a review


Git Cheat Sheet



Branch naming Convention

Name branches as follows:

group/Jira-ticket/label

Group tokens

Use "grouping" tokens in front of your branch names.

group1/VP-85
group2/VP-85 group1/VP-89 group2/VP-89 group3/VP-90

Example Groups - Short well-defined tokens

Choose short tokens so they do not add too much noise to every one of your branch names. 

wip       Works in progress; stuff I know won't be finished soon
feat      Feature I'm adding or expanding
test      Adding testing to a feature
bug       Bug fix or experiment
junk      Throwaway branch created to experiment

Each of these tokens can be used to tell you to which part of your workflow each branch belongs.


You can quickly tell which branches have reached each different stage, and you can group them together easily using Git's pattern matching options.

$ git branch --list "test/*"
test/foo
test/frabnotz

$ git branch --list "*/foo"
new/foo
test/foo
ver/foo

$ gitk --branches="*/foo"

Use slashes to separate parts

Slashes let you do some branch renaming when pushing or fetching to/from a remote.

$ git push origin 'refs/heads/feature/*:refs/heads/phord/feat/*'
$ git push origin 'refs/heads/bug/*:refs/heads/review/bugfix/*'

Slashes also work better for tab expansion (command completion) in my shell. 

$ git checkout new<TAB>
Menu:  new/frabnotz   new/foo   new/bar


$ git checkout foo<TAB>
Menu:  new/foo   test/foo   ver/foo

(Zshell is very configurable about command completion and I could also configure it to handle dashes, underscores or dots the same way. But I choose not to.)

It also lets you search for branches in many git commands, like this:

git branch --list "feature/*"
git log --graph --oneline --decorate --branches="feature/*" 
gitk --branches="feature/*"

Caveat:  Because branches are implemented as paths, you cannot have a branch named "foo" and another branch named "foo/bar". This can be confusing for new users.

Do not use bare numbers

Do not use use bare numbers (or hex numbers) as part of your branch naming scheme. Inside tab-expansion of a reference name, git may decide that a number is part of a sha-1 instead of a branch name. 

$ git checkout CR15032<TAB>
Menu:   fix/CR15032    test/CR15032

If I tried to expand just 15032, git would be unsure whether I wanted to search SHA-1's or branch names, and my choices would be somewhat limited.


Jira Ticket id

e.g VP-89

Format them exactly the same as in Jira  this makes life easy for tracking.

Do not make random changes to the code - there should always be a Jira ticket for the change you want to make - if there is not then create one and use it to describe the bug or feature that the change will effect.  This will also give others a place to comment on the change, log time and design items etc.  It will also allow you to put a change you think you should make but is not - THE NEXT MOST IMPORTANT NEXT THING into a ticket and who knows someone else might do it.

Also don't use a generic ticket for a big mix of changes.  Keep changes focussed on the issue in question - this will make it much easier to back out changes if necessary.

In particular don't fix bugs and add features in the same change set.


Label

A short label to let people know what is being worked on without them needing to look at the ticket.  e.g feat/VP-23/Landing_page.

Spaces not allowed - Use underscores.

Long branch names can be very helpful when you are looking at a list of branches. But it can get in the way when looking at decorated one-line logs as the branch names can eat up most of the single line and abbreviate the visible part of the log.

On the other hand long branch names can be more helpful in "merge commits" if you do not habitually rewrite them by hand. The default merge commit message is Merge branch 'branch-name'. You may find it more helpful to have merge messages show up as Merge branch 'fix/CR15032/crash-when-unformatted-disk-inserted' instead of just Merge branch 'fix/CR15032'.