Git Etiquette

Standardized workflow frame for teams and individuals.

Features

• Git strategy for branching
• Issues, labels and project board automation
• Git command cheat sheet

Table of Contents

1. Introduction
2. Getting Started
- Project board
- The labels for issues
- Issues forms and pull request template
- Workflow file setup
- Base tree for repository
3. Git strategy and usage
- Bedrock Rules
- Branch Strategy
- Formatting Rules
4. Useful Git Commands
- How to Create a Branch (via Git)
- Deleting Branches Locally & Remotely
- .gitignore
- Adding .gitignore into already existing repository
- Merging Branches
5. Cheat Sheet
6. Featured organizations, teams, and projects that utilize the Git Etiquette
7. How to Contribute
8. Authors
9. License

---

Introduction

The main focus of Git Etiquette is to provide a standard way of using Git and project management tools that is shared among developers, which helps to ensure that everyone is on the same page and following the same standardized workflow frame.

By following the Etiquette, the team can ensure that their workflow will be more consistent, work will be properly documented and their use of the git will be more efficient. Additionally, it provides clear instructions for using Git, which helps to minimize the risk of errors and improves the quality of the work being done.

The background story for Git Etiquette is that it was started as a personal project to create a unified and coherent workflow for personal use. The goal was to make it easier for others to understand the work being done and navigate the history of the project more easily.

My team leader was excited about my personal project I was working on and assigned me to write it up so that the rest of the team could benefit from it.

(back to top)

---

Getting started

1. Project board
2. The labels for issues
3. Issues forms and pull request template
4. Workflow file setup
5. Base tree for repository

(back to top)

Project Board

Here's how you setup your project board, which is a crucial part of automation and project management.

Views

Project views allow you to view the project from different layouts and are located at the top as tabs.

Set up for each view:

Name	Layout	Group	Fields
List view by status	Table	Status	All, except Milestones
Board view	Board	Default	All, except Milestones, Tracks, Tracked by
List all	Table	Default	All, except Milestones

Remember to save changes!

Status

In projects, click the three dots in the top right corner, select Settings, then under Custom Fields, click on Status and add the following statuses (including the emojis):

• Backlog 📜
• In Progress 🚧
• Ready for Review 🔍
• Done ✔️

Also don't forget to remove any default statuses.

Example

You can view the project board of this repository to get an example of what the project board should look like and how the automation is handled.

A project board

(back to Getting Started)

(back to top)

The labels for issues

Featured labels

• Labels can either be assigned automatically by the automation or manually by the user. It is best to let the automation handle the assignment of labels marked as "automatically" and not add them manually to an issue.
• when a new issue is opened, it will be automatically assigned the "Backlog 📜" label. If an issue is already labeled as "In Progress 🚧", you can change the label back to "Backlog 📜" if needed.

Adding labels to the repository

You can add labels by going to the repository, clicking on the Issues tab, and then clicking on the Labels button, which is located next to the milestones option, and now you can start copying these labels by clicking on the New Labels button.

Organization default repository labels

If you plan to use these labels across all of your organization's future repositories, then you can go to your organization's settings, navigate to the repository section under "code, planning, and automation", and click on repository defaults. Then, you can click on the new label button and add the labels. These labels will featured in all of organization's future repositories, but will not be added to already existing repositories, so you will need to add them manually to those.

Label Name	Description	Manually or Automatically	Label / Status Field
Docs 📝	Changes to documentation only	Manually	Label
Feat 🆕	A new feature	Manually	Label
Style 🖌️	Changes to formatting (e.g. the code is missing semicolons)	Manually	Label
Test ☑️	Adding/correcting existing tests	Manually	Label
Refactor 🔁	A code change which isn't bug fix or adds a feature. It's restructure of the code without changing the functionality	Manually	Label
BugFix 🐛	A bug fix	Manually	Label
Chore 👷‍♂️	Maintenance or change to auxiliary tools	Manually	Label
Add ➕	Adding essentials to the repository (e.g. .gitignore or example files)	Manually	Label
Backend ⚙️	When a backend issue is opened, it is automatically given to the issue	Automatically	Label
Frontend 🖥️	When a fronted issue is opened, it is automatically given to the issue	Automatically	Label
Design 🎨	When a design issue is opened, it is automatically given to the issue	Automatically	Label
Unassigned ❕	Currently nobody has been assigned to it	Automatically	Label
Unlabeled ❗	No labels have been added	Automatically	Label
Backlog 📜	Tasks that have not yet been started or left unfinished	Both	Both
In Progress 🚧	Currently in the process of being worked on	Manually	Both
Ready for Review 🔍	A pull request has been created and it is ready for review	Manually	Both
Done ✔️	Task has been completed or closed	Manually	Both

