View on GitHub

Povio Engineering Guidelines

These are guidelines for the technologies we are using.

Git and Github Guidelines

Git GitHub

Contents

Essentials

A short overview of the git guidelines.

Branches and namings

Commit messages

Make multiple commits and name them according to the content of the commit. Each commit is made out of a Summary and a Description.

Summary

Description

Most standard flow

Repository files

Generally, you only want your repository to just have your code. That is why a good practice is to maintain a .gitignore file within the repo. This file should exclude when possible:

The rule of thumb here is that it is correct to exclude the files which fall into these categories in the .gitignore of the repository when the files are generated by the code/tools from this repo.

When speaking about the OS and IDE files, it is best to maintain a personalized exclude file. You may check whether a global file is configured for your system by running and edit it.

git config --get core.excludesfile

If that command doesn’t return anything, the common solution is to create a .gitignore_global in your user directory and set it as global. For example, on Linux:

touch ~/.gitignore_global
git config --global core.excludesfile ~/.gitignore_global

For a source of inspiration on which files shouldn’t find their way inside your VCS feel free to check out this link.

Workflow Overview

The workflow is based on Gitflow, although not all elements may always be necessary.

Diagram of Gitflow branch structure

Pull Requests

Read GitHub’s guide on Pull Requests (PRs) to understand how they work.

PR should be used in two cases:

Ensure that PR compare the develop branch (not master) with your feature branch.

PR must be mergeable, meaning there should not be any merge conflicts.

Naming convention

We should be consistent naming PRs. They should be named similarly to the branch. Let’s take a look at an example.

Branch name: feature/<name-of-the-feature>. PR name: Feature/<Name of the feature>

When you are using Jira, please add the ticket ID to the name: Feature/<Jira-ID> - <Name of the feature>. Doing it that way, Jira will automatically keep a reference to this branch.

Big Pull Requests

We should be encouraged to create small PRs as possible. But we cannot avoid them all the time. In some cases, we need to include some libraries to the project and it can get big and ugly. In such case we should do the following:

Reviewing Pull Requests

You should have enough context to thoroughly review the committed code just by reading it as a reviewer. However, there are times when the pull request is a bit on the large side, or it is referencing existing code not found in the PR, or you, for some other reason, do not have a good enough context to review anything other than code style and typos. In these cases, we encourage you to approach the PR submitter and go through the pull request together.

As a reviewer, your job is to be the extra pair of eyes so that the code will get twice as good. You will look at things such as code style and structure. You will discuss things you might have done differently, point out possible, more elegant solutions based on something you have learned, and so on. The goal here is to make the whole team better in the process.

Remember that you are reviewing something someone else has worked on hard, so always be respectful. These guidelines for giving feedback are a good reference:

This is based on GitHub’s How to write the perfect pull request.

Keeping up to date

When working on a feature branch, it is important to regularly pull everyone else’s work from develop. Assuming you are working on feature/your-feature-branch, use the following steps taken from this StackOverflow answer.

First check if there are even any changes on develop to pull from GitHub.

git fetch origin

If there are changes, switch to develop and fast forward to the latest.

git checkout develop
git merge --ff origin/develop

--ff means fast-forward merge. In theory you shouldn’t have made any commits to develop since you last left it, so you should be able to just fast forward it to the latest commit you’ve pulled down. If this fails, you might have accidentally committed to develop at some stage. If not, it means someone rebased the remote develop branch (which is bad…)

Now go back to your feature branch.

git checkout feature/your-feature-branch

The following steps depend on whether your changes are local or have been pushed to GitHub.

[Option 1] If you haven’t yet pushed your changes to GitHub

You can simply rebase from develop, replaying your changes on top of the changes you just pulled from GitHub

git rebase develop

[Option 2] If you have already pushed your changes to GitHub

Do not rebase, this rewrites the history of the branch, and will cause problems when you try and push back to GitHub. Instead, merge the updates back into your feature branch.

git merge develop
git push origin feature/your-feature-branch

Collaborating on a feature

Feature branches will need to be pushed to GitHub for:

Push your local feature branch to GitHub for the first time

If you have created a local feature branch called feature/cool-feature, push using:

git push -u origin feature/cool-feature

The -u argument is not essential, it just tells Git to set up a tracking reference for the remote branch. It means you can do something like git fetch origin; git status; and it will let you know if you are behind the remote branch. Subsequent pushes do not require the -u argument.

Clone someone else’s remote feature branch
git fetch
git checkout -b feature/cool-feature origin/feature/cool-feature

This creates a new local branch called feature/cool-feature that is based on the remote branch called origin/feature/cool-feature that you just fetched.

Push updated code on a feature branch

If you want to push further commits back to GitHub, use the same push command as before, but without -u:

git push origin feature/cool-feature
Pull updates on a feature branch

While on feature/cool-feature:

git pull --rebase origin feature/cool-feature

Example Flow

Get started

Perform the following to clone the repository’s develop branch:

git clone https://github.com/poviolabs/project-name.git

Start work on a new feature

To work on a new feature you need to create a new feature branch for your changes.

git checkout -b feature/your-feature-branch develop

You can omit develop if you are already on the develop branch

Do some work

While on your feature branch, make your changes and commit them as usual.

Finished with your feature

Code Review completed

Once a team member has reviewed your code and everything is okay, one of you should either:

git checkout develop
git merge --no-ff feature/your-feature-branch
git push origin develop

Why use –no-ff?

Git Tools

Git Aliases

[alias]
	c = "!git add -A && git commit -m "
	p = !git push origin $(git rev-parse --abbrev-ref HEAD)
	n = !git checkout -b
	s = !git status
	l = !git log
	b = !git branch
	ch = !git checkout
	m = !git merge
	gr = !git reset --soft HEAD^
	pull = !git pull origin $(git rev-parse --abbrev-ref HEAD)

Example of usage:

g p -> git push origin <current branch>
g l -> git log
g s -> git status

##Credits Git Workflow Guide