Coding conventions

sailingcai edited this page Sep 13, 2010 · 31 revisions

We need to develop some conventions that will make collaboration smoother.

Let’s discuss these on the newsgroup and add/remove items.

  • if you want your new work to be included by others – keep your branch up-to date as much as possible or send a patch by email.
  • keep your master branch (or whichever branch you want others to pull into the master) free of experimental features and local modifications
  • discuss experimental features on the newsgroup before moving them onto the master branch
  • have all text files in UNIX mode (use dos2unix if necessary)
  • do not copy-paste code and templates

Python and Django

  • newly written code should run on Python2.4 and later version 2
  • Django 1.1 and later should be supported unless there is a compelling reason to use a later version

Templates

  • keep all messages in {% trans %} and {% blocktrans %} tags
  • do not copy-paste significant portions of html between templates
  • if you change templates – make sure they validate with http://validator.w3.org before publishing your changes
  • do not use empty elements for formatting (i.e. empty paragraph to make some space, <br/> tags where css would do the job)
  • do not use table-based layout in new templates

Translations

  • check validation of new translation messages containing html markup
  • all non-admin interface urls must be translated
  • if you change contents of msgstr or message key in templates and .py files – change it everywhere – including other language .po files
  • Translation document has some more details

Suggestions

  • pull/merge early – this will make resolving merge conflicts easier.
  • if you only want to merge in one-two files you can do this (please suggest a better recipe if you know one):

git fetch git@... bobs_branch:bob
git diff HEAD:path/file.py bob:path/file.py > file.diff

bobs_branch – name of the branch from his repository you want to pull (i.e. this may be “master”)
bob – is alias of his branch on your system

Examine file.diff, delete hunks you don’t want to apply, delete line in diff that has git object hex digits then run
patch < file.diff
give patch name of the file, that will update path/file.py with hunks that you kept in the diff file.