Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

rules: some initial changes ... this file should be dropped really

  • Loading branch information...
commit 7282d2ab96b7d7064593bd7860c99a2d5beb436a 1 parent 88ee93e
@xtfxme xtfxme authored
Showing with 50 additions and 75 deletions.
  1. +50 −75 DEVELOPER.RULES
View
125 DEVELOPER.RULES
@@ -1,88 +1,63 @@
-For developers assisting on pyjamas, a laissez-faire attitude is taken:
-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:
+pyjs developers are encouraged to observe the guidelines below:
-* break stuff in latest repo, it gets reverted. the prime rule of pyjamas
- is that the latest repository code MUST work, for production environments
- to be able to use it.
+* keep HEAD stable -- the latest repository code MUST work for production
+ environments -- do your work in branches.
-* other than that, please feel free to announce on the list "i'm going to do
- xyz, any objections or input" but otherwise just happily take the initiative.
- if however you are not an experienced developer then feel free to ask at
- each stage before proceeding.
+* 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
-* obey PEP8 where it's sensible to do so. there's a program called pep8.py
- which automatically checks stuff. one rule we have to break is to remain
- consistent with GWT function names - it's just... tough luck :) that,
- and properties in pyjs are too expensive, we have to use the silly
- get{Property} and set{Property} function names. oh well.
+* 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.
-* please add yourself to copyright and CREDITS. if kindly committing someone
- else's patch, please add them rather than yourself, of course.
+* 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
- pyjamas into debian: each and EVERY single copyright holder MUST be
- recorded. please note that the copyright file is in the format specified
- by debian DEP5 (which is pretty blindingly obvious, but just... please bear
- it in mind that the copyright file is in a machine-readable
- standards-compliant format)
-
-* please ONLY ADD SOURCE CODE and ONLY ADD PYJAMAS-RELATED source code.
-
- on no account add the source code of an external project to pyjamas:
- create a download script which fetches and unpacks a stable revision
- of that code.
-
- on ABSOLUTELY NO ACCOUNT add any binary-object files, executables,
- fonts, external images that were written by and for other projects,
- or anything OTHER than pyjamas source code.
-
- if however an image is required for example as part of CSS styling in the
- examples, and the image's Copyright is your own, or the License on the
- image can be established to be a compatible Software (Libre) License, then
- it *may* be added to the repository.
-
- also please remember that the javascript that is auto-generated by
- the pyjamas compiler is also considered to be "object code", and as
- such should NEVER be added to the pyjamas repository.
-
- anything that is needed must either be downloaded or it must be
- compiled (or both). there are at present three download.sh scripts
- (in the examples) which can be used for inspiration and guidance.
-
- if in doubt - ask on the developer list BEFORE committing because it is
- a royal pain to permanently destroy-delete files in git.
-
-* pyjamas UI development: follow GWT source code as closely as possible.
- 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
- 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". 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
+ 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
- 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
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
different environments).
Please sign in to comment.
Something went wrong with that request. Please try again.