web2py

Aider web2py : Bugs, améliorations et documentation

web2py est très ouvert aux rapports de bug, aux améliorations de documentation et améliorations.

Google Group

Le forum principal pour discuter des bugs et des nouvelles fonctionnalités est : web2py-users (L'URL est https://groups.google.com/forum/#!forum/web2py)

Remplir un rapport de bug via Google Code

Si vous avez trouvé un bug et que vous en avez discuté sur le groupe, il peut vous être demandé de créer un rapport de bug en créant une 'Issue' sur Github https://github.com/web2py/web2py/issues

Reporter un bug de sécurité

Lorsque vous reportez des bugs de sécurité, soyez attentifs à la divulgation d'informations qui pourraient aider à l'exploitation malveillante d'une faille. Après avoir posté sur Google Group ou avoir relevé une issue sur le site Google Code, vous serez contacté par un développeurs pour partager les informations en privé.

Contribuer aux modification du code et de la documentation

Comment le code du projet est-il géré

Le code de base de web2py est géré sur un dépôt git Github. Le système original de contrôle de version était Mercurial chez Google, mais le développement actif est maintenant porté vers Github. web2py a deux versions importantes : la version stable courante, et le développement instantané. Sur git, le développement instantané est en général référencé comme "master", mais le projet web2py utilise "trunk", qui correspond le mieux au niveau terminologie à Mercurial.

Les bugs et les améliorations vont dans le trunk, donc pour tirer avantage de la correction du bug vous aurez besoin d'utiliser le trunk. Le meilleur moyen de faire ceci est de cloner le dépôt git. C'est la première étape quand on utilise le code stocké sur Github, et est bien documenté. Vu que les releases sont taguées, vous pouvez alterner entre la branche trunk (qui est 'master') et la release courante (ou toute autre release). Ceci rend le dépôt git très pratique.

Les compétences principales git dont vous aurez besoin sont :

1. cloner un dépôt hébergé sur Github
2. vérifier la branche master
3. vérifier la branche basée sur un tag

Tout ceci est bien couvert par les tutoriels Github : voir ci-après.

Discuter des modifications proposées

Si la modification se rapporte à un bug, la discussion sera probablement redirigée sur une Issue sur Google Code (voir ci-dessus). Si la modification se rapporte à une améliration, le groupe de développeur est le meilleur point de rencontre initial : web2py-developers group (l'URL est https://groups.google.com/forum/#!forum/web2py-developers)

Vu que web2py promet une rétro-compatibilité pour les fonctionnalitées non-expérimentales, accepter une modification dans le code de base est une promesse de maintenance pour les futurs utilisateurs, et c'est une promesse qui ne peut pas être prise à la légère. Les utilisateurs les moins expérimentés peuvent découvrir via les discussions qu'il existe une méthode pour achever ce qu'ils veulent; malheureusement, la documentation de ces "power features" lag parfois (voir l'amélioration de la documentation ci-dessous).

Lorsque vous êtes prêt à soumettre une modification de code, la discussion sera probablement redirigée vers les commentaires liés à la "Pull Request" (voir ci-après).

Coding style

Généralement, suivez le style de code PEP8. http://www.python.org/dev/peps/pep-0008/

Il y a un guide spécifique ici : web2py style

Astuces sur la mise en place d'un environnement de développement

Le chapitre 13 a quelques astuces sur l'utilisation d'EDI divers sur web2py.

Preparation : en utilisant GitHub

Depuis que web2py utilise GitHub, le flux général des modifications fonctionne ainsi :

1. Vous créez un clone de web2py sur GitHub, que GitHub appellera "forking".
2. Vous créez un clone de votre 'fork' web2py sur votre machine locale (ou n'importe où vous souhaitez faire les changements)
3. Vous repoussez vos changement sur votre fort GitHub
4. Vous faites une "pull request" via GitHub
5. Si votre "pull request" est acceptée, votre commit sera automatinquement intégré dans la branche master de web2py.

Au moment où j'écris, les techniques de base de git/GitHub sont présentées ici : https://help.GitHub.com/articles/fork-a-repo

Cependant, vous avez besoin de suivre les instructions ci-dessous pour savoir comment créer des patches qui pourront être fusionnés proprement.

Preparation : utiliser travis avec votre fort GitHub

web2py travaille avec travis, un service d'intégration continue de tests. Ceci signifie qu'un commit déclenchera tous les tests unitaires d'intégration.

Vous pouvez aisément ajouter travis à votre propre dépôt GitHub pour éviter d'envoyer des patches qui échoueront aux tests travis.

Suivez les instructions ici : http://about.travis-ci.org/docs/user/getting-started/

Les trois parties d'une amélioration de bonne qualité

Une amélioration de haute qualité se compose en trois parties :

1. La modification de code
2. Les tests de la nouvelle fonctionnalité
3. La mise à jour du book (qui est également maintenu sur GitHub)

Assurer un patch propre : utiliser la bonne technique de branche git

Utiliser git correctement est un peu plus complexe dans un projet partagé.

Voici les lignes directrices spécifiques pour être sûr que votre pull request sera appliquée correctement.

Tout d'abord, assurez-vous que vous avez un dépôt distant prêt qui pointe sur le dépôt principal web2py sur GitHub. Votre dépôt distant devrait être appelé upstream. Vous avez besoin de le faire une seule fois.

Ajouter un dépôt upstream est présenté par l'article GitHub d'introduction avec le lien ci-dessus, mais au cas où vous l'ayez raté, vous pouvez l'ajouter ainsi :

git remote add upstream https://GitHub.com/web2py/web2py/

Vous avez ensuite besoin d'un nom de branche pour vos changements. git conseille beaucoup de noms de branches, aussi spécifiques que possible. Pour web2py, nous recommandons des noms comme :

• tous les commits pour des corrections de bug devraient être dans une branche nommée "issue/number_of_the_issue_on_google_code" (comme issue/1684)
• tous les commits pour amélioration devrait être dans une branche nommée "enhancement/title_of_the_enhancement" (comme enhancement/trapped_links)

Dans votre environnement local, vérifiez la branche poru vos changements : Remplacez CHANGE1 par votre nom de branche.

git fetch upstream
git checkout -b CHANGE1 upstream/master

... apporte des modifications ou une sélection minutieuse depuis une autre branche locale. Faire un commit est nécessaire. Lorsque vous êtes prêt à envoyer vos modifications locales à votre fork web2py :

git push origin CHANGE1

<TODO insérer une note à propos de la possibilité de regrouper plusieurs commits en un>

et maintenant allez sur le site web GitHub, modifiez la nouvelle branche et effectuez une pull request. GitHub a un bouton "delete branch" une fois que votre pull request est fusionné ou fermé. Il n'y a aucune garantie, mais les PRs effectuent en général une revue en quelques jours. La plupart des gens envoyant des patchs en tant que PRs mettent également à jour le rapport d'erreur ou le fil de discussion de l'amélioration.

Ajouter des tests

Les tests unitaires devraient être ajoutés lorsqu'une amélioration est changée ou une fonctionnalité ajoutée. Les tests sont des scripts Python sont contenus dans gluon/tests Copier l'approche des tests existants. Vous noterez que les tests ont souvent besoin de créer quelque chose comme une table, effectuer un test de fonctionnalité et vérifier le résultat, et retourne ensuite à l'état précédant le test (ce qui dans ce cas, signifie effacer la table). Il y a une bonne référence sur les tests ici : Web2pyslice 1691

http://www.web2pyslices.com/slice/show/1691/help-developers-adding-tests-to-web2py

Effectuer les tests

Vous pouvez exécuter les tests :

python web2py.py --run_system_tests

Voir le slice référencé ci-dessus pour plus d'informations, incluant l'exécution des tests individuels.

Exemple de test unitaire

Ecrire des tests est facile. Voici un exemple de gluon/tests/test_dal.py Vous pouvez voir comment les tests étendent une classe TestCase. Notez comment une table suffisamment complexe est ajoutée, le test est effectué et la sortie validée, et ensuite les modifications sont détruites, remettant l'ensemble à l'état propre comme lorsque vous êtes arrivé.

class TestVirtualFields(unittest.TestCase):

    def testRun(self):
        db = DAL(DEFAULT_URI, check_reserved=['all'])
        db.define_table('tt', Field('aa'))
        db.commit()
        db.tt.insert(aa="test")
        class Compute:
            def a_upper(row): return row.tt.aa.upper()
        db.tt.virtualfields.append(Compute())
        assert db(db.tt.id>0).select().first().a_upper == 'TEST'
        db.tt.drop()
        db.commit()

Mettre à jour le book

Le book est également sur GitHub et le même workflow git peut être utilisé. La source du book contient les sources dans différentes langues, sous le répertoire sources. Le contenu est écrit en syntaxe markmin . Le book est une application web2py. Vous pouvez le trouver pratique pour faire un fork GitHub du livre, et le cloner sur votre dépôt local dans le répertoire applications d'une installation web2py. Ceci rend facile la visualisation de vos modifications sur un navigateur.

web2pyslices.com

web2pyslices.com est une ressource pour des gudies, des échantillons de code et des exemples.