README.md (f4d82e9) - processeur-decriture.git

README.md

# Introduction

Ce dépôt contient les sources du processeur d’écriture pour les documents de rédaction scientifique de David Valentine.
L’architecture de l’applicaion est basée sur celle de [https://git.loupbrun.ca/louis/lobrassard-net/](loupbrun), qui a l’immense gentillesse de partager son installation sous la licence [CC-BY](#).
Plusieurs modifications y sont toutefois appliquées pour répondre à des besoins particuliers.

# Générer les documents

Sélectionner le projet.

Exemple :

`$ make PROJET=proposition`

# Consulter les documents

`$ make serve`

# Approche par module Git

Tant les tâches de rédaction que les tâches de développement sont suivies avec Git.
Le dépôt applique un principe de séparation entre la production des contenus textuels et le développement technique du processeur.
Les tâches de développement sont validées (commited) directement dans ce dépôt, tandis que l’historique de la rédaction évolue dans un système de modules prévu à cet effet.

Voir le Pro Git book pour de l’information sur les modules :
https://git-scm.com/book/en/v2/Git-Tools-Submodules

## Ajouter un module

- `$ git submodule add <chemin-vers-le-module> src/<nom-du-module>`

## Mettre à jour un module (local) modifié à distance

Deux méthodes possibles :

1. dans le dépôt principal : `$ git submodule update --remote src/<nom-du-module>`
1. dans le module : fetch and merge manuel

**Remarque :** pour la première méthode, ne pas oublier d’indiquer, dans `.gitmodules`, la branche voulue pour l’update.

À ce point, les mises à jour se trouvent dans l’arbre de travail du module local.
Dès lors, il est possible d’exécuter le `makefile`, qui aura accès aux données du module et qui pourra donc produire un extrant complet.

Si l’on souhaite inclure les données du module dans l’index du dépôt principal (donc du processeur), il est nécessaire d’effectuer une validation, comme suit :

- `$ git add src/<nom-du-module>`
- `$ git commit -m "update <nom-du-module> submodule"`

Cependant, cela n’est pas un besoin particulier du projet actuel.
On pourrait tout de même vouloir valider un module au moment de générer l’extrant d’un projet, en particulier pour une version importante de celui-ci.

## Partager les modifications locales du module vers le module à distance

Info : https://stackoverflow.com/a/5814351/16839131

**Remarque :** cette solution ne fonctionne que si le dépôt distant est vide (*bare*).

Dans un premier temps :

```bash
$ cd your_submodule
$ git checkout main
<hack,edit>
$ git commit ...
```

Pour merger avec les validations distantes (si nécessaire) :
après avoir checked out sur une branche du module (déjà fait selon l’étape précédente), il faut `$ cd ../../ && git submodule update --remote --rebase` (ou merge).

Enfin, on peut `git push` directement dans le module pour partager le merge.

Toujours ramener main distant avant de rebase ou merge, sinon problèmes...
Ou alors pas de rebase ou merge sur main, et transfert direct sur l’autre branche, puis rebase dans le dépôt distant...

Sinon, on peut push en même temps que le dépôt principal :

- d’abord : `$ git add your_submodule && git commit -m "Updated submodule`.
- puis : `$ git push --recurse-submodules=on-demand`

Pour aller plus loin : foreach, etc.

## Note importante

Le dépôt distant du module n’est pas *bare* (on veut pouvoir y travailler directement dans certaines circonstances).
Il s’y trouve donc une copie de travail, et le *push* sera refusé par le dépôt distant.

Solutions possibles :
https://www.slingacademy.com/article/solving-git-error-refusing-to-update-checked-out-branch/

La tactique du forçage (`--force`) ne fonctionne pas dans ce cas (raison inconnue).

L’échange d’information entre le module et le dépôt distant s’effectue donc par l’entremise d’une branche distincte de `main`, puis sur le dépôt il s’agit de rebaser sur `main`.

processeur-decriture.git

README et gitignore: maj