Botanique/CONTRIBUTING.md

# Comment contribuer ? <!-- omit in toc -->
Ce guide contient méthodes et conseils sur comment aider le projet.
Lisez attentivement si vous êtes un nouveau contributeur.

Ce guide n'est pas fixe et est mis à jour régulièrement. Si vous
trouvez un problème quelconque, n'hésitez pas à le signaler par le biais
d'un [ticket](https://git.kennel.ml/ConfrerieDuKassoulait/Botanique/issues) ou
à le corriger directement en soumettant
une [Pull Request](https://git.kennel.ml/ConfrerieDuKassoulait/Botanique/pulls).

## Sommaire <!-- omit in toc -->
- [Recevoir de l'aide](#recevoir-de-laide)
- [Langues](#langues)
	- [Ajouter une langue](#ajouter-une-langue)
	- [Mettre à jour une langue](#mettre-à-jour-une-langue)
- [Ajouter une commande](#ajouter-une-commande)
- [Modifier une commande](#modifier-une-commande)
- [Ajouter un évènement](#ajouter-un-évènement)
- [Soumettre ses modifications](#soumettre-ses-modifications)
- [Gestion du dépôt](#gestion-du-dépôt)

## Recevoir de l'aide
Si tu as besoin d'aide, tu peux poser ta question sur
le [Discord](https://discord.gg/Z5ePxH4).

## Langues
La langue par défaut est définie dans [`src/utils/client.ts`](src/utils/client.ts)
dans `client.config.default_lang`.

La langue par défaut fait office de solution de secours dans le cas où une traduction
est incomplète. On part donc du postulat que la langue par défaut contient toujours
toutes les chaînes de caractère dont le bot a besoin.


### Ajouter une langue
1. Créer un nouveau fichier dans [src/locales/](./src/locales/), le fichier
doit être nommé `langue.json` avec `langue` suivant
[cette liste](https://discord.com/developers/docs/reference#locales).
2. Le contenu du fichier peut être copié du fichier de la langue par défaut,
[cf. au dessus](#langues).
3. Ce sont les valeurs des clés (le texte à gauche des `:`) qui doivent
être traduits. Merci par avance !
  > Ne vous forcez pas à tout traduire. Même une contribution avec
  > une seule variable de modifiée compte !
4. Une fois terminée, [ouvrez une Pull Request](#soumettre-ses-modifications).

### Mettre à jour une langue
1. Rechercher la langue dans le dossier [src/locales/](./src/locales/).
2. Modifier/Ajouter des traductions comme
[expliquer au dessus](#ajouter-une-langue) (à partir du `3.`).
  > Pensez à vérifier si de nouvelles valeurs n'ont pas été ajouté dans
  le fichier langue par défaut, [cf. au dessus](#langues).

## Ajouter une commande
Pour ajouter une commande au bot, créez un fichier `nom-de-la-commande.ts` dans
un sous dossier de [`src/commands/`](./src/commands/). Vous pouvez créer une
nouvelle catégorie si votre commande n'entre dans aucune qui existe déjà.

Le contenu du fichier doit commencer comme suit :
```typescript
import { SlashCommandBuilder } from '@discordjs/builders';
import { Client, CommandInteraction } from 'discord.js';
import { getLocale, getLocalizations } from '../../utils/locales';
import { getFilename } from '../../utils/misc';

export default {
	data: (client: Client) => {
		const filename = getFilename(__filename);
		return new SlashCommandBuilder()
			.setName(
				filename.toLowerCase())
			.setDescription(client.locales.get(client.config.default_lang)
				?.get(`c_${filename}_desc`) ?? '')
			.setNameLocalizations(
				getLocalizations(client, `c_${filename}_name`, true))
			.setDescriptionLocalizations(
				getLocalizations(client, `c_${filename}_desc`)
			);
	},

	interaction: async (interaction: CommandInteraction, client: Client) => {
		const loc = getLocale(client, interaction.locale);

		/* Votre code ici */
	},
};
```
Ce template vous permet de commencé rapidement votre commande car il contient
déjà tout ce qu'il faut pour le support des langues. Pensez bien à ne pas écrire
directement vos chaînes de caractères ici mais bien dans
les [fichiers de langues](./src/locales/), c'est à ça que la variable
`loc` sert.

Vous devez aussi ajouter **obligatoirement** :
- `"c_COMMANDE_name": "NOM"` au fichier de langue, avec `COMMANDE` le nom de
la commande et `NOM` le nom de votre commande.
- `"c_COMMANDE_desc": "DESCRIPTION"` au fichier de langue, avec `COMMANDE`
le nom de la commande et `DESCRIPTION` la description de votre commande.

## Modifier une commande
Quand vous modifiez une commande, pensez à mettre-à-jour les langues. Si vous
ne savez pas traduire dans une langue, ne vous forcez pas, supprimer simplement
la traduction.

## Ajouter un évènement
Pour ajouter le support d'un évènement au bot, créez un fichier `nom-evenement.ts` dans
un sous dossier de [`src/events/`](./src/events/). Vous pouvez créer une
nouvelle catégorie si votre commande n'entre dans aucune qui existe déjà.

Vous pouvez préciser que l'évènement ne sera déclenché qu'une seule fois avec
```typescript
export const once = true;
```

De préférence, merci de mettre un lien en commentaire vers la documentation
de discord.js de l'évènement ([exemple ici pour l'évènement `ready`](./src/events/client/ready.ts#L3))

## Soumettre ses modifications
1. Lorsque vous vous sentez confiant dans vos modifications, ouvrez
une [Pull Request](https://git.kennel.ml/ConfrerieDuKassoulait/Botanique/pulls)
afin que votre code puisse être revu et fusionné. Vous pouvez suivre cette
[condition de nommage](https://gist.github.com/joshbuchea/6f47e86d2510bce28f8e7f42ae84c716#example)
ça aide à s'y retrouver plus rapidement.

1. Pensez à bien commenter votre code pour que n'importe qui comprennent vos
modifications. Vérifier bien dans tout les fichiers si ce que vous avez
modifié n'est pas référencer ailleurs (exemple : si vous modifier une variable
d'environnement, il faut penser à mettre à jour le
[`README`](./README.md#variables-denvironnements)).

3. N'oubliez pas d'utiliser [les fichiers de langues](./src/locales/) pour vos
chaînes de caractère, [cf. cette partie](#langues) pour plus de précisions.

4. Veuillez tester vos modifications avant de les soumettre. **Attention**, ce
n'est pas parce que vos modifications fonctionnent avec `npm run debug` qu'elles
fonctionneront avec `npm run main`, ainsi que dans l'image Docker.

> **Explication**
>
> `npm run debug` execute le code depuis le dossier [`src`](src/)
> tandis que `npm run main` et l'image Docker le fait depuis le dossier `dist`.
>
> Docker est cependant différent car dans l'image, le dossier [`src`](src/) est
> supprimé.

## Gestion du dépôt
- On ne push jamais directement sur la branche `main`.
- Quand on merge des modifications vers `main`, on fait un *squash*,
l'historique des modifications reste disponible dans
[le graph](https://git.kennel.ml/ConfrerieDuKassoulait/Botanique/graph).