• When copying and pasting labels, make sure to include any associated emojis.

(back to Getting Started)

(back to top)

Issues forms and pull request template

Make sure to add the issue form files to the .github/ISSUE_TEMPLATE folder in your repository, and the pull request template goes to the .github folder.

Pick them from here:

Issue forms	Pull request template
backend-card.yml	pull_request_template.md
design-card.yml
frontend-card.yml

When creating an issue, depending on which one you pick, the form will automatically add one of the three labels (Backend ⚙️, Design 🎨, or Frontend 🖥️). For example, if you select a card related to backend development, it will add the "Backend ⚙️" label.

1. Open a new issue inside the repository.
2. Choose one of the cards or templates (Backend, Frontend, or Design).
- For example if you choose the backend card, then the Backend ⚙️ label will be added.
- Backlog 📜 label is always added when opening an issue.
3. Pick one descriptive label from this list: Docs 📝, Feat 🆕, Style 🖌️, Test ☑️, Refactor 🔁, BugFix 🐛, Chore 👷‍♂️, Add ➕
4. you can add another label from this list: In Progress 🚧, Done ✔️
The label "In Progress 🚧" means that someone is currently working on the issue.
The label "Done ✔️" indicates that the issue has been completed or closed.

%%{init: {'themeVariables': { 'fontSize': '20px'}}}%%
 graph LR;
     classDef infoboxcolors fill:#fff2cc, color:#000000;
     classDef firstboxcolors fill:#dae8fc, color:#000000;
     classDef secondboxcolors fill:#e1d5e7, color:#000000;
     classDef thirdboxcolors fill:#d5e8d4, color:#000000;

 subgraph Main
 style Main color:#00000000, fill:#00000000, stroke:#f66, stroke-width:2px, stroke-dasharray:5 5
 
 subgraph .
 style . color:#00000000, fill:#00000000, stroke-width:3px, stroke:#f66
     subgraph 1.
     style 1. color:#272B30, stroke:#f66, fill:#f8cecc
 end

     X([Open an issue])-->A[Project];
     class X infoboxcolors;
     class A firstboxcolors;
     end
 
 subgraph ..
 style .. color:#00000000, fill:#00000000, stroke-width:3px, stroke:#f66
     subgraph 2.
     style 2. color:#272B30, stroke:#f66, fill:#f8cecc
 end

     A-.->XX([Choose</br> a template]);
     class XX infoboxcolors;

     XX-->B((Backend)) & C((Frontend)) & D((Design));
     class B,C,D secondboxcolors;
     end

 subgraph ...
 style ... color:#00000000, fill:#00000000, stroke-width:3px, stroke:#f66
     subgraph 3.
     style 3. color:#272B30, stroke:#f66, fill:#f8cecc
 end

     .... -.->XXX([A more descriptive</br>label</br>is added</br>manually]);
     class XXX infoboxcolors;
     XXX-->E(Docs);
     XXX-->F(Feat);
     XXX-->G(Style);
     XXX-->H(Test);
     XXX-->I(Refactor);
     XXX-->J(Bugfix);
     XXX-->K(Chore);
     XXX-->L(Add);
     XXX-->R(In Progress);
     XXX-->S(Done);
     class E,F,G,H,I,J,K,L,M,N,O,P,Q,R,S,T,U thirdboxcolors;
     end
 
 subgraph ....
 style .... color:#00000000, fill:#00000000, stroke-width:3px, stroke:#f66
     subgraph 3.
     style 3. color:#272B30, stroke:#f66, fill:#f8cecc
 end

     Frontend & Backend & Design & Backlog -.- XXXX([These labels</br>will be automatically</br>added accordingly]);
     class XXXX infoboxcolors;
     C-->Frontend(Frontend);
     B-->Backend(Backend);
     D-->Design(Design);
     C & B & D-->Backlog(Backlog);
     class E,F,G,H,I,J,K,L,M thirdboxcolors;
     end
 end

Schema for labeling.

