Git Best Practices

There are several Git best practices that needs to be followed. Some of these practices are mandatory, because if not followed then it will make a negative impact on productivity. Here’s the summary:

1. Use .gitignore file, depending on your programming language (mandatory)
2. [Python projects] Use Pipenv (mandatory)
3. Add README.md (optional, strongly recommended)
4. Use Conventional Commits (mandatory)
5. Learn how to use Visual Studio Code’s Git features (optional, recommended)
6. Use Git Credential Storage

Below we’ll detail each one of them.

Use .gitignore file, depending on your programming language (mandatory)

If you’re new to .gitignore file, please read Gitignore Explained: What is Gitignore and How to Add it to Your Repo.

The common question after that is “What should I put in the .gitignore file?” The most practical way to get the list inside .gitignore is to use gitignore.io. Go there and select the following choices based on your programming language:

• TypeScript/JavaScript (NodeJS): Linux, MacOS, Windows, VisualStudioCode, Node
• React Web: Linux, MacOS, Windows, VisualStudioCode, react
• React Native: Linux, MacOS, Windows, VisualStudioCode, ReactNative, AndroidStudio, Xcode
• Python: Linux, MacOS, Windows, VisualStudioCode, Python, PyCharm
• PHP/Wordpress : Linux, macOS, Windows, VisualStudioCode, Composer, PhpStorm, Node
  (Node is required because PHP projects also use husky and lint-staged)

Question: “What happens if I don’t put a .gitignore file?”

Answer: You will save/upload all executable/cache files (e.g. __pycache__, node_modules) to the git repository, which will make your development time slow and store unnecessary files in git repository. Also, this will interfere with Continuous Integration pipeline. So, always make sure you put .gitignore file before your first commit.

Note: Commit yarn.lock for Continuous Integration i.e. do NOT ignore it

This policy depends on the purpose of the project. However for Lovia apps, we need this so our Continuous Integration builds can use yarn install –frozen-lockfile. This is important for reproducible builds. This is inline with Twelve Factor app #10 Dev/prod parity – Make the tools gap small: keep development and production as similar as possible.

[Python projects] Use pipenv (mandatory)

If you’re new to Pipenv, please read Pipenv: A Guide to the New Python Packaging Tool.

In practice, after you install Pipenv, you replace any usage of pip (or conda) with pipenv. This will create a Pipfile file inside your project, which you must commit to Git.

This Pipfile is required so that other developers, when cloning your project or as a team collaborating in the same project, can synchronize the Python packages needed by your project. If this file is missing, then other developers, and also the Continuous Integration pipeline, will need to install Python package dependencies manually and this costs additional time and effort.

How to Install and Use Pipenv on Ubuntu/Linux 18.04/20.04

Install python3-pip package:

sudo apt-get install python3-pip

Install pipenv using pip3:

sudo -H pip3 install pipenv

Now you can use pipenv inside your project folder, for example to install rasa:

pipenv install rasa

Add README.md (optional, strongly recommended)

This file is to be read by other developers (including yourself, to remind you because humans often forget). At a minimum, this file should contain the project title and a link to a relevant Handbook page (where more complete documentation can be found).

For example, in miluv-sales-chatbot project as a Rasa NLU project, README.md should contain a link to the Rasa NLU handbook. And the handbook page should have a good summary of the important things to know about Rasa NLU, links to Rasa documentation, blog posts (especially in About Lovia), videos (especially in Lovia Team YouTube channel), and other resources.

After that, README.md should describe how to perform typical needed tasks, such as: (Note: these steps should also be described in the Handbook in more detail, but README.md contains a simplified version of them for quick reference)

1. Setting up the project for the first time (e.g. installing dependencies using Pipenv or yarn)
2. Configuration (e.g. by editing .env file)
3. Running the project (e.g. by running yarn start or rasa shell)
4. How to train the model
5. How to run tests or get performance evaluation metrics
6. How to build the project executable/package
7. How to deploy the project to staging and production environments (without credentials)
8. Continuous Integration pipeline summary (without credentials)
9. Continuous Delivery pipeline summary (without credentials)

Use Conventional Commits (mandatory)

See Conventional Commits.

Learn how to use Visual Studio Code’s Git features (optional, recommended)

Visual Studio Code has really good Git integration and useful features, you can read more in Visual Studio Code User Guide: Git support.

At the very least you need to be able to sync/pull/commit/push inside Visual Studio Code. And to avoid merge conflicts, make sure to pull regularly several times per day and commit+push your work everyday.

Use Credential Storage

For Windows, you can use Git Credential Helper for Windows.

For Ubuntu, you can use store (most convenient, although not very secure), or cache but with a longer period. Example:

git config --global credential.helper store

Reference: https://stackoverflow.com/a/35942890/122441