docs/source/dev/developers.rst

   1 .. _development:
   2
   3 ==========
   4 Developers
   5 ==========
   6
   7 Git Access
   8 ----------
   9
  10 Read-only Git Access
  11 ''''''''''''''''''''
  12
  13 ::
  14
  15     git clone git://git.osuosl.org/gitolite/ganeti/ganeti_webmgr
  16
  17 Commit Access
  18 '''''''''''''
  19
  20 Commit access requires an account on our gitolite server. You must
  21 `Submitting Patches`_ and establish a relationship with us prior to being
  22 granted commit access.
  23
  24 ::
  25
  26     git clone git@git.osuosl.org:ganeti/ganeti_webmgr
  27
  28 Branch Layout
  29 -------------
  30
  31 We use `Git-flow <http://github.com/nvie/gitflow>`_ for managing our
  32 branches. Read about the `branching
  33 model <http://nvie.com/posts/a-successful-git-branching-model/>`_ and
  34 why `you should use it
  35 too <http://jeffkreeftmeijer.com/2010/why-arent-you-using-git-flow/>`_.
  36
  37 -  **master** - Releases only.
  38 -  **develop** - Mostly stable development branch. Small changes only.
  39    It is acceptable that this branch have bugs, but should remain mostly
  40    stable.
  41 -  **feature/<name>** - Large code changes and new features.
  42
  43 Coding Standards
  44 ----------------
  45
  46 We follow `PEP 8 <http://www.python.org/dev/peps/pep-0008/>`_, "the
  47 guide for python style".
  48
  49 In addition to PEP 8:
  50
  51 -  Do not use backslash continuations. If a line must be broken up, use
  52    parenthetical continuations instead.
  53
  54 Units
  55 '''''
  56
  57 Try to write modular code. Focus on isolating units of code that can be
  58 easily analyzed and tested. For sanity purposes, please try to avoid
  59 mutually recursive objects.
  60
  61 JSON
  62 ''''
  63
  64 If you need a JSON library, the import for this codebase is "from
  65 django.utils import simplejson as json". See `#6579 <http://code.osuosl.org/issues/6579>`_ for
  66 more information.
  67
  68 Testing
  69 '''''''
  70
  71 Ganeti Web Manager has a fairly complete test suite. New code should
  72 have matching tests. Before committing code, run the suite for Ganeti
  73 Web Manager and `Object
  74 Permissions <http://code.osuosl.org/projects/object-permissions>`_
  75
  76 ::
  77
  78     ./manage.py test ganeti_web
  79     ./manage.py test object_permissions
  80
  81 Clean up after yourself
  82 '''''''''''''''''''''''
  83
  84 Remember to tear down any resources you set up in your tests. Don't use
  85 "YourModel.objects.all().delete()" to clean up your objects; it could be
  86 hiding bugs. Clean up exactly the resources you created.
  87
  88 Test your setups and teardowns
  89 ''''''''''''''''''''''''''''''
  90
  91 To speed up analysis of broken tests, if you have a setUp() or
  92 tearDown() in a TestCase, add a test\_trivial() method which is empty.
  93 It will pass if your setUp() and tearDown() work.
  94
  95 Views
  96 '''''
  97
  98 All views should be thoroughly tested for security, checking to ensure
  99 that the proper http codes are returned.
 100
 101 -  Test Anonymous User access
 102 -  Test Permission based access
 103 -  Test Superuser based access
 104
 105 Check for invalid input.
 106
 107 -  missing fields
 108 -  invalid data for field
 109
 110 Templates & Javascript
 111 ''''''''''''''''''''''
 112
 113 The test suite does not yet include selenium tests for verifying
 114 javascript functionality. Some basic tests can be performed using
 115 django's test suite:
 116
 117 -  Check objects in the context: forms, lists of objects, etc.
 118 -  Check for existence of values in forms.
 119
 120 Adding features
 121 ~~~~~~~~~~~~~~~
 122
 123 When adding a feature to GWM, please remember to include:
 124
 125 Help tips
 126 '''''''''
 127
 128 The gray box with a green title bar that appears on the right side of
 129 the page when you focus on a form field is a help tip. To add one for a
 130 new field, add it to the file which corresponds to your field's form in
 131 the ganeti\_web/templates/ganeti/helptips/ directory.
 132
 133 Internationalization
 134 ''''''''''''''''''''
 135
 136 Ganeti Web Manager is designed to support translation to other languages
 137 using Django's i18n machinery. If you add text that will be displayed to
 138 the user, please remember to format it for translation:
 139 ::
 140
 141     {% trans "this text will be displayed in the correct language" %}
 142
 143     {% blocktrans %}
 144         Here is a some text that will be displayed
 145         in the correct language but would not
 146         fit well in a single line
 147     {% endblocktrans %}
 148
 149 `Django's i18n
 150 page <https://docs.djangoproject.com/en/dev/topics/i18n/>`_ has more
 151 information about this.
 152
 153 Submitting Patches
 154 ------------------
 155
 156 Patches should either be attached to issues, or emailed to the mailing
 157 list. If a patch is relevant to an issue, then please attach the patch
 158 to the issue to prevent it from getting lost.
 159
 160 Patches must be in git patch format, as generated by git format-patch.
 161
 162 ::
 163
 164     git commit
 165     git format-patch HEAD^
 166
 167 To create patches for all changes made from the origin's master branch,
 168 try:
 169
 170 ::
 171
 172     git format-patch origin/master
 173
 174 For more information, see the man page for git-format-patch.
 175
 176 Sending emails to the list can be made easier with git send-mail; see
 177 the man page for git-send-email for instructions on getting your email
 178 system to work with git.
 179
 180 If there are multiple patches comprising a series which should be
 181 applied all at once, git pull requests are fine. Send a rationale for
 182 the pull request, along with a git pull URL and branch name, to the
 183 mailing list.