(back to Getting Started)

(back to top)

Workflow file setup

Variable	Description	Example Organisation / User specific setting
username		User
gh_project_token		User
organization_name		Organisation
gh_app_key		Organisation
gh_app_id		Organisation
gh_app_installation_id		Organisation
project_number		Both
project_portfolio_number		Both

Authentication for user

Create a Personal Access Token (PAT)

1. Let's begin with creating a PAT by going to the personal settings. From there, go to the developer settings and then click on the personal access tokens on the left menu, which opens a menu of two items. Pick the tokens (classic) from the dropdown menu, and then press the button that says "Generate new token" to generate a new token (classic)

For additional details on creating a PAT, refer to the documents

2. Select the following scopes (permissions)

   • repo - all
   • admin:org - write:org
   • admin:org - read:org
   • project - read:project

3. Save the given token in to your repository secrets and name it as SECRET_TOKEN so that the workflow file knows what to look for.

Authentication for organisation (via app)

• Start by creating a Github App under your organization. Follow the instructions in the documents.

App settings

• For the newly created Github App, set the following requirements:

  • Repository permissions (8 in total)

    • Actions - Read and write
    • Checks - Read and write
    • Commit statuses - Read only
    • Contents - Read and write
    • Environments - Read only
    • Issues - Read only
    • Metadata - Read only
    • Pull requests - Read only

  • Organization permissions (2 in total)

    • Members - Read only
    • Projects - Read and write

  • Check the documents to see how to edit the permissions of the Github App.

• Go to Optional features (in the app) and opt-out from the following setting:

  • User-to-server token expiration

• Generate a private key, treat the file like the password and keep it safe.

Installing

• Install the Github App in the organization
  • To install the GitHub App in your organization, go to your organization's settings, navigate to Developer settings, select GitHub Apps, click edit next to the app, select Install App, and then click Install.

Secrets

• To make the private key, the GitHub App's installation id, and the App's id accessible to all the repositories in the organization for the workflow file, store the private key as PRIVATE_KEY, the GitHub App's installation id as APP_INSTALLATION_ID, and the app's id as APP_ID as secrets in the organization's settings and actions.
  • The private key can be generated within the app itself, by navigating to the app's settings and selecting the Generate Private Key option.
  • App id can be found from configuration general page as App ID
  • To find the app installation id, navigate to your organization's settings, select Github Apps, and then select Configure next to the app. The app installation id can be found now in the address bar, like this: https://github.com/organizations/<organization>/settings/installations/<id>

Finding number of project board

• Go to the project board and then look in the address bar, it should appear like this: https://github.com/users/<username>/projects/<number> and for the organization it should appear like this: https://github.com/orgs/<organizationname>/projects/<number>
• Project id is necessary for the automation.

(back to Getting Started)

(back to top)

Editing the parameters in WFprojects.yml file

Only the parameters should be changed that are inside the angle brackets (<>). For example, username: octocat or project_number: 1 (remember to remove anglebrackets).

These parameters can be found org/user related settings in the WFprojects.yml file and are almost at the beginning of the file.

• User related settings (only edit these).

username: <username>
gh_project_token: ${{ secrets.SECRET_TOKEN }}
project_number: <projectid>

• Organization related settings.

organization_name: <organization>
gh_app_key: ${{ secrets.APP_SECRET_KEY }}
gh_app_id: ${{ secrets.APP_ID }}
gh_app_installation_id: ${{ secrets.APP_INSTALLATION_ID }}
project_number: <projectid>

Base tree for repository

In the end the base of the repository should look like this:

.
├── .github
│   ├── CODE_OF_CONDUCT.md
│   ├── CONTRIBUTING.md
│   ├── ISSUE_TEMPLATE
│   │   ├── backend-card.yml
│   │   ├── design-card.yml
│   │   ├── frontend-card.yml
│   │   └── config.yml
│   ├── workflows
│   │   └── WFprojects.yaml
│   └── pull_request_template.md
├── .gitignore
└── README.md

3 directories, 10 files

Excluding .gitignore file. There's topic about .gitignore later in this guide, which I recommend to check out.

(back to Getting Started)

(back to top)

---

Git strategy and usage

1. Bedrock Rules
2. Branch Strategy
3. Formatting Rules

(back to top)

Bedrock Rules

