-
Notifications
You must be signed in to change notification settings - Fork 0
/
DEVELOPER.RULES
161 lines (126 loc) · 7.41 KB
/
DEVELOPER.RULES
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
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:
* 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.
* 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.
* 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.
* please add yourself to copyright and CREDITS. if kindly committing someone
else's patch, please add them rather than yourself, of course.
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
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
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
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".