Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 137 lines (105 sloc) 6.09 kb
7282d2a C Anthony Risinger rules: some initial changes ... this file should be dropped really
xtfxme authored
1 pyjs developers are encouraged to observe the guidelines below:
27c606a add developer rules
lkcl authored
2
7282d2a C Anthony Risinger rules: some initial changes ... this file should be dropped really
xtfxme authored
3 * keep HEAD stable -- the latest repository code MUST work for production
4 environments -- do your work in branches.
27c606a add developer rules
lkcl authored
5
7282d2a C Anthony Risinger rules: some initial changes ... this file should be dropped really
xtfxme authored
6 * feel free to announce on the list "i'm going to do xyz, any objections
7 or input?" or otherwise, just happily take the initiative. if however,
8 you are not an experienced developer, feel free to ask at any stage along
9 the way
54636ed update DEVELOPER.RULES
Luke Leighton authored
10
7282d2a C Anthony Risinger rules: some initial changes ... this file should be dropped really
xtfxme authored
11 * respect PEP8 when sensible. there's a program called pep8.py capable of
12 automatically checking for common oversights. maintaining consistency
13 with established GWT function names, properties, etc. is more critical.
27c606a add developer rules
lkcl authored
14
7282d2a C Anthony Risinger rules: some initial changes ... this file should be dropped really
xtfxme authored
15 * add yourself to copyright and CREDITS. if kindly committing another's
16 patch, please add them rather than yourself.
a4276a9 add developer rules
lkcl authored
17
18 this is IMPORTANT. the copyright file is crucial for the acceptance of
7282d2a C Anthony Risinger rules: some initial changes ... this file should be dropped really
xtfxme authored
19 pyjs into some distributions, and is in general good practice: each and
20 EVERY single copyright holder MUST be recorded. the copyright file is in
21 DEP5 format (ie. machine-readable) so take care not to introduce
22 extraneous whitespace or otherwise.
23
24 * ONLY ADD SOURCE CODE and ONLY ADD PYJS-RELATED source.
25
26 look to existing examples for how to resolve 3rd party dependencies.
27
28 DO NOT ADD binary-object files, executables, fonts, external images, or
29 other non-function assets to the repository unless they are required for
30 the purposes of the example/code at hand. lastly, the JavaScript
31 autogenerated by the pyjs translator is considered
32 "object code" and should NEVER be added.
33
34 * UI development: mirror GWT source as closely as possible. make use of
35 java2py.py (in contrib) to do 95% of the conversion work for you ...
36 religiously follow the GWT source code, trusting it pretty much 100%.
37 _don't_ try to second-guess it; _don't_ try to "rework it"; in fact,
38 don't _think_ at all: just "go with the flow". why? the GWT team
39 resources far outpace out own, and the GWT codebase is already proven to
40 some degree.
41
42 no GWT source? try to find some elsewhere. if you really can't find
43 anything exact, find something that's pretty close to what you want,
44 subclass it if possible, and move forward.
45
46 make CERTAIN you 100% understand the *.browser.py, *.{engine}.py
47 and *.{platform}.py override system BEFORE clobbering UI code.
48
49 * UI committing: verify as many engine/example combinations as possible
50 using both --enable-strict AND -O (for browsers). if you cannot teswell-known configuration, simply ask the list on test for you.
51 to test on your behalf (before committing).
52
53 * core/translator committing:
54 - verify/run libtest
27c606a add developer rules
lkcl authored
55 with --strict and with standard http://python.org; and do consider running
7282d2a C Anthony Risinger rules: some initial changes ... this file should be dropped really
xtfxme authored
56 - pyv8run.sh (./pyv8test.sh --strict). as there's a 64-bit
27c606a add developer rules
lkcl authored
57 version of libv8, now, that's not as hard as it used to be: pyv8
58 now compiles native on 64-bit.
59
7282d2a C Anthony Risinger rules: some initial changes ... this file should be dropped really
xtfxme authored
60 also: translator changes _must_ be accompanied by
54636ed update DEVELOPER.RULES
Luke Leighton authored
61 a unit test (hence the reason why libtest must be run, under so many
7bb1b7e add extra clarification to DEVELOPER.RULES: requirement for unit tests o...
Luke Kenneth Casson Leighton authored
62 different environments).
63
27c606a add developer rules
lkcl authored
64 * commits must be "single purpose". if you're thinking of using the word
65 "and" in the commit message, STOP and think. see very first rule as
66 to why this is important: i.e. if you break something, the WHOLE commit
67 will be reverted; NO effort will be spent "dividing" the patch, when that
68 should have been done by you in the first place.
69
70 * special version of the above: please _don't_ do major whitespace
71 reorganisations at the same time as coding patches. keep them separate,
72 and commit whitespace patches with a commit message mentioning "whitespace".
73 duh.
74
75 * commit messages must describe the patch not the action being taken!
76 "added this"; "removed this" are NOT ok.
77
78 * commit messages should really include the bugreport number of the issue
79 being fixed. if there isn't a bugreport number, you should consider
80 raising one. it's just good practice.
81
82 * please try to keep discussion of bugs to the bugtracker, but also make
83 sure that the pyjamas-dev list is alerted when a bug is raised. it might
84 not always work out that way, and if it doesn't, that's fine: it's just
85 nice to be able to know what the hell's going on with a particular bug,
86 without having to hunt through the rather obtuse pyjamas-dev google group.
87
88 that's about it. the rest - do what you like! make sure you keep
89 people informed, engage them to help do testing.
90
fab7ce6 update DEVELOPER.RULES, better examples
C Anthony Risinger authored
91 DEVELOPER GIT BRANCHES
8c3e45b add C Anthony's git branch naming rules to DEVELOPER_RULES
chema authored
92
fab7ce6 update DEVELOPER.RULES, better examples
C Anthony Risinger authored
93 as it's probably well know, git makes branching super easy and cheap.
94 individual, public-facing branches should be in the form of:
8c3e45b add C Anthony's git branch naming rules to DEVELOPER_RULES
chema authored
95
96 <username>/(bug|feat)/<module>/<issueid>-<description>
97
fab7ce6 update DEVELOPER.RULES, better examples
C Anthony Risinger authored
98 username = SourceForge user
99 bug|feat = whichever appropriate
100 module = the affected module, if any, or bootstrap/builtin/etc.
101 issueid = the issue corresponding to this branch, if any
102 description = a small description of the branch's activities/purpose
103
104 this will assist anyone testing/observing.
105
106 example (developer):
107
108 # git clone git://pyjamas.git.sourceforge.net/gitroot/pyjamas/pyjamas
109 # git config remote.origin.pushurl ssh://<username>@pyjamas.git.sourceforge.net/gitroot/pyjamas/pyjamas
110 # git config remote.origin.push "refs/heads/<username>/*:refs/heads/<username>/*"
111 # git checkout -b <userXZY>/bug/101-default-stylesheet
112 # ...working/commiting/building...
113 # git push
114 (branch get reviewed/tested/accepted)
115 # git checkout master
116 # git pull
117 # git rebase -i <userXZY>/bug/101-default-stylesheet
118 (remove any merge commits)
119 # git push origin master
8c3e45b add C Anthony's git branch naming rules to DEVELOPER_RULES
chema authored
120
121 the remote.origin.push config option will enable pushing all your
fab7ce6 update DEVELOPER.RULES, better examples
C Anthony Risinger authored
122 branches by default. when you want to push to master (public), you must
123 specify explicitly.
8c3e45b add C Anthony's git branch naming rules to DEVELOPER_RULES
chema authored
124
fab7ce6 update DEVELOPER.RULES, better examples
C Anthony Risinger authored
125 exxample (user):
8c3e45b add C Anthony's git branch naming rules to DEVELOPER_RULES
chema authored
126
fab7ce6 update DEVELOPER.RULES, better examples
C Anthony Risinger authored
127 # git clone git://pyjamas.git.sourceforge.net/gitroot/pyjamas/pyjamas
128 # git checkout -b testing <userXYZ>/bug/101-default-stylesheet
129 # git merge master
130 # python bootstrap.py
131 (build apps/examples/etc.)
8c3e45b add C Anthony's git branch naming rules to DEVELOPER_RULES
chema authored
132
133 the checkout command will create a new branch, "testing", based off
fab7ce6 update DEVELOPER.RULES, better examples
C Anthony Risinger authored
134 the remote branch "<userXZY>/bug/101-default-stylesheet". you can
135 switch between branches (testing different builds) without re-running
136 bootstrap.py. for each new branch, merge "master".
Something went wrong with that request. Please try again.