1. Pull frequently
2. Push infrequently
3. Commit frequently
   • Merge "forward frequently"
     • Note: Make sure that your branch doesn’t diverge too much from the original branch
4. Create pull requests infrequently
   • Productivity is not measured by PRs!
   • If your code affects others, then make a pull request. So that others who are working on the same project gets the latest feature.
     • In other hand if it doesn't affect others, then do not make unecessary pull requests for minor things.
     • Key sentence: Quality Over Quantity
5. Always ask if unsure

(back to Git Strategy and Usage)

(back to top)

Branching Strategy

The strategy is based on the Git Flow strategy, where each feature (or issue) is represented by a separate branch. Every new branch created is a feature that is being added or worked for the project. The main branch is the production branch, which is the version that is sent to the customer and is always the working one. The dev branch is where all the feature branches are pull requested to aka merged.

The actual Git Flow strategy also includes release and hotfix branches, which are not included in this strategy. Additonally, version numbering is missing, which might be added later.

Strategy guideline

Branches

Name	Description
main	A production branch
dev	A development branch
feature branches	Each issue is one feature branch

Merging

• The merge order is from feature branch to development branch, and then from development branch to main branch. This order ensures that changes are tested in the development branch before they are merged in to the main branch.
  • Simply said: the merge order is: feature > dev > main.
• Always open pull request from feature branch to dev branch (never to main!).
• Each issue equals to one feature which is represented by one feature branch.
• Always open pull request, instead of merging straight to the branch! This ensures that changes are peer reviewed and any potential problems can be identified before the changes are applied to the branch. Even if the problems were accepted via a pull request, it is still easy to revert back if needed.

Naming conventions for the branches

• In the two next sections, you can find instructions on how to properly format the branches in order to ensure the team is following a consistent workflow and that the branches are properly documented.

(back to Git Strategy and Usage)

(back to top)

Formatting Rules for a Branch (Type/Reference ID/Description)

1. Type

• Docs - Changes to documentation only
• Feat - A new feature
• Style - Changes to formatting (e.g. the code is missing semicolons)
• Test - Adding/correcting existing tests
• Refactor - A code change which isn't bug fix or adds a feature. It's restructure of the code without changing the functionality
• BugFix - A bug fix
• Chore - Maintenance or change to auxiliary tools
• Add - Adding essentials to the repository (e.g. .gitignore or example files)

2. Reference ID

Reference the issue from GitHub, Trello or some other agile source. For now use one of the two formats shown below.

