Code Repository and Branching Strategy

This document provides a guideline for your code repository and branching strategy to follow. To interact with GitHub and follow along, you will need to install git on your local machine and ensure you have an account registered on GitHub.

Depending on your role within the team, you will use one of the following workflows:

Product Management workflow

Used by Product Owners and Business Analysts to sign off user stories.

Development workflow

Used by Developers to implement user stories.

Before diving into the details of the workflows, let's first look at the basic git commands applicable to both workflows.

Note: We will use an example repository throughout this document. This will allow you to follow along and practice the commands.

Basic Git Commands

Cloning a Repository

The first step when working with a GitHub code repository is to create a clone. Cloning a repository means you make a copy of what is in GitHub on your local machine.

To create a local clone of a GitHub repository, follow these steps:

Using your browser, navigate to the repository: https://github.com/{Username}/{RepositoryName}. Notice the URL pattern: you will need the username of the owner of the repository and the repository name.

Verify that the correct repository is loaded and use the < > Code button to copy the repository URL

Navigate on your local machine to a directory where you would like to store the repository: cd {drive}:\{directory}\.

cd C:\Data\

Clone the repository using the git clone command, then paste the URL you copied in step 3.

git clone https://github.com/FlippieCoetser/r.template.git

a new directory will be created after successfully cloning the repository. Change the directory into the newly created directory and list the contents in the directory.

cd r.template
dir

Verify the content in this folder match the content in GitHub.

If the content does not match, follow the update local repository section below.

Update local repository

The content of the local repository will not update automatically when changes are made to the cloud repository. It is good practice before you start working to update your local repository with the latest changes from the cloud repository. This is achieved with the git pull command.

Ensure you are in the correct directory and run the git pull command.

git pull

Development Workflow

Create a new branch

When agile requirements are used, it is typical for the issue in GitHub to reference a user story. Essentially, the user story defines a new feature or bug fix the Product Owner wants implemented.

The development team typically discuss the user story with the Product Owner to align expectations and scope. The team may also break down the user story into smaller tasks assigned to different developers.

Example:
As a user,
When I want to plan my day,
I want to see a list of todos,
So that I can prioritize my work.

The example above may seem simple, but in reality, it touch many parts of the application. For example, an User Interface needs to be designed, or a database needs to be created.

Typically the smaller tasks will fall under one of the below categories:

INFRA, PROVISION, RELEASE, DATA, BROKERS, FOUNDATIONS, VIEWS, PROCESSING, ORCHESTRATION, COORDINATIONS, MANAGEMENT, AGGREGATIONS, CONTROLLERS, BASE, COMPONENTS, PAGES, ACCEPTANCE, INTEGRATIONS, CODE RUB, DOCUMENTATION, CONFIG, MINOR FIX, MEDIUM FIX, MAJOR FIX, REVIEW, STANDARD, DESIGN, BUSINESS, UNKNOWN

The next step is for the developer to create a new branch for the assigned task. For example, assume a developer is assigned to design a new database table to support the storage of todos.

The task categorisation is DATA, the business entity is todo, and the action is retrieve.

A new local branch can be created using the above information as follows: users/{GitHubUsername}/{Type}-{Entity}-{Action}.

Based on the above example, the branch name will be: users/FlippieCoetser/Data-Todo-Retrieve.

Create a new branch

git checkout -b users/FlippieCoetser/Data-Todo-Retrieve

Note: Following this exact naming pattern is not always possible. However, it is essential to ensure the branch starts with users/{GitHubUsername}/. The last part of the branch name should describe the work. If unsure, discuss it with the team or consult the product owner.

Push the new branch to the cloud repository

The command you executed in Step 1 will switch to the newly created branch automatically. Meaning any changes made to the code will be made to the new branch. However, the new branch only exists on your local machine. To make the new branch also available in the cloud repository, you need to push the new branch to the cloud repository.

git push --set-upstream origin users/FlippieCoetser/Data-Todo-Retrieve

Verify the new branch is available in the cloud repository

Commit Changes

A test-driven development (TDD) approach is used to ensure the code is of high quality. This means that code change happens in pairs:

