Skip to content
This repository
tag: 0.8.1a
Fetching contributors…

Cannot retrieve contributors at this time

file 161 lines (126 sloc) 7.587 kb
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".
Something went wrong with that request. Please try again.