DEVELOPER.RULES

pyjs developers are encouraged to observe the guidelines below:

* keep HEAD stable -- the latest repository code MUST work for production
  environments -- do your work in branches.

* feel free to announce on the list "i'm going to do xyz, any objections
  or input?" or otherwise, just happily take the initiative. if however,
  you are not an experienced developer, feel free to ask at any stage along
  the way

* respect PEP8 when sensible. there's a program called pep8.py capable of
  automatically checking for common oversights. maintaining consistency
  with established GWT function names, properties, etc. is more critical.

* add yourself to copyright and CREDITS. if kindly committing another's
  patch, please add them rather than yourself.

  this is IMPORTANT.  the copyright file is crucial for the acceptance of
  pyjs into some distributions, and is in general good practice: each and
  EVERY single copyright holder MUST be recorded. the copyright file is in
  DEP5 format (ie. machine-readable) so take care not to introduce
  extraneous whitespace or otherwise.

* ONLY ADD SOURCE CODE and ONLY ADD PYJS-RELATED source.

  look to existing examples for how to resolve 3rd party dependencies.

  DO NOT ADD binary-object files, executables, fonts, external images, or
  other non-function assets to the repository unless they are required for
  the purposes of the example/code at hand. lastly, the JavaScript
  autogenerated by the pyjs translator is considered
  "object code" and should NEVER be added.

* UI development: mirror GWT source as closely as possible. make use of
  java2py.py (in contrib) to do 95% of the conversion work for you ...
  religiously follow the GWT source code, trusting it pretty much 100%.
  _don't_ try to second-guess it; _don't_ try to "rework it"; in fact,
  don't _think_ at all: just "go with the flow". why? the GWT team
  resources far outpace out own, and the GWT codebase is already proven to
  some degree.

  no GWT source? try to find some elsewhere. if you really can't find
  anything exact, find something that's pretty close to what you want,
  subclass it if possible, and move forward.

  make CERTAIN you 100% understand the *.browser.py, *.{engine}.py
  and *.{platform}.py override system BEFORE clobbering UI code.

* UI committing: verify as many engine/example combinations as possible
    using both --enable-strict AND -O (for browsers). if you cannot teswell-known configuration, simply ask the list on test for you.
  to test on your behalf (before committing).

* core/translator committing:
    - verify/run libtest
  with --strict and with standard http://python.org; and do consider running 
   - pyv8run.sh (./pyv8test.sh --strict).  as there's a 64-bit
  version of libv8, now, that's not as hard as it used to be: pyv8 
  now compiles native on 64-bit. 

  also: translator changes _must_ be accompanied by
  a unit test (hence the reason why libtest must be run, under so many
  different environments).

* commits must be "single purpose".  if you're thinking of using the word
  "and" in the commit message, STOP and think.  see very first rule as
  to why this is important: i.e. if you break something, the WHOLE commit
  will be reverted; NO effort will be spent "dividing" the patch, when that
  should have been done by you in the first place.

* special version of the above: please _don't_ do major whitespace
  reorganisations at the same time as coding patches.  keep them separate,
  and commit whitespace patches with a commit message mentioning "whitespace".
  duh.

* commit messages must describe the patch not the action being taken!
  "added this"; "removed this" are NOT ok.

* commit messages should really include the bugreport number of the issue
  being fixed.  if there isn't a bugreport number, you should consider
  raising one.  it's just good practice.

* please try to keep discussion of bugs to the bugtracker, but also make
  sure that the pyjamas-dev list is alerted when a bug is raised.  it might
  not always work out that way, and if it doesn't, that's fine: it's just
  nice to be able to know what the hell's going on with a particular bug,
  without having to hunt through the rather obtuse pyjamas-dev google group.

that's about it.  the rest - do what you like! make sure you keep
people informed, engage them to help do testing.

DEVELOPER GIT BRANCHES

as it's probably well know, git makes branching super easy and cheap.
individual, public-facing branches should be in the form of:

<username>/(bug|feat)/<module>/<issueid>-<description>

username    = SourceForge user
bug|feat    = whichever appropriate
module      = the affected module, if any, or bootstrap/builtin/etc.
issueid     = the issue corresponding to this branch, if any
description = a small description of the branch's activities/purpose

this will assist anyone testing/observing.

example (developer):

# git clone git://pyjamas.git.sourceforge.net/gitroot/pyjamas/pyjamas
# git config remote.origin.pushurl ssh://<username>@pyjamas.git.sourceforge.net/gitroot/pyjamas/pyjamas
# git config remote.origin.push "refs/heads/<username>/*:refs/heads/<username>/*"
# git checkout -b <userXZY>/bug/101-default-stylesheet
# ...working/commiting/building...
# git push
   (branch get reviewed/tested/accepted)
# git checkout master
# git pull
# git rebase -i <userXZY>/bug/101-default-stylesheet
   (remove any merge commits)
# git push origin master

the remote.origin.push config option will enable pushing all your
branches by default.  when you want to push to master (public), you must
specify explicitly.

exxample (user):

# git clone git://pyjamas.git.sourceforge.net/gitroot/pyjamas/pyjamas
# git checkout -b testing <userXYZ>/bug/101-default-stylesheet
# git merge master
# python bootstrap.py
   (build apps/examples/etc.)

the checkout command will create a new branch, "testing", based off
the remote branch "<userXZY>/bug/101-default-stylesheet".  you can
switch between branches (testing different builds) without re-running
bootstrap.py.  for each new branch, merge "master".