Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
rules: some initial changes ... this file should be dropped really
  • Loading branch information
C Anthony Risinger committed Aug 23, 2012
1 parent 88ee93e commit 7282d2a
Showing 1 changed file with 50 additions and 75 deletions.
125 changes: 50 additions & 75 deletions DEVELOPER.RULES
@@ -1,88 +1,63 @@
For developers assisting on pyjamas, a laissez-faire attitude is taken: pyjs developers are encouraged to observe the guidelines below:
if you want repository access, all you have to do is ask. Follow the
rules below, and you'll do ok with this multi-project project:


* break stuff in latest repo, it gets reverted. the prime rule of pyjamas * keep HEAD stable -- the latest repository code MUST work for production
is that the latest repository code MUST work, for production environments environments -- do your work in branches.
to be able to use it.


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


* obey PEP8 where it's sensible to do so. there's a program called pep8.py * respect PEP8 when sensible. there's a program called pep8.py capable of
which automatically checks stuff. one rule we have to break is to remain automatically checking for common oversights. maintaining consistency
consistent with GWT function names - it's just... tough luck :) that, with established GWT function names, properties, etc. is more critical.
and properties in pyjs are too expensive, we have to use the silly
get{Property} and set{Property} function names. oh well.


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


this is IMPORTANT. the copyright file is crucial for the acceptance of this is IMPORTANT. the copyright file is crucial for the acceptance of
pyjamas into debian: each and EVERY single copyright holder MUST be pyjs into some distributions, and is in general good practice: each and
recorded. please note that the copyright file is in the format specified EVERY single copyright holder MUST be recorded. the copyright file is in
by debian DEP5 (which is pretty blindingly obvious, but just... please bear DEP5 format (ie. machine-readable) so take care not to introduce
it in mind that the copyright file is in a machine-readable extraneous whitespace or otherwise.
standards-compliant format)

* ONLY ADD SOURCE CODE and ONLY ADD PYJS-RELATED source.
* please ONLY ADD SOURCE CODE and ONLY ADD PYJAMAS-RELATED source code.

look to existing examples for how to resolve 3rd party dependencies.
on no account add the source code of an external project to pyjamas:
create a download script which fetches and unpacks a stable revision DO NOT ADD binary-object files, executables, fonts, external images, or
of that code. other non-function assets to the repository unless they are required for

the purposes of the example/code at hand. lastly, the JavaScript
on ABSOLUTELY NO ACCOUNT add any binary-object files, executables, autogenerated by the pyjs translator is considered
fonts, external images that were written by and for other projects, "object code" and should NEVER be added.
or anything OTHER than pyjamas source code.

* UI development: mirror GWT source as closely as possible. make use of
if however an image is required for example as part of CSS styling in the java2py.py (in contrib) to do 95% of the conversion work for you ...
examples, and the image's Copyright is your own, or the License on the religiously follow the GWT source code, trusting it pretty much 100%.
image can be established to be a compatible Software (Libre) License, then _don't_ try to second-guess it; _don't_ try to "rework it"; in fact,
it *may* be added to the repository. 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
also please remember that the javascript that is auto-generated by some degree.
the pyjamas compiler is also considered to be "object code", and as
such should NEVER be added to the pyjamas repository. 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,
anything that is needed must either be downloaded or it must be subclass it if possible, and move forward.
compiled (or both). there are at present three download.sh scripts
(in the examples) which can be used for inspiration and guidance. make CERTAIN you 100% understand the *.browser.py, *.{engine}.py

and *.{platform}.py override system BEFORE clobbering UI code.
if in doubt - ask on the developer list BEFORE committing because it is
a royal pain to permanently destroy-delete files in git. * 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.
* pyjamas UI development: follow GWT source code as closely as possible. to test on your behalf (before committing).
make use of java2py.py (in contrib) to do 95% of the conversion work for
you. don't just follow the GWT API: do _literally_ "blindly" follow * core/translator committing:
the GWT source code, trusting it pretty much 100%. _don't_ try to - verify/run libtest
second-guess it; _don't_ try to "rework it"; in fact, don't _think_ at
all: just "go with the flow". the reason is simple: the GWT team have
far more resources than we do, and if you want to re-learn all of the
"browser tricks" that they've spent man-decades finding and working
around _go ahead_ :)

if GWT source doesn't exist: try to find some. if you _really_ can't
find anything, then find something that's pretty close to what you want,
subclass it if possible, and go from there.

also: make DAMN SURE that you are aware of the __browser__, __{engine}__
and the platform/* overrides systems BEFORE messing with UI code.

* before pyjamas UI committing:
check as _many_ engines and browsers as you can using as many
examples as you can stand, using both --strict _and_ -O for browsers.
if you don't have certain engines or browsers, TELL PEOPLE and ask them
to test on your behalf. preferably before committing.

* non-UI-related stuff (compiler-related) make damn sure you run libtest
with --strict and with standard http://python.org; and do consider running with --strict and with standard http://python.org; and do consider running
under pyv8run.sh as well (./pyv8test.sh --strict). as there's a 64-bit - 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 version of libv8, now, that's not as hard as it used to be: pyv8
now compiles native on 64-bit. now compiles native on 64-bit.


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


Expand Down

0 comments on commit 7282d2a

Please sign in to comment.