Developers Guidelines

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.

Workflow

The repo use git flow branching model, for more information see:

• A successful git branching model.

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 feature-, bugfix-, release- and hotfix-.

Except for the main developers master, develop and release- branches are protected. You will not be able to push directly on these branches.

For now, main developpers are:

•  rdeville

Tutorials

Let us do a little tutorial to apply this workflow.

This tutorial will follow the following workflow steps:

1. Fork this repo (Optional),
2. Setup your working environment,
3. Create your working branch,
4. Work on this branch,
5. Ensure your modification are documented and pass the tests,
6. Once finished and tested, your can merge this branch to your branch,
7. Prepare your merge request,
8. 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 feature-* or bugfix-*. 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 .direnv/bin/activate_direnv which 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.

# Clone with HTTPS
git clone https://git.platform.tld/namespace/repo.git
# Clone with SSH
git clone git@git.platform.tld:namespace/repo.git

# 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 feature-doc-content-title.

# 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.

# Assuming you are in the root of the repo or in .config/<repo_name>
# and you setup python dev requirements
tox

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 develop or 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

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