infos for developpers

This commit is contained in:
Emmanuel Viennet 2021-01-28 09:47:27 +01:00
parent 42c27e752c
commit f0569694bf
5 changed files with 108 additions and 86 deletions

17
docs/Contribuer.md Normal file
View File

@ -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).

View File

@ -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": <https://google.github.io/styleguide/pyguide.html#383-functions-and-methods>
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 <https://scodoc.org/git/viennet/ScoDoc>
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

View File

@ -102,5 +102,5 @@ Pour vos tests en local, avec Chrome, modifier le paramétrage en réglant: `chr
#### Comment supprimer un département ? #### 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`. 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).

View File

@ -3,6 +3,8 @@
Informations pour les développeurs souhaitant étendre ou modifier ScoDoc. Informations pour les développeurs souhaitant étendre ou modifier ScoDoc.
## Informations générales
* S'abonner aux [listes de diffusion](ListesDeDiffusion.md) * S'abonner aux [listes de diffusion](ListesDeDiffusion.md)
* [Générer de nouveaux formats de bulletins PDF](ApiGenerationBulletinsPdf.md) * [Générer de nouveaux formats de bulletins PDF](ApiGenerationBulletinsPdf.md)
* [Créer de nouveaux types de "parcours"](ApiCreationParcours.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) * [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": <https://google.github.io/styleguide/pyguide.html#383-functions-and-methods>
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 <https://scodoc.org/git/viennet/ScoDoc>
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/`).

View File

@ -47,7 +47,7 @@ ScoDoc permet de définir des partitions et groupes en nombre quelconque, et d'y
## Trombinoscopes ## Trombinoscopes
![trombinoscope](screens/Trombi-scodoc7.png) ![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 ## Autres fonctionnalités