This document will describe main guidelines for developers who want to contribute to this repo. It rely on other documentation in this repo for which link will be provided when needed.
The aim of this document is to describe how to help development of this project, how to properly contribute and provide a link the style code used in this repo.
Most of this guidelines are not mandatory, its mainly to make code and documentation more homogenous and help people to understand what is done in the code.
The repo use git flow branching model, for more information see:
To help you following this branching model, you can use
git flow command. To
install this command, see:
- git flow to install package
- git flow cheatsheet
Branches should start with prefix
Except for the main developers
release- branches are
protected. You will not be able to push directly on these branches.
For now, main developpers are:
Let us do a little tutorial to apply this workflow.
This tutorial will follow the following workflow steps:
- Fork this repo (Optional),
- Setup your working environment,
- Create your working branch,
- Work on this branch,
- Ensure your modification are documented and pass the tests,
- Once finished and tested, your can merge this branch to your branch,
- Prepare your merge request,
- Propose a merge request on the main repo.
1. Fork this repo (Optional)
This step is optional, as you can work directly on the main repo by creating
branch corresponding on what you are working on like
But it is the prefered method if you want to keep your configuration and be free
to name the branch whatever you want.
2. Setup your working environment
Depending of the type of repos, you might need to install different working environment. This setup will mainly depend on the base langage of repository, i.e. python based, ruby based, etc.
Do not hesitate to take a look to the script
I use with by
direnv to automate the setup of my working environments. The
location of the folder
.direnv depends on the repos type:
- Usually at the root of "standard" git repo.
- Usually in
.config/<repo_name>for vcsh repo.
Hint: Usage of
direnv is strongly recommended
direnv is not a required dependency but it is strongly
recommended to use it.
As many tools used by repos required environment variables, we strongly recommend using direnv to automate loading of these environment variables.
direnv is an extension for your shell. It augments existing
shells with a new feature that can load and unload environment variables
depending on the current directory.
In other terms, if a script
.envrc is present in a folder and allowed for
direnv, it will automatically be executed when entering the folder. When
leaving the folder any exported variables will be automatically unloaded.
This will allow you to not really care about the setup of working
environment as scripts run by
direnv will setup it for you.
If you want to use it, please refer to this short tutorial Usage of Direnv.
Python based repository
First, install the following external software which are required:
- bash >= 5.0
- python3 >= 3.8
- pip3 (using python >= 3.8)
- python3-venv (using python >= 3.8, or directly
python3.8-venvfor debian based distros)
Then, you will need to clone the repo:
# Clone with HTTPS git clone https://git.platform.tld/namespace/repo.git # Clone with SSH git clone email@example.com:namespace/repo.git
Finally, you will need to install python required dependencies to be able to use scripts in the repo:
# Assuming you are in the root of the repo or in ~/.config/<repo_name> # Create python virtual environment python3 -m venv .virtualenv # Activate the virtual environment source .virtualenv/bin/activate # Install python production required dependencies in the virtualenvironment pip3 install -r requirements.txt # Install python development required dependencies in the virtualenvironment pip3 install -r requirements.dev.txt
3. Create your working branch
In this exemple we will add a new documentation page, it is kind of a new
feature, so the new branch will be name
# Create the branch and directly go to it git checkout -b feature-doc-content-title
NOTE: If it is a bufix, the branch name may be like
bugfix-name-of-the-bug, etc. This naming convention is only if you wish to
work directly on the main repo, you are free to name the branch whatever you
like on your own fork.
4. Work on this branch
Then, do the work you need to do on your branch.
If you want to write the documentation page and are new using mkdocs, a tutorials is provided to help you adding content to the documentation.
See Update documentation.
If you want to setup/modify the CI to automatically push the website, a tutorial is provided to help you learn how to do it.
See Update CI.
5. Ensure your modification are documented and pass the tests
To ensure your modification are valid, i.e. pass the test. This will depend on the language base of the repo.
Python based repo
For python based repo simply use the following command:
# Assuming you are in the root of the repo or in .config/<repo_name> # and you setup python dev requirements tox
This will automatically run the testing tools (also used in the CI) and will ensure the build of the documentation:
- tox: Setup python testing suite
- shellcheck: Shell script analysis tools
For more information, you can check following files:
This previously described files are usually:
- In the root of the repo for "standard" git repo
6. Merge branch on your fork
This step is optional and only if you make a fork of the repo, otherwise, go directly to the next section.
Now you have finish your work, you can merge this feature into your
master branch (you are free of your branch management in your own fork).
# Go to your develop branch git checkout develop # Merge feature into develop git merge feature-doc-content-title
If you did not make a fork of the repo, when merging your branch to
develop, you will have no issues. But when pushing your modification,
these modification will be rejected as branch
protected on the main repo.
7. Prepare your merge request
Before proposing your merge request, ensure that :
- Your your configuration files are not versionned
8. Propose a merge request on the main repo
Finally, you can propose a merge request.
If you make a fork of the main repo
To do so, if your fork is not on Framagit, you may need to push it on this platform.
To do so, create an account on Framagit or ask your colleague how to do so as Framagit may not allow open registration.
Then, create an empty repo on Framagit and create the remote on your local folder and push your repo:
git remote add upstream-fork https://framagit.org//<USER>/<REPO_NAME> # To be sure, push all your branch, or if you know, push only needed branches git push upstream-fork --all
Then propose your merge request on the branch
master of the main repo. DO
NOT FORGET TO BE EXPLICIT ON YOU MERGE REQUEST
If you work directly on a branch on the main repo
You can direclty propose your merge request on the branch
master of the main
repo. DO NOT FORGET TO BE EXPLICIT ON YOU MERGE REQUEST