.. _development: ========== Developers ========== Git Access ---------- Read-only Git Access '''''''''''''''''''' :: git clone git://git.osuosl.org/gitolite/ganeti/ganeti_webmgr Commit Access ''''''''''''' Commit access requires an account on our gitolite server. You must `Submitting Patches`_ and establish a relationship with us prior to being granted commit access. :: git clone git@git.osuosl.org:ganeti/ganeti_webmgr Branch Layout ------------- We use `Git-flow `_ for managing our branches. Read about the `branching model `_ and why `you should use it too `_. - **master** - Releases only. - **develop** - Mostly stable development branch. Small changes only. It is acceptable that this branch have bugs, but should remain mostly stable. - **feature/** - Large code changes and new features. Coding Standards ---------------- We follow `PEP 8 `_, "the guide for python style". In addition to PEP 8: - Do not use backslash continuations. If a line must be broken up, use parenthetical continuations instead. Units ''''' Try to write modular code. Focus on isolating units of code that can be easily analyzed and tested. For sanity purposes, please try to avoid mutually recursive objects. JSON '''' If you need a JSON library, the import for this codebase is "from django.utils import simplejson as json". See `#6579 `_ for more information. Testing ''''''' Ganeti Web Manager has a fairly complete test suite. New code should have matching tests. Before committing code, run the suite for Ganeti Web Manager and `Object Permissions `_ :: ./manage.py test ganeti_web ./manage.py test object_permissions Clean up after yourself ''''''''''''''''''''''' Remember to tear down any resources you set up in your tests. Don't use "YourModel.objects.all().delete()" to clean up your objects; it could be hiding bugs. Clean up exactly the resources you created. Test your setups and teardowns '''''''''''''''''''''''''''''' To speed up analysis of broken tests, if you have a setUp() or tearDown() in a TestCase, add a test\_trivial() method which is empty. It will pass if your setUp() and tearDown() work. Views ''''' All views should be thoroughly tested for security, checking to ensure that the proper http codes are returned. - Test Anonymous User access - Test Permission based access - Test Superuser based access Check for invalid input. - missing fields - invalid data for field Templates & Javascript '''''''''''''''''''''' The test suite does not yet include selenium tests for verifying javascript functionality. Some basic tests can be performed using django's test suite: - Check objects in the context: forms, lists of objects, etc. - Check for existence of values in forms. Adding features ~~~~~~~~~~~~~~~ When adding a feature to GWM, please remember to include: Help tips ''''''''' The gray box with a green title bar that appears on the right side of the page when you focus on a form field is a help tip. To add one for a new field, add it to the file which corresponds to your field's form in the ganeti\_web/templates/ganeti/helptips/ directory. Internationalization '''''''''''''''''''' Ganeti Web Manager is designed to support translation to other languages using Django's i18n machinery. If you add text that will be displayed to the user, please remember to format it for translation: :: {% trans "this text will be displayed in the correct language" %} {% blocktrans %} Here is a some text that will be displayed in the correct language but would not fit well in a single line {% endblocktrans %} `Django's i18n page `_ has more information about this. Submitting Patches ------------------ Patches should either be attached to issues, or emailed to the mailing list. If a patch is relevant to an issue, then please attach the patch to the issue to prevent it from getting lost. Patches must be in git patch format, as generated by git format-patch. :: git commit git format-patch HEAD^ To create patches for all changes made from the origin's master branch, try: :: git format-patch origin/master For more information, see the man page for git-format-patch. Sending emails to the list can be made easier with git send-mail; see the man page for git-send-email for instructions on getting your email system to work with git. If there are multiple patches comprising a series which should be applied all at once, git pull requests are fine. Send a rationale for the pull request, along with a git pull URL and branch name, to the mailing list.