From f0569694bf90e6d7c991cbd8b810222ad02f9264 Mon Sep 17 00:00:00 2001 From: viennet Date: Thu, 28 Jan 2021 09:47:27 +0100 Subject: [PATCH] infos for developpers --- docs/Contribuer.md | 17 +++++++ docs/Developpement.md | 82 --------------------------------- docs/FAQ.md | 4 +- docs/GuideDeveloppeurs.md | 89 +++++++++++++++++++++++++++++++++++- docs/PresentationGenerale.md | 2 +- 5 files changed, 108 insertions(+), 86 deletions(-) create mode 100644 docs/Contribuer.md delete mode 100644 docs/Developpement.md diff --git a/docs/Contribuer.md b/docs/Contribuer.md new file mode 100644 index 000000000..cb38e842b --- /dev/null +++ b/docs/Contribuer.md @@ -0,0 +1,17 @@ +# Contribuer à ScoDoc + +ScoDoc est un logiciel libre, et repose sur des volontaires comme vous. Chacun peut aider, en améliorant la documentation (page, vidéos), en s'abonnant à la liste Notes (voir [listes de diffusion](ListesDeDiffusion.md)) pour y aider les collègues, ou en développant ou testant le logiciel. + +Le canal de communication entre développeurs est la liste de diffusion mail [scodoc-devel](ListesDeDiffusion.md). Là, vous pourrez demander un compte sur le [git du projet](https://scodoc.org/git), consulter/ajouter des tickets, proposer votre code (*pull requests*). + +## Contribuer à la documentation + +La documentation est constituée de deux parties: + + - les vidéos postées sur [la chaîne YouTube](https://www.youtube.com/playlist?list=PLw49h6RbvswhasBk9bXj7PzOD8GDW3kG1). Proposez de nouvelles vidéos, c'est très facile à faire ! + + - Les pages Web comme celle que vous lisez actuellement. La documentation est générée via `MkDocs, un système très simple basé sur le format [Markdown](https://www.markdownguide.org/basic-syntax/). Toutes les sources sont sur le [dépôt git DocScoDoc](https://scodoc.org/git/viennet/DocScoDoc). + +## Contribuer au logiciel + +Le [dépot principal](https://scodoc.org/git/viennet/ScoDoc) comporte plusieurs branches. Voir le [guide pour les développeurs](GuideDeveloppeurs.md). \ No newline at end of file diff --git a/docs/Developpement.md b/docs/Developpement.md deleted file mode 100644 index 91d8ea564..000000000 --- a/docs/Developpement.md +++ /dev/null @@ -1,82 +0,0 @@ -## Développer sur ScoDoc 7 - -Quelques conseils, indications et mémos pour les développeurs sur ScoDoc version 7.x. - -## Style et formatage du code -L'ancienneté de la base de code a rendu le style peu cohérent. - -Le code doit être formatté avec [`black`](https://black.readthedocs.io/) avant tout commit (configurez votre éditeur pour appeler `black` à l'enregistrement). - -### Documentation -On adopte le style "Google": - -Exemple: - """Description résumée de la fonction - - blah blah sur la fonction - - Args: - table_handle: An open smalltable.Table instance. - keys: A sequence of strings representing the key of each table - row to fetch. String keys will be UTF-8 encoded. - require_all_keys: Optional; If require_all_keys is True only - rows with values set for all keys will be returned. - - Returns: - A dict mapping keys to the corresponding table row data - fetched. Each row is represented as a tuple of strings. For - example: - - {b'Serak': ('Rigel VII', 'Preparer'), - b'Zim': ('Irk', 'Invader'), - b'Lrrr': ('Omicron Persei 8', 'Emperor')} - """ - -## Git - -Le dépot est - -La branche `master` est celle en production. La branche `Scodoc8`est expérimentale (nouvel installeur, refactoring...). ScoDoc9 sera avec Python 3. - -### Hot fixes (internes) - -Pour les développeurs internes (écriture sur le dépot master): - - # Créer une branche - # si besoin (travail en cours), utiliser git stash avant - git checkout master - git branch hotfix - git checkout hotfix - ... dev, test ... - git add ... - git commit -m "fixed ..." - git checkout master - git merge hotfix - git branch -d hotfix - # publication - - # éventuellement: git stash pop - -### Mettre à jour votre branche - -Vous travaillez dans votre branche `ma_branche`. Pour lui appliquer les mises à jour de `master` (remote): - - git pull origin master - -### Commandes utiles, en vrac - - * `git log -L:fonction_python:fichier.py` - -### Refactoring - - pylint --disable=all -e E sco_parcours_dut.py | grep undefined-variable | awk '{print $4;}' | sort | uniq | tr -d \' - -Lint tous les fichiers modifiés: - git status | grep modified | grep .py | awk '{print $2}' | xargs pylint -E - -Restore les modes au besoin (SAMBA les changent parfois): - git diff -p -R --no-color | grep -E "^(diff|(old|new) mode)" --color=never | git apply - - -## Portail pour tests -TODO diff --git a/docs/FAQ.md b/docs/FAQ.md index 15290c73a..171aa4444 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -102,5 +102,5 @@ Pour vos tests en local, avec Chrome, modifier le paramétrage en réglant: `chr #### Comment supprimer un département ? La suppression d'un département efface toutes les données: étudiants, notes, etc. Se connecter sur ScoDoc (Web) comme administrateur, suivre le lien `Administration de scodoc` sur la page d'accueil, et supprimer le département. Cette opération retire le département de l'application Web, mais ne supprime pas la base de données du serveur. Pour cela, se connecter (en ssh) en tant que `root` sur le serveur, aller dans le répertoire `/opt/scodoc/Products/ScoDoc/config` et lancer le script `./delete_dept.sh`. - - +#### Comment contribuer au projet ? +[Voir la page](Contribuer.md). diff --git a/docs/GuideDeveloppeurs.md b/docs/GuideDeveloppeurs.md index c28ead9a4..f038cec6d 100644 --- a/docs/GuideDeveloppeurs.md +++ b/docs/GuideDeveloppeurs.md @@ -3,6 +3,8 @@ Informations pour les développeurs souhaitant étendre ou modifier ScoDoc. +## Informations générales + * S'abonner aux [listes de diffusion](ListesDeDiffusion.md) * [Générer de nouveaux formats de bulletins PDF](ApiGenerationBulletinsPdf.md) * [Créer de nouveaux types de "parcours"](ApiCreationParcours.md) @@ -12,5 +14,90 @@ Informations pour les développeurs souhaitant étendre ou modifier ScoDoc. * [Anciennes discussions sur la gestion des plannings](IdeesGestionPlannings.md) - +## Développer sur ScoDoc 7 et 8 + +Quelques conseils, indications et mémos pour les développeurs sur ScoDoc version 7.x et 8. + +### Style et formatage du code +L'ancienneté de la base de code a rendu le style peu cohérent. + +Le code doit être formatté avec [`black`](https://black.readthedocs.io/) avant tout commit (configurez votre éditeur pour appeler `black` à l'enregistrement). + +#### Documentation +On adoptera le style "Google": + +Exemple: + """Description résumée de la fonction + + blah blah sur la fonction + + Args: + table_handle: An open smalltable.Table instance. + keys: A sequence of strings representing the key of each table + row to fetch. String keys will be UTF-8 encoded. + require_all_keys: Optional; If require_all_keys is True only + rows with values set for all keys will be returned. + + Returns: + A dict mapping keys to the corresponding table row data + fetched. Each row is represented as a tuple of strings. For + example: + + {b'Serak': ('Rigel VII', 'Preparer'), + b'Zim': ('Irk', 'Invader'), + b'Lrrr': ('Omicron Persei 8', 'Emperor')} + """ + +### Git + +Le dépot est + +La branche `master` est celle en production. La branche `Scodoc8`est expérimentale (nouvel installeur, refactoring...). ScoDoc9 sera avec Python 3. + +Ci-dessous quelques pense-bête qui peuvent servir. +#### Hot fixes (internes) + +Pour les développeurs internes (écriture sur le dépot master), un exemple basique: + + # Créer une branche + # si besoin (travail en cours), utiliser git stash avant + git checkout master + git branch hotfix + git checkout hotfix + ... dev, test ... + git add ... + git commit -m "fixed ..." + git checkout master + git merge hotfix + git branch -d hotfix + # publication + + # éventuellement: git stash pop + +#### Mettre à jour votre branche + +Vous travaillez dans votre branche `ma_branche`. Pour lui appliquer les mises à jour de `master` (remote): + + git pull origin master + +#### Commandes utiles, en vrac + + * `git log -L:fonction_python:fichier.py` + +#### Refactoring + + pylint --disable=all -e E sco_parcours_dut.py | grep undefined-variable | awk '{print $4;}' | sort | uniq | tr -d \' + +Lint tous les fichiers modifiés: + + git status | grep modified | grep .py | awk '{print $2}' | xargs pylint -E + +Restore les modes au besoin (SAMBA les changent parfois): + + git diff -p -R --no-color | grep -E "^(diff|(old|new) mode)" --color=never | git apply + + +### Portail pour tests +TODO (voir `scotests/fakeportal/`). + diff --git a/docs/PresentationGenerale.md b/docs/PresentationGenerale.md index 1fdd0bff3..26885ef8e 100644 --- a/docs/PresentationGenerale.md +++ b/docs/PresentationGenerale.md @@ -47,7 +47,7 @@ ScoDoc permet de définir des partitions et groupes en nombre quelconque, et d'y ## Trombinoscopes ![trombinoscope](screens/Trombi-scodoc7.png) -*(en réalité vous aurez les photus de vos étudiants !)* +*(en réalité vous aurez les photos de vos étudiants !)* ## Autres fonctionnalités