la-chariotte/README.md

# La Chariotte

<img src="la_chariotte/static/img/logos/logo_la_chariotte.png" title="Logo de la Chariotte" height="150"/>

La Chariotte est une application de gestion de commandes groupées.

Elle est publiée sous licence libre Affero GPL, développée et maintenue par [Hashbang](https://hashbang.fr/).

## Contribuer

Si vous souhaitez contribuer au projet de la Chariotte, merci beaucoup !

La permière étape est de cloner le projet et d'obtenir le statut de développeur. Une fois que c'est fait, vous pouvez :

- choisir une tâche dans le board que vous voulez réaliser, et vous l'assigner - si vous ne savez pas quelle tâche faire, n'hésitez pas à écrire à laetitia@chariotte.fr
- créer une nouvelle branche **à partir de develop** dont le nom dira ce que vous voulez faire
- réaliser la tâche, sans oublier d'écrire et de lancer les tests (voir plus bas)
- créer une Merge Request, contenant le plus de détails possible sur ce que vous avez fait

Ensuite, un mainteneur de la Chariotte pourra relire votre code et proposer des améliorations/poser des questions si nécessaire. Seuls les mainteneurs peuvent merger dans develop et main.

Encore merci, et bon code !

## Versions - semantic versionning

Les fonctionnalités développées dans les différentes versions sont listées dans le fichier [CHANGELOG.md](https://gitlab.com/hashbangfr/la_chariotte/-/blob/main/CHANGELOG.md). 

Étant donné un numéro de version MAJEUR.MINEUR.CORRECTIF, il faut incrémenter :

le numéro de version MAJEUR quand il y a des changements non rétrocompatibles,
le numéro de version MINEUR quand il y a des ajouts de fonctionnalités rétrocompatibles,
le numéro de version de CORRECTIF quand il y a des corrections d’anomalies rétrocompatibles.

La version est à mettre à jour dans `la_chariotte.__init__.py` lors des releases.

## Développement

Cloner le projet :
```bash
git clone git@gitlab.com:hashbangfr/la_chariotte.git
```

### Environnement virtuel.

Pour éviter que les bibliothèques nécessaires au projet ne rentrent en conflit avec celles de votre système, il peut être utile d'installer un environnement virtuel :

```bash
python3 -m venv .venv
```

Une fois l'environnement virtuel installé, vous pouvez l'activer :

```bash
source .venv/bin/activate
```

### Dépendances

La Chariotte utilise Weasyprint pour la génération de PDFs, qui nécessite certains paquets sur votre machine. Vous pouvez suivre [les instructions de cette page](https://doc.courtbouillon.org/weasyprint/stable/first_steps.html#installation) pour les installer.

Ensuite, vous pouvez récupérer les dépendances python :
```bash
pip install -r requirements.txt
pip install -r dev-requirements.txt
```

### Base de données

La Chariotte nécessite une base de données, et est actuellement compatible avec PostgreSQL ([instructions d'installation ici](https://www.digitalocean.com/community/tutorials/how-to-install-postgresql-on-ubuntu-20-04-quickstart)).

Pour le développement, nous vous conseillons de créer une base de données nommée ```chariotte``` accessible par l'utilisateur et le mot de passe du même nom.

Dans une invite postgresql, entrez ceci :

```SQL
CREATE ROLE chariotte WITH
	LOGIN
	NOSUPERUSER
	CREATEDB
	NOCREATEROLE
	INHERIT
	NOREPLICATION
	CONNECTION LIMIT -1
	PASSWORD 'xxxxxx';
```
```SQL
CREATE DATABASE chariotte
    WITH
    OWNER = chariotte
    ENCODING = 'UTF8'
    CONNECTION LIMIT = -1
    IS_TEMPLATE = False;
```

### Fichier de configuration

Créez un fichier de configuration dans lequel vous pourrez spécifier la configuration qui est utile pour vous. Nous allons le nommer ici ```local_settings.py```.

```python
from la_chariotte.settings import *

DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.postgresql",
        "NAME": "chariotte",
        "USER": "chariotte",
        "PASSWORD": "chariotte",
        "HOST": "localhost",
    }
}
```

### Lancement du serveur

Tout devrait être maintenant prêt pour pouvoir lancer le serveur :

```shell
python manage.py migrate --settings=local_settings
python manage.py runserver --settings=local_settings
```

Pour créer un superutilisateur, qui aura accès à l'interface admin (/admin) :
```shell
python manage.py createsuperuser
```

### Travailler sur le frontend

Nous utilisons bulma comme framework CSS. Vous pouvez l'installer en utilisant la commande suivante :

```bash
npm install bulma
```

Vérifiez que vous utilisez la bonne version de sass :

```bash
sass --version
# used for developement: 1.59.3 compiled with dart2js 2.19.4
```

Recompiler dès que des changements sont detectés dans les fichiers scss.

```bash
sass --watch --no-source-map ./la_chariotte/static/sass/style.sass:./la_chariotte/static/css/app.css
```

Ou bien préférez compiler vers CSS au coup à coup :
```bash
sass --no-source-map ./la_chariotte/static/sass/style.sass:./la_chariotte/static/css/app.css
```

### Lancer les tests

Lancer les tests avec pytest :
```bash
pytest
```

Si il y a des erreurs [isort](https://pycqa.github.io/isort/), on peut lancer isort pour trier les fichiers :

```bash
isort .
```

Si il y a des erreurs [black](https://black.readthedocs.io/en/stable/), on peut lancer black pour linter le code :

```bash
black .
```

### Tests de l'envoi de mails

Pour tester l'apparence des mails, on peut utiliser [Sendria](https://github.com/msztolcman/sendria) : 
```bash
pip install sendria
sendria --db mails.sqlite
$NAVIGATOR http://127.0.0.1:1080
```

## Architecture de l'application

Les différentes applications Django créées sont :

- ``order``, pour gérer tout ce qui tourne autour des commandes
- ``accounts``, pour gérer la création de comptes. Pour la connexion, la déconnexion et le changement de mot de passe, on utilise l'application auth intégrée à Django.
- ``mail``, pour l'envoi des mails.

A l'état actuel, le diagramme de classes est le suivant :

```mermaid
classDiagram
    GroupedOrder "item_set" <-- Item
    GroupedOrder "order_set" <-- Order
    Order "ordered_items" <-- OrderedItem 
    Item "orders" <-- OrderedItem 
    OrderAuthor "author" <-- Order
    CustomUser "grouped_orders" <-- GroupedOrder

    class GroupedOrder{
      name
      deadline : DateTime
      delivery_date : Date
      place
      description
      orga : CustomUser
      total_price
    }
    class Item{
      name
      grouped_order : GroupedOrder
      ordered_nb
      total_price
      max_limit
    }
    class Order{
        grouped_order : GroupedOrder
        author : OrderAuthor
        price
        created_date
        note
    }
    class OrderedItem{
        order : Order
        nb 
        item : Item
    }
    class OrderAuthor {
        first_name
        last_name
        phone
        email
    }
    class CustomUser{
        first_name
        last_name
        email
    }
```

## Conventions de nommage

### Nommage des branches

Chaque branche doit être nommée sous la forme `category[/ticket-ref]/description`.
*category* détermine le type de modification que vous comptez effectuer au sein de la branche :

 - `feature` pour ajouter une fonctionnalité au projet
 - `fix` pour corriger un bug
 - `test` pour effectuer des changements n'étant associé à aucun besoin déjà spécifié
 - `doc` pour effectuer des changements relatifs à la documentation (readme notamment)
 - `refactor` pour effectuer un changement au sein du code sans conséquence sur l'application

Vous pouvez ajouter une catégorie si le besoin s'en fait sentir, tout en s'assurant que le sens soit bien compréhensible de l'extérieur.

Entre la catégorie et la description peut s'insérer la référence du ticket Gitlab relatif à la branche.

La description de la branche, en anglais et en kebab-case, doit décrire de manière très succinte l'objectif de la branche : dans quel but elle a été créée sans entrer dans le détail.

 Bons exemples :

 - `feature/72/improve-pdf-generation`
 - `fix/117/deadline-increments-on-duplicated-commands`
 - `doc/explain-conventions`
 - `refactor/99/is_ongoing-to-is_open`

 Mauvais exemples :

 - `fix-some-stuff`
 - `readme`
 - `feature/add-a-cool-ui-element-when-the-cursor-passes-over-the-calendar-where-the-user-can-also-choose-the-associated-hour`
 - `fix/edit-order/views/order.py-to-replace-is_ongoing-by-is_open`

### Noms des commits

Les noms de commits doivent être constitués de deux parties : un sujet et un corps (optionnel).
Le sujet fait office de titre du commit ; il se suffit souvent à lui-même et doit expliquer brièvement le but du commit.
Si besoin, le message de commit peut être enrichi d'un corps qui permet de détailler plus en détails ce qui a été modifié et pourquoi (mais pas comment !).

Les noms des commits doivent respecter ces 7 règles d'or pour garantir une homogénéité dans le projet:

- Sépare le sujet du corps avec une ligne vide
- Limite la ligne de sujet à 50 caractères
- Met une majuscule à la ligne de de sujet
- Ne finis pas la ligne de sujet avec un point
- Utilise le mode impératif dans la ligne de sujet (IMPORTANT)
- Limite la taille de ligne (*wrap*) du corps à 72 caractères
- Utilise le corps pour expliquer le quoi et le pourquoi (et pas le comment)

Les détails de cette méthode sont détaillés dans ce tuto : https://cbea.ms/git-commit/

Bons exemples :

- `Refactor system X for readability`
- `Remove deprecated method`
- `Release version 1.4.2`

 Mauvais exemples :

- `Changing behaviour of X`
- `add submit button.`
- `Edit order.py line 72 to improve efficiency by adding recursive algorithm`