README mise à jour des notes sur les modules (8488556) - processeur-decriture.git

README.md

@@ -1,33 +1,50 @@
 # Introduction
 
 Ce dépôt contient les sources du processeur d'écriture des documents de rédaction scientifique de David Valentine.
-L'architecture globale 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.
+L'architecture globale 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.
 
-# Approche par modules
+# Approche par module
 
 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
+Voir le Pro Git book pour de l'information sur les modules :
+https://git-scm.com/book/en/v2/Git-Tools-Submodules
 
-## Ajouter un sous-module
+## Ajouter un module
 
 - `$ git submodule add <chemin-vers-le-module> src/<nom-du-module>`
 
-## Mettre à jour un sous-module localement (modifié à distance)
+## 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 submodule update --remote src/<nom-du-module>` ou fetch and merge manuel dans le module
 - `$ git add src/<nom-du-module>`
 - `$ git commit -m "update <nom-du-module> submodule"`
 
-**Remarque :** ne pas oublier d'indiquer, dans `.gitmodules`, la branche voulue pour l'update.
+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
@@ -35,25 +52,27 @@ $ git checkout main
 $ git commit ...
 ```
 
-Pour merger avec les validations distantes :
-après avoir checked out sur une branche du module (déjà fait supposément selon l'étape précédente), il faut `$ cd ../../ && git submodule update --remote --rebase` (ou merge).
+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.
 
 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`
+- 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*.
-Il s'y trouve donc une copie de travail et le *push* sera refusé par le dépôt distant.
+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 ne fonctionne pas dans ce cas (raison incconnue).
-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.
\ No newline at end of file
+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`.
+


...	...	@@ -1,33 +1,50 @@
1	1	# Introduction
2	2
3	3	Ce dépôt contient les sources du processeur d'écriture des documents de rédaction scientifique de David Valentine.
4		-L'architecture globale 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.
	4	+L'architecture globale 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](#).
5	5	Plusieurs modifications y sont toutefois appliquées pour répondre à des besoins particuliers.
6	6
7		-# Approche par modules
	7	+# Approche par module
8	8
9	9	Tant les tâches de rédaction que les tâches de développement sont suivies avec Git.
10	10	Le dépôt applique un principe de séparation entre la production des contenus textuels et le développement technique du processeur.
11	11	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.
12	12
13		-Voir le Pro Git book pour de l'information sur les modules : https://git-scm.com/book/en/v2/Git-Tools-Submodules
	13	+Voir le Pro Git book pour de l'information sur les modules :
	14	+https://git-scm.com/book/en/v2/Git-Tools-Submodules
14	15
15		-## Ajouter un sous-module
	16	+## Ajouter un module
16	17
17	18	- `$ git submodule add <chemin-vers-le-module> src/<nom-du-module>`
18	19
19		-## Mettre à jour un sous-module localement (modifié à distance)
	20	+## Mettre à jour un module (local) modifié à distance
	21	+
	22	+Deux méthodes possibles :
	23	+
	24	+1. dans le dépôt principal : `$ git submodule update --remote src/<nom-du-module>`
	25	+1. dans le module : fetch and merge manuel
	26	+
	27	+Remarque : pour la première méthode, ne pas oublier d'indiquer, dans `.gitmodules`, la branche voulue pour l'update.
	28	+
	29	+À ce point, les mises à jour se trouvent dans l'arbre de travail du module local.
	30	+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.
	31	+
	32	+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 :
20	33
21		-- `$ git submodule update --remote src/<nom-du-module>` ou fetch and merge manuel dans le module
22	34	- `$ git add src/<nom-du-module>`
23	35	- `$ git commit -m "update <nom-du-module> submodule"`
24	36
25		-Remarque : ne pas oublier d'indiquer, dans `.gitmodules`, la branche voulue pour l'update.
	37	+Cependant, cela n'est pas un besoin particulier du projet actuel.
	38	+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.
26	39
27	40	## Partager les modifications locales du module vers le module à distance
28	41
29	42	Info : https://stackoverflow.com/a/5814351/16839131
30	43
	44	+Remarque : cette solution ne fonctionne que si le dépôt distant est vide (bare).
	45	+
	46	+Dans un premier temps :
	47	+
31	48	```bash
32	49	$ cd your_submodule
33	50	$ git checkout main
...	...	@@ -35,25 +52,27 @@ $ git checkout main
35	52	$ git commit ...
36	53	```
37	54
38		-Pour merger avec les validations distantes :
39		-après avoir checked out sur une branche du module (déjà fait supposément selon l'étape précédente), il faut `$ cd ../../ && git submodule update --remote --rebase` (ou merge).
	55	+Pour merger avec les validations distantes (si nécessaire) :
	56	+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).
40	57
41	58	Enfin, on peut `git push` directement dans le module pour partager le merge.
42	59
43	60	Sinon, on peut push en même temps que le dépôt principal :
44		-d'abord `$ git add your_submodule && git commit -m "Updated submodule`.
45	61
46		-Puis : `$ git push --recurse-submodules=on-demand`
	62	+- d'abord : `$ git add your_submodule && git commit -m "Updated submodule`.
	63	+- puis : `$ git push --recurse-submodules=on-demand`
47	64
48	65	Pour aller plus loin : foreach, etc.
49	66
50	67	## Note importante
51	68
52		-Le dépôt distant du module n'est pas bare.
53		-Il s'y trouve donc une copie de travail et le push sera refusé par le dépôt distant.
	69	+Le dépôt distant du module n'est pas bare (on veut pouvoir y travailler directement dans certaines circonstances).
	70	+Il s'y trouve donc une copie de travail, et le push sera refusé par le dépôt distant.
54	71
55	72	Solutions possibles :
56	73	https://www.slingacademy.com/article/solving-git-error-refusing-to-update-checked-out-branch/
57	74
58		-La tactique du forçage ne fonctionne pas dans ce cas (raison incconnue).
59		-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.
60	75	\ No newline at end of file
	76	+La tactique du forçage (`--force`) ne fonctionne pas dans ce cas (raison inconnue).
	77	+
	78	+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`.
	79	+
61	80