Skip to content

Commit

Permalink
Merge pull request #1488 from SpaceFox/maj_doc_pour_v1.0
Browse files Browse the repository at this point in the history 
Maj doc pour v1.0
  • Loading branch information
@SpaceFox
SpaceFox committed Sep 9, 2014
2 parents c829a84 + e8fd901 commit 7658414
Show file tree
Hide file tree
Showing 3 changed files with 99 additions and 66 deletions.
17 changes: 12 additions & 5 deletions CONTRIBUTING.md
View file
Expand Up @@ -15,16 +15,22 @@ Les contributions externes sont les bienvenues !
2. Faites vos modifications
3. Ajoutez un test pour votre modification. Seules les modifications de documentation et les réusinages n'ont pas besoin de nouveaux tests
4. Assurez-vous que l'intégralité des tests passent : `python manage.py test`
5. Poussez votre travail et faites une _pull request_
5. Assurez-vous que le code suit la [PEP-8](http://legacy.python.org/dev/peps/pep-0008/) : `flake8 --exclude=migrations,urls.py,settings.py --max-line-length=120 zds`
6. Si vous avez fait des modifications du _front_, jouez les tests associés : `gulp test`
7. Si vous modifiez le modèle (les fichiers models.py), n'oubliez pas de créer les fichiers de migration : `python manage.py schemamigration app_name --auto`
8. Poussez votre travail et faites une _pull request_

# Quelques bonnes pratiques
* Respectez [les conventions de code de Django](https://docs.djangoproject.com/en/1.6/internals/contributing/writing-code/coding-style/), ce qui inclut la [PEP 8 de Python](http://legacy.python.org/dev/peps/pep-0008/)
* Le code et les commentaires sont en anglais
* Le _workflow_ Git utilisé est le [git flow](http://nvie.com/posts/a-successful-git-branching-model/) à quelques détails près :
* Les contributions se font uniquement sur la branche `dev` (appelée `develop` dans le git flow standard)
* Lorsqu'on décide que `dev` est prête pour la prod, la branche est mergée dans `master` (les branches `releases` dans le git flow standard). Dès lors, cette branche ne reçoit plus que des corrections, aucune nouvelle fonctionnalité.
* Le _workflow_ Git utilisé est le [Git flow](http://nvie.com/posts/a-successful-git-branching-model/). En détail :
* Les arrivées fonctionnalités et corrections de gros bugs hors release se font via des PR.
* Ces PR sont unitaires. Aucune PR qui corrige plusieurs problèmes ou apporte plusieurs fonctionnalité ne sera accepté ; la règle est : une fonctionnalité ou une correction = une PR.
* Ces PR sont mergées dans la branche `dev` (appelée `develop` dans le git flow standard), après une QA légère.
* Pensez à préfixer vos branches selon l'objet de votre PR : `hotfix-XXX`, `feature-XXX`, etc.
* La branche `prod` (appelée `master` dans le git flow standard) contient exclusivement le code en production, pas la peine d'essayer de faire le moindre _commit_ dessus !

Tous les détails sur le workflow se trouvent [sur la page dédiée](doc/workflow.md).

* Votre test doit échouer sans votre modification, et réussir avec
* Faites des messages de _commit_ clairs et en français
Expand All @@ -41,9 +47,10 @@ Les contributions externes sont les bienvenues !
| Nouvelle Fonctionnalité ? | [oui|non]
| Tickets concernés | [Liste de tickets séparés par des virgules]
```
* Ajoutez des notes de QA (Quality Assurance). Ces notes doivent permettent à un testeur de comprendre ce que vous avez modifié, ce qu'il faut tester en priorité et les pièges auxquels il doit s'attendre et donc sur lesquels porter une attention particulière. Précisez tout particulièrement s'il est nécéssaire d'effectuer une action de gestion préalable, comme `python manage.py migrate`, `python manage.py loaddata fixture/*.yaml` ou `gulp build`.

## Les commits
* Pour les commits, nous suivons le même ordre d'idée des standards git, à savoir :
* Pour les commits, nous suivons le même ordre d'idée des standards Git, à savoir :
* La première ligne du commit ne doit pas faire plus de 50 caractères
* Si besoin, complétez votre commit via des commentaires, en respectant une limite de 70 caractères par ligne
* Bien que le code soit en anglais, le commit doit être de préférence en français
Expand Down
72 changes: 11 additions & 61 deletions README.md
View file
@@ -1,55 +1,34 @@
[![Build Status](https://travis-ci.org/zestedesavoir/zds-site.svg?branch=dev)](https://travis-ci.org/zestedesavoir/zds-site)
[![Coverage Status](https://coveralls.io/repos/zestedesavoir/zds-site/badge.png?branch=dev)](https://coveralls.io/r/zestedesavoir/zds-site?branch=dev)
[![Licnce GPL](http://img.shields.io/badge/license-GPL-yellow.svg)](http://www.gnu.org/licenses/quick-guide-gplv3.fr.html)
[![Licence GPL](http://img.shields.io/badge/license-GPL-yellow.svg)](http://www.gnu.org/licenses/quick-guide-gplv3.fr.html)





Zeste de Savoir
===============
# Zeste de Savoir

Site internet communautaire codé à l'aide du framework [Django](https://www.djangoproject.com/) 1.6 et de [Python](https://www.djangoproject.com/) 2.7.

* Lien du site : [zestedesavoir](http://www.zestedesavoir.com)

## Fonctionnalités implementées




Fonctionnalités implementées
----------------------------

- Membres
- Tutoriels
- Articles
- Membres
- Forums
- Messages privés
- Galeries d'images
- Recherche





Fonctionnalités à venir
-----------------------
## Fonctionnalités à venir

Elles sont reportées essentiellement dans le [bugtraker](https://github.com/zestedesavoir/zds-site/issues).





Comment démarrer une instance de ZdS ?
--------------------------------------

## Comment démarrer une instance de ZdS ?

### Installation d'une version locale de ZdS
- [Intallation sur Windows](doc/install-windows.md)
- [Intallation sur Linux](doc/install-linux.md)
- [Intallation sur OS X](doc/install-os-x.md)

- [Installation de Solr](doc/install-solr.md) pour gérer la recherche

### Mettre à jour votre version locale de ZdS
Après avoir mis à jour votre dépot, vous devez executer les commandes suivantes (depuis la racine de votre projet) pour mettre à jour les dépendances.
Expand All @@ -59,7 +38,6 @@ python manage.py migrate
pip install --upgrade -r requirements.txt
```


### Données de test
Pour bénéficier de données de test, exécutez les commandes suivantes, dans l'ordre, à la fin des précédentes :

Expand Down Expand Up @@ -91,42 +69,14 @@ Vous pourrez ensuite la consulter en ouvrant le fichier `zds-site/doc/sphinx/bui

### Conseils de developpement

Avant de faire une Pull Request (PR), vérifiez que votre code passe tous les tests unitaires et qu'il est compatible [PEP-8](http://legacy.python.org/dev/peps/pep-0008/) en exécutant les commandes suivantes, pour le back :
Vous trouverez tout sur [la page dédiée de la documentation](CONTRIBUTING.md)

```console
python manage.py test
flake8 --exclude=migrations,urls.py,settings.py --max-line-length=120 zds
```

Pour le front :

```console
gulp test
```

Si vous modifiez le modèle (les fichiers models.py), n'oubliez pas de créer les fichiers de migration :

```console
python manage.py schemamigration app_name --auto
```

Si vous avez une connexion lente et que vous ne voulez travailler que sur une branche précise, vous pouvez toujours ne récupérer que celle-ci :

```console
git clone https://github.com/zestedesavoir/zds-site.git -b LA_BRANCHE --depth 1
```



En savoir plus
--------------
## En savoir plus

- [Comment déployer ZDS sur un serveur de production ?](doc/deploy.md)
- [Contribuer](CONTRIBUTING.md)
- [Comment contribuer et conseils de développement](CONTRIBUTING.md)
- [Comment contribuer : comprendre comment suivre le workflow (sur zds)](http://zestedesavoir.com/forums/sujet/324/comment-contribuer-comprendre-comment-suivre-le-workflow/)



- [Les détails du workflow utilisé sur Zeste de Savoir](doc/workflow.md)


Zeste de Savoir est basé sur un fork de [Progdupeu.pl](http://progdupeu.pl) ([Dépôt Bitbucket](https://bitbucket.org/MicroJoe/progdupeupl/)).
76 changes: 76 additions & 0 deletions doc/workflow.md
View file
@@ -0,0 +1,76 @@
Cette page détaille le _workflow_ utilisé sur Zeste de Savoir. Elle est là surtout pour satisfaire votre curiosité, à moins d'avoir les droits de faire une Mise En Production (MEP). La [page de contribution](CONTRIBUTING.md) devrait répondre à vos questions quant au processus de développement.

Ce _workflow_ est très fortement basé sur le [Git flow](http://nvie.com/posts/a-successful-git-branching-model/).

# _Workflow_ général

L'idée générale est très simple :

- Le développement se fait sur la branche `dev`
- La branche `prod` contient la version en production
- Lorsqu'on juge qu'on a assez de matière pour un nouveau déploiement, on crée une branche dédiée (par exemple `release-v1.7`), qui est testée en pré-production et corrigée sur cette branche
- En cas de bug ultra-urgent à corriger en production, on crée une branche spéciale

# _Workflow_ de développement

## Description

1. Les arrivées fonctionnalités et corrections de gros bugs se font via des _Pull Requests_ (PR) depuis des _forks_.
2. Ces PR sont unitaires. Aucune PR qui corrige plusieurs problèmes ou apporte plusieurs fonctionnalité ne sera accepté ; la règle est : une fonctionnalité ou une correction = une PR.
3. Ces PR sont mergées dans la branche `dev` (appelée `develop` dans le git flow standard), après une _Quality Assurance_ (QA) légère.
4. La branche `prod` (appelée `master` dans le git flow standard) contient exclusivement le code en production, pas la peine d'essayer de faire le moindre _commit_ dessus !
5. Les branches du dépôt principal (`dev`, `prod` et la branche de release) ne devraient contenir que des merge de PR, aucun commit direct.

## Quelques précisions

**Où peut-on trouver les détails pratiques ?**

Tous ces détails sont [dans la page de contribution](CONTRIBUTING.md). On y trouve entre autres les recommendations en terme de PR ou de messages de commits.

**Qu'est-ce qu'une "QA légère"** ?

C'est s'assurer que le code fait ce qu'il devrait sans passer des heures à re-tester l'intégralité du site. Concrètement, cela implique :

- Une revue de code
- La vérification que des tests correspondants à la fonctionnalité ou à la correction sont présents, cohérents et passent
- Des tests manuels dans le cas de fonctionnalités ou corrections complexes et/ou critiques (au cas par cas)

# _Workflow_ de mise en production

## Description

1. Quand on a assez de nouveautés dans `dev` (mais pas trop), on décide de faire une _release_. L'idée est de pouvoir vérifier et corriger les problèmes de cette _release_ rapidement, en moins de 2 semaines entre le lancement de la release et sa MEP.
1. Création d'une **nouvelle branche de release** du nom de la version (par exemple `release-v1.7`)
2. Déploiement de cette branche sur l'environnement de pré-production, avec un _dump_ de données de production
3. Tests les plus complets possibles sur ce nouvel environnement
4. Corrections éventuelles sur cette branche de _release_. Les corrections **ne sont pas remontées sur `dev`** au fur et à mesure. Cf ci-dessous pour les détails.
2. Lorsqu'on a bien testé cette branche, on la met en production :
1. Merge de la branche de _release_ dans `dev`
2. Merge de la branche de _release_ dans `prod`
3. Tag avec la nouvelle version
4. Mise en production sur le serveur
5. Suppression de la branche de _release_, devenue inutile

Le temps maximum entre la création d'une branche de _release_ et sa mise en production est de **deux semaines**. Au-delà on considère qu'il y a trop de problèmes et qu'ils risquent de bloquer le développement :

1. Merge des corrections de la branche de _release_ dans `dev`
2. Pas de mise en production
3. Suppression de la branche de _release_, devenue inutile

## En cas de problèmes sur la release

Vous l'avez lu : les corrections de `master` **ne sont pas remontées sur `dev`** au fur et à mesure. La raison est que ça prends du temps, de l'énergie et que ça fait beaucoup de merges croisés. Donc toutes les corrections sont remontées en même temps lors de la mise en production. Conséquences :

- Si vous bossez sur `dev` pendant qu'une _release_ est en cours, pas la peine de corriger un bug déjà corrigé sur la _release_ : la PR serait refusée (pour cause de doublon).
- Si un _gros_ problème est détecté sur la _release_ et qu'il est correctible en un temps raisonnable :
1. Il est corrigé sur la branche de _release_.
2. Les merges de PR sur `dev` qui impliquent un risque même vague de conflit sont bloqués.
3. S'il y a quand même un conflit (à cause d'une PR mergée sur `dev` avant la détection du problème), la personne qui règle le problème fournit 2 correctifs : un pour la branche de _release_ et un pour la branche de de `dev`.

Ceci fonctionne bien si les développements sont de bonne qualité, donc avec peu de correctifs sur la branche de _release_ (idéalement aucun !)... les codes approximatifs et non testés seront donc refusés sans la moindre pitié !

# Glossaire

- **MEP** : Mise En Production
- **PR** : _Pull Request_
- **QA** : _Quality Assurance_

0 comments on commit 7658414

Please sign in to comment.