Contributing guide

Contributing guide

docs/contributing.md

+# Contributing to ATR-DAN
+
+We welcome every contribution possible to improve ATR-DAN. Whether it is Python code, translations, design suggestions, small fixes, etc.
+
+If you want to discuss some ideas, send us an email at `contact (at) teklia.com`!
+
+## Cloning the source code
+
+It is as simple as running the following command:
+
+```bash
+git clone git@gitlab.teklia.com:atr/dan.git
+```
+
+As ATR-DAN is open-source, you do not need any authentication to retrieve its source code. However, if you wish to work on ATR-DAN source code and submit patches, you will need to authenticate yourself. Steps to do so are detailed just below.
+
+## GitLab setup
+
+We assume you already have:
+
+- a working [git](https://git-scm.com/) client installation on your computer
+- an SSH key to authenticate yourself on a GitLab instance
+
+You can find more information [here](https://docs.gitlab.com/ee/user/ssh.html).
+
+### Sign up on Teklia's GitLab instance
+
+At Teklia, we use [GitLab](https://gitlab.teklia.com/) **a lot**. We use it to host all our source code, work as a team, build and ship our projects, etc.
+
+You can sign up on Teklia's GitLab instance [here](https://gitlab.teklia.com/users/sign_up).
+
+Please note that your account will need to be approved by an administrator which could take up to one business day.
+
+### Add your SSH key
+
+Once you are connected to [gitlab.teklia.com](https://gitlab.teklia.com/), you need to add your **SSH public key** to your user account on Teklia's GitLab instance. To do so, you can follow [the official GitLab instructions](https://docs.gitlab.com/ee/user/ssh.html#add-an-ssh-key-to-your-gitlab-account).
+
+!!! warning "Security warning"
+    **Do not** use HTTPS to clone a repository, it will require you to type your GitLab password when cloning/pushing.
+
+### Activate 2FA
+
+To gain and keep access on ATR-DAN's GitLab repository as a contributor, your GitLab account must be protected with Multiple Factor Authentication (generally using one time passwords generated from your phone).
+
+You will need to setup an app like [Google Authenticator](https://support.google.com/accounts/answer/1066447?hl=fr&co=GENIE.Platform%3DAndroid) or [Duo Mobile](https://duo.com/product/multi-factor-authentication-mfa/duo-mobile-app) on your phone, and [then follow these steps](https://docs.gitlab.com/ee/user/profile/account/two_factor_authentication.html#enabling-2fa).
+
+If you do not complete the 2FA initial activation within 48 hours of creating your account, it will be automatically disabled.
+
+## Submitting a patch to ATR-DAN's source code
+
+### Find issues
+
+We use GitLab to track issues (either bugs, or new features).
+
+You can look at ATR-DAN's issues from different views:
+
+- through the current [milestone](https://gitlab.teklia.com/atr/dan/-/milestones), the most important issues are listed there, as they are the most time-sensitive
+- through the [full issue list](https://gitlab.teklia.com/atr/dan/-/issues)
+
+!!! info
+    Please ask first if you can work on an issue, by simply commenting on it. Be aware that some issues may be way more complex than others.
+
+#### Priorities
+
+Issues should have a priority label:
+
+- **P1** are high priority, usually bugs badly affecting users experience,
+- **P2** are at the normal priority level
+- **P3** are low priority
+
+If nothing is set, assume **P2** by default.
+
+### Work on a branch
+
+To start working on a patch, you must first create a **git branch**, based on the current `main` branch:
+
+```bash
+# Start from main
+git checkout main
+
+# Update main to latest available revision
+git pull origin main
+
+# Create a new branch
+git checkout -b my-new-branch
+```
+
+Each new commit will then be stored on that new branch named `my-new-branch`.
+
+To name your branch, use a name:
+
+1. in English,
+1. in lowercase,
+1. without spaces, use dashes `-` to link words,
+1. explicit and related to your current work.
+
+Here are some examples of suitable branch names:
+
+- `remove-model-x` when the goal is to remove a Django model named `X`
+- `fix-invalid-chars-search` when the patch fixes a **bug** related to search
+- `bump-dependency-y`
+- `add-super-feature`
+- `feature-z`
+
+Please avoid:
+
+- naming your branch with the issue ID, we prefer explicit naming here,
+- using another language than English,
+- spaces, camelCase, underscores, etc.
+
+### Publish your work
+
+You are allowed to push directly on ATR-DAN's repository, except for the `main` branch. The goal is for your code to reach `main` once the following steps are completed:
+
+1. unit tests are all OK, meaning that all jobs in the CI stage named `test` ended in success
+1. formatting has been validated by a tool, meaning that all jobs in the CI stage named `checks` ended in success
+1. the code itself has been approved by a human reviewer
+
+To get approvals, you need to [create a Merge Request (also called MR)](https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html) on GitLab.
+
+When pushing [your code from your local branch](https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html#when-you-use-git-commands-locally), you will notice some output in the console with a link towards `gitlab.teklia.com`: it will allow you to create a Merge Request (or view the previously created one) in 2 clicks.
+
+Once your work is ready, configure your Merge Request as follows:
+
+- Assign yourself as the **Assignee**.
+- Assign [@babadie](https://gitlab.teklia.com/babadie) as the **Reviewer**, he will either review or re-assign to another reviewer when needed.
+- Set an explicit name, in English, properly formatted.
+- Add a reference to the issue you are working on in the description:
+    - `Closes #XYZ` if you fully solve the mentioned issue,
+    - `Ref #XYZ` if you only want to link your Merge Request to the issue.
+- Fill in the description with an explanation of the changes you made.
+- If the related issue has a milestone set, set the same milestone on this Merge Request.
+
+If you are not confident the work being published is yet ready for review, you can prefix your Merge Request name with `Draft:`; that will tell the reviewer to wait a bit before diving into your code. Do not forget to remove that prefix once your code is ready.
+
+The reviewer may leave some comments directly on the Merge Request, asking you for updates. Please resolve all of them (or discuss them if you disagree), publish some commits fixing the issues, and then [ask for a new review](https://docs.gitlab.com/ee/user/project/merge_requests/reviews/#request-a-new-review). Rinse and repeat until the reviewer approves and merges your code!
+
+### Update your branch
+
+As other developers are working on ATR-DAN, sometimes features/bugfixes/etc will land on `main` while your Merge Request touches the same parts. You may get conflicts here and will need to solve them using a **rebase**.
+
+!!! info
+    It is your responsibility, as a developer, to maintain your code in a **mergeable state**: no conflicts and up to date with the latest `main`.
+
+To update using **rebase**, while working on your branch:
+
+```bash
+# Retrieve the latest updates from main
+git fetch origin main
+
+# Now the remote reference to origin/main has been updated, you can rebase on top of it
+# Be aware that the local reference to main is not yet updated, it is only updated with git pull
+git rebase origin/main
+```
+
+The `git rebase` operation will ask you to solve manually conflicts (if any). Please [follow this guide](https://www.atlassian.com/git/tutorials/rewriting-history/git-rebase) or ask us for help if you are lost.
+
+### Landing your code
+
+If you have reached this step, congratulations and many thanks! Your code has been approved and should already be merged, as that is the responsibility of the reviewer.
+
+Your work will be shipped in the next ATR-DAN release along with latest features, bugfixes and other contributions.