forked from ScoDoc/DocScoDoc
infos for developpers
This commit is contained in:
parent
c799edbe11
commit
18cffea24d
17
docs/Contribuer.md
Normal file
17
docs/Contribuer.md
Normal 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).
|
||||
@ -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
|
||||
@ -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).
|
||||
|
||||
@ -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": <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/`).
|
||||
|
||||
|
||||
|
||||
@ -47,7 +47,7 @@ ScoDoc permet de définir des partitions et groupes en nombre quelconque, et d'y
|
||||
|
||||
## Trombinoscopes
|
||||
|
||||
*(en réalité vous aurez les photus de vos étudiants !)*
|
||||
*(en réalité vous aurez les photos de vos étudiants !)*
|
||||
|
||||
## Autres fonctionnalités
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user