• Referencing an issue from Github: issue(insert number here) or just hashtag + number (e.g. /issue12/ or /#12/)
• Referencing from Trello: trello(insert number here) (e.g /trello8/)

3. Description

Short Description that is 1-3 words long and separated by hyphens aka " - ". Briefly describes what is done or worked on.

Examples

Good Examples 👍	Bad Examples 👎
✔️ add/issue12/gitignore	❌ something/bug12/do_S*ame<
✔️ style/8/added-missing-semicolons	❌ hi/TeSt/ääliö
✔️ fix/trello1/serializer	❌ fiX/TreLlo1/SeRiAlIzeR

Note: Only use allowed special characters which are " / " and " - " when formatting the branch!

(back to Git Strategy and Usage)

(back to top)

---

Useful Git Commands

1. How to Create a Branch (via Git)
2. Deleting Branches Locally & Remotely
3. .gitignore
4. Adding .gitignore into already existing repository
5. Merging Branches

(back to top)

How to Create a Branch (via Git)

• git branch -a
  • see all available branches in this repository/project.
• git checkout -b <insertBranchNameHere>
  • create a new branch ("-b" creates and switches to it).
• git switch <insertBranchNameHere>
  • switch between branches.

adding it to working branch (not master)

• git add –i
  • Opens interactive menu and it is used to update index using the current content.
    • There are alternative ways (e.g. git add .) to add changes to staging area but, they are not preferred unless you are experienced git user. Interactive menu gives easy access to control what changes we want to add to staging phase and push forward.
• git status
  • Shows which files are tracked by Git and which changes have been staged (which have been not).
• git restore --staged <insertFileNameToUnstage>
  • Note: Incase you added something you don't want to push.
• git commit -m "<insertCommentsHere>"
  • Record changes to the repository
• git push --set-upstream origin <insertBranchNameHere>
  • (You can do alias for this)

(back to Useful Git Commands)

(back to top)

Merging Branches

Very important: when merging, make sure that you are on the branch that you want to merge to. You will tell Git basically: "see those new stuff? Bring them over here."

1. git add -i
2. git commit -m "<insertCommentsHere>"
3. git checkout master
4. git merge <insertBranchNameHere> --no-ff
   • Additional command "--no-ff" tells Git that you want to retail all of the comments prior to the merge. Makes tracking easier in the future.

Always consult before merging directly as it can conflict with others. It is recommended to do pull request instead.

(back to Useful Git Commands)

(back to top)

Deleting Branches Locally / Remotely

Locally

• git branch -d <insertLocalBranchNameHere> - deletes the merged branch locally (it's not needed anymore!).
  • "-d" only if the branch has been pushed and merged.
  • "-D" force the local branch to be deleted, even if it hasn't been pushed or merged yet (important! Always communicate with your team before using force!).

Remotely

• Or use this git push origin --delete <insertRemoteBranchNameHere> to remove remote branch.

(back to Useful Git Commands)

(back to top)

.gitignore

Gitignore is essential part of the repository and workflow. It prevents unnecessary files (e.g. large binary files which makes pushing to github very slow) and secret files (e.g. file that includes password or other crucial information) being added to the repository.

• https://gitignore.io - on this page you will find ready-made .gitignore templates that you can use in your projects.

(back to Useful Git Commands)

(back to top)

Adding .gitignore into already existing repository

When attempting to ignore a file (or files) that's already tracked in the repository, then do this:

1. Commit all changes
2. Removes any changed files from the index (staging phase).
   • git rm -r --cached .
     • "rm" - remove command
     • "-r" - allow recursive removal
     • "-cached" - only remove files from the index. Your files will still be there.
     • "." indicates all files will be untracked. Specific file with "git rm -r foo.txt"
   • With this command we untrack all of the files that have already been added to the repository. Tl:dr stop tracking but not delete from the system.
3. Add .gitignore file
4. Re-add everything
   • git add .
5. Commit
   • git commit -m "<insertCommentsHere>"
6. Last step: git push

Becaution here as this will DELETE the file (or files) that is specified in the .gitignore from the github repository.

(back to Useful Git Commands)

(back to top)

---

Cheat Sheet

🔶 Creating a branch

Command	Description	Frequently used?
git pull	Before starting a pull command, it is important to make sure that your working copy is clean and free of any uncommitted local changes. To accomplish this, you can use git's Stash feature to save your local changes temporarily so that they are not overwritten when you pull. This will ensure that any changes you make to the repository are safe and secure.
git branch -a	See all available branches	👍
git checkout -b <insert example: chore/#12/gitignore>	Create a new branch	〰️
git switch <insertBranchNameHere>	Switch between branches	👍

🔷 Adding files to a branch (not master)

Command	Description	Frequently used?
git add -i	Interactive menu	👍
git status	Files tracked by Git	👍
git restore --staged <insertFileNameToUnstage>	Unstage unwanted file(s)	〰️
git commit -m "<insertCommentsHere>"	Record changes to the repository	👍
git push --set-upstream origin <insertBranchNameHere>	Push staged files in to a branch	👍

🟥 Deleting branches

Command	Description	Frequently used?
git branch -d <insertLocalBranchNameHere>	Delete local branch	〰️
git push origin --delete <insertRemoteBranchNameHere>	Delete remote branch	〰️

◻️ Merging branches

note: merging directly to master or main is not generally recommended, always do a pull request! ! !

Command	Description	Frequently used?
git add -i	Interactive menu	👍
git commit -m "<insertCommentsHere>"	Record changes to the repository	👍
git switch master	Switch to master	👍
git merge <insertBranchNameHere> --no-ff	Merges a branch into master	👎

Git Flow Strategy Cheat Sheet as in schema

(back to top)

---

Featured organizations, teams, and projects that utilize the Git Etiquette

Virittämö Helsinki	Aava

(back to top)

---

How to Contribute

1. Clone repository and create a new branch: git checkout https://github.com/LeDuble/Git-Etiquette.git -b <insertBranchNameHere>
2. Add changes to your branch
3. Create a Pull Request with descriptive text.
4. Leave a star 🤩

Feed back and suggestions are welcome!

(back to top)

---

Author

• LeDuble

(back to top)

---

License

You can read the full license here

(back to top)