A failing unit test is written
The code is written to make the unit test pass

It would be best if you program with intent and purpose. The commit message should reflect this. Could you create a new branch if you want to explore or experiment with an idea? Once you are happy with the results and comfortable implementing your idea, switch back to the branch where the implementation is needed and follow the TDD approach.

The rationale for not exploring or experimenting in the branch where the implementation is needed is to ensure the Product Owner can track the user story's progress and ensure the main branch is not polluted with unnecessary code.

The commit message should be clear and concise. It should describe the work done and the status of the work. It is recommended to use the following commit message structure: {Type}: {TestCondition} -> {StatusStatus}.

Again this might only sometimes be possible. For example, you will not write unit tests if you want to add documentation or configuration files. In such a case provide a clear commit message which describes what you have done.

Below is an example of work done to implement the Retrieve operation in the Todo broker in an R code base.

Create a new unit test which test if a Todo broker exists.

Note: the code snippet below is an example and is based on R. The same principle applies to other languages.

# test-Broker.Todo.R
describe('Given Broker.Todo', {
  it('exists', {
    #Given
    Broker.Todo |> is.null() |> expect_equal(FALSE)
  })
})

Ensure the test fails and Stage changes

git add tests/testthat/test-Broker.Todo.R

Commit changes with a clear and concise message

git commit -m "BROKER: Todo.Broker Exist -> Fail"

Push the changes to the cloud repository

git push

Options step: Check if the changes are available in the cloud repository. Navigate to the cloud repository and change the branch to the newly create one and click the commits link. You should see the commit message and the files changed.

Write the code to make the test pass

# Broker.Todo.R
Broker.Todo <- \() {}

Ensure the test pass and Stage changes

git add Broker.Todo.R

Commit changes with a clear and concise message

git commit -m "BROKER: Todo.Broker Exist -> Pass"

Push the changes to the cloud repository

git push

You should not see a failing test followed by a passing test directly in the comment message.

The above steps are repeated until the user story is completed.

Creating a Pull Request

Once the user story is completed, the Product Owner will perform user acceptance testing and hopefully approve the new feature.

Assuming the Product Owner has signed off on the user story, the branch is ready to be merged back into the main branch. To do so a pull request is created in GitHub. Although the command-line interface can be used to create a pull request, the Product Owner will typically create the pull request via the GitHub web interface.

Using the browser navigate to the repository and select Pull requests in the tab strip. You should already see a suggestion from GitHub to create a pull request.

Rather click New pull request than accept the suggestion. This will ensure you consciously select the correct branch to merge into the main branch.

Select the correct branch to merge into the main branch and click Create pull request.

Update the pull request Description with a clear and concise message and click Create pull request.

GitHub will automatically run all unit tests and check if the code can be merged into the main branch without conflicts. To merge the changes into the main branch, click Merge pull request.

Delete Branch

Once the code has been merged into the main branch, the branch can be deleted. This is a two-step process:

Delete the branch from the cloud repository

git remote update origin --prune

use git branch --all to list all branches: local and remote.

Delete the branch from the local repository

git branch -d users/FlippieCoetser/Data-Todo-Retrieve

Product Management Workflow

Product Owners involved in singing off user stories will typically only use Git Clone, Git switch, and Git Pull commands in addition to the actions performed in the GitHub web interface.

We already covered the Git Clone and Git Pull commands in the previous section. So let's look at Git switch. After cloning the code repository, the Product Owner may want to first see the new feature before signing off on it.

To do this, the Product Owner will follow the below steps:

Clone the repository if not already done

git clone https://github.com/FlippieCoetser/r.template.git

Switch to the branch containing the new feature

git switch users/FlippieCoetser/Data-Todo-Retrieve

Pull all changes from the cloud repository

git pull

Run the application and test the new feature

After running the application from this branch, the Product Owner can then sign off on the user story and approve the pull request. The pull request will then be merged into the main branch and the branch can be deleted.

Create a pull request via the GitHub web interface
Merge the pull request via the GitHub web interface
Delete the branch in the GitHub web interface and locally

FlippieCoetser/GitHub.Workflow