Git Workflow - HeartUoA/HeaRT GitHub Wiki

Git Workflow Step-By-Step Conventions:

1. Clone the remote repository locally by doing the following:

# 1. Clone the repo into the current directory
git clone https://github.com/HeartUoA/HeaRT

# 2. Navigate to the cloned directory
cd <repo-name>

2. Update your local repository master with the most recent code from the remote repository doing the following:

git checkout master
git pull origin master

3. For every new issue, branch off from master and create a new branch. The branch should follow the Branch Naming Conventions as listed below. Branch off master with the following command:

# For example: 
git checkout -b {git-issue-id}-{feature-desc}

4. Make changes to the feature branch on the local clone, and commit when needed and with well descriptive messages - refer to Commit Messages below.

5. Test your changes by running all the tests.

6. Merge the remote master into your local branch and resolve any merge conflicts:

git checkout master
git pull origin master 
git checkout <branch-name>
git merge master

7. Push your local branch up to the remote repository by doing the following:

git push -u origin <branch-name>

8. Create the pull request:

  • On the "Pull Requests" tab of the main repository, open a PR from <branch-name> => master
  • The pull request should have a title that summarizes the changes.
  • The title of the pull request should not just reference the issue number. It should succinctly describe the actual changes.
  • The body should provide more details about what changes have been made.
  • Add at least two reviewers to the PR.
  • Add the appropriate labels to the PR (including the 'needs review' label).
  • Link the PR to the corresponding Git issue.
  • Refer to the [Pull Request template](link goes here)

9. Merge the pull request into master

  • Once two approvals have been made to your pull request, you (and no one else) can merge the pull request into the remote master branch.

Reviewing Pull Requests

  • Two other group members must review and approve of the pull request before it can be merged.
  • As a reviewer, you must test the changes to make sure they work as intended and do not break any existing functionality.
  • You must check the code to make sure it is well-written.
  • If you are the second reviewer approving the pull request, remove the 'needs review' label from the pull request and assign the 'approved' label to it.
  • As a reviewer, you are not allowed to merge in the pull request. Only the author can merge in their own pull requests.

Branch Naming Conventions

  • Branch names must be lowercase
  • Branch names must be hyphen-separated (-)
  • Branch names must be structured as follows:
    <branch-name>: {git-issue-id}-{branch-description}

Branch Prefixes

  • master - (Development branch) Usually integration branch for feature work and often defaults branch. For pull request workflows, the branch where new feature branches are targeted.
  • {git-issue-id}/ - This prefix at the start of a branch refers to the unique Jira issue number in the product backlog.

Merging Branches

  • We merge {git-issue-id}-{branch-description} branches onto the development branch master.

Commit Messages

  • The main purpose of commit messages is to make it easy to navigate between commits.
  • Capitalise the subject line.
  • Use the imperative mood in the subject line.
  • Limit the subject line to 50 characters and be concise.
  • Do not end the subject line with a period.
  • Separate subject from body with a blank line.
  • Wrap the body at 72 characters.
  • Use the body to explain what and why not the how (the code does that).
  • Reference the issue tracker at the end as follows:
    Resolves: #123
    See also: #456, #789
    

Further reading: Here

Additional Resources:

ohmyz - Make terminal pretty

Sourcetree - UI for git

dev.to - Common Git commands to get started

⚠️ **GitHub.com Fallback** ⚠️