An example of Git repository for a Python project

This repository is a toy repository to showcase what needs to be in your repository to present it in a clear manner, make it usable in a standard way, and use a classic structure. Your repository should always contain a README file, preferably using Mardown (.md). The objective of this README is to provide an overview of the repository with a description of the project itself, the important concepts to understand, how to install and use your code (including code examples, CLI uses, input formatting, etc.), how to contribute (e.g. standards used for the code, how to organise your pull request, how to add tests), and useful links. Feel free to use this to easily communicate to your colleagues/students what you expect to find in a repository.

This repository is not meant to contain any useful code, it is merely an example project. It contains a few branches and tags to illustrate how to use them to keep things clean and ordered.

Useful standards

I like to follow these standards:

• Keep a Changelog: Keeping a changelog is crucial for people to understand what's new, changed, deleted with each version of your code. This standard provides a clean, easy-to-read way of keeping a changelog.
• Semantic Versioning: Obviously, keeping a changelog only makes sense if you version your code properly. Semantic versioning is easy to understand and widely used.
• Google's Standard for Python: The standard used by Google for its python code. In particular, section 3.8 showcases how to document your code properly.

What your repository should contain

Here is the minimum that your repository should contain:

• At the root: a README file (like this one), a LICENSE file, a .gitignore (this repository contains the standard .gitignore used for Python projects.)
• A folder with your code: the code should rarely be at the root of the repository. Instead, it should be put into its own folder. For Python packages, the name of the folder should be the name of package (e.g. as registered on pip). In this case, I create a toy python package called my_package. It contains two modules with examples of documentation.
• A tests folder containing the unit/integration tests of your code. The folder should follow the same structure as your main code folder (i.e. same subfolders) and all the test files should be named test_module_name.py to be discoverable by usual testing packages (e.g. unittest or pytest). This toy project contains unit tests for the toy package. You can use python -m unittest to run them.

How to keep your repository clean

Your project should always contain a main branch (usually named main or master). Nobody should work directly on that branch, EVER. Use git checkout branch_name to switch to another branch.

If you want to create a new branch and switch to it, you can for instance use the version number of the future release to create a new branch using the following:

git checkout -b 1.1

This way, you can keep a clean main branch (usually in a working state) while you develop new features/fixes. Once your happy with your new branch, create a pull request (through Github's interface) for someone to review your code (preferable if you work in a team), otherwise, switch to the branch you would like to merge into (e.g. main) and use the following command to merge:

git merge branch_name

The strategy used for merging is up to you. You can create a branch for each new feature. Multiple feature branches may be merged into a version branch to then be merged itself into the main branch.

Don't forget that the branches you create locally will not be pushed by default to the online repository. To add a branch to the origin, you can use the following command:

git push --set-upstream origin branch_name

To push all your local branches to the origin, you can use instead git push origin '*:*'. Also, using git pull will not pull the branches that are on origin but not in your local repository. To get all the branches from the origin, you can use the following command:

git fetch --all

Once a new version has been pushed to the main, you can keep the branch of that version for safekeeping but you can also add a tag to the HEAD of the main branch to make sure people can retrieve it quickly. Use the following commands:

git checkout main
git tag -am "A description of the tag, for instance with the release date" tag_name

tag_name should be the version number if possible to make it easier to navigate tags. If you do so, then to retrieve the repository state of that version, simply use the following command:

git checkout tags/version_number -b new_branch

This creates a new branch to prevent mistakes of checking out an older version while staying on the main branch for instance, and then committing to it.

Like for branches, local tags are not automatically pushed to origin, to do so, you can use the following command:

git push origin tag tag_name

To push all your tags to the origin at once, you can use git push origin --tags.

In order to keeps things clean, each commit should be accompanied with a meaningful comment about what has been changed/added in the commit, using the following command:

git commit -m "An example of message: added this feature, fixed this other feature."

Useful links

Here is a collection of useful links:

• Markdown Cheat Sheet
• Pydoc to generate the documentation from your docstrings.