3d_gpu/devnotes.mdwn

   1 # Notes for dev
   2
   3 * nmigen is python, therefore use pep8. Install autopep8 and use
   4  -v  -a -a -a --experimental. goes in Makefile
   5 * epydoc (old but still relevant) to be used to extract docstrings. again
   6   goes in Makefile
   7 * unit tests (python setup.py test) always to be developed extensively
   8   (synergistically) at time of code writing, NOT as an afterthought.
   9 * do not use import * !
  10 * modules to be kept very small, such that "yosys show" on reading
  11   verilog produces a small, legible diagram
  12 * module header to actually explain what the module does. link to
  13   requirements spec, and any other useful stuff.
  14 * ascii art recommended in module header to illustrate where bits go.
  15 * class header likewise required and explain purpose of the class.
  16 * code comments to be useful but not excessive to the point of drowning
  17   the code
  18 * functions not to exceed 60-70 (or so) lines, if possible. if too big,
  19   split into multiple functions (remember, nmigen constructs can be returned
  20   from a function)
  21
  22 # Git commits
  23
  24 * commits to be SMALL (5 - 15 lines max) and MUST not disrupt existing unit
  25   tests. unit tests always to be run prior to commit.
  26 * commits MUST be SINGLE PURPOSE. clue (red flag) is if the commit message
  27   includes the word "and".
  28 * commit message to explain purpose (ie not be "changed this" or "added that")
  29 * large commits ok as long as they are additions rather than modifications.
  30 * whitespace to be separate, "autopep8 cleanup" is sufficient.
  31 * when using bugtracker, include link to bugreport in commit message. Cross
  32   ref commit id to bugreport.
  33 * large refactoring (e.g. renaming functions) needs to be atomic and
  34   single-purpose as best as possible.  unit tests still need to pass,
  35   post-refactor.
  36
  37 # Which files should be added to the repository
  38
  39 **Only source files must be added to the repository.**
  40
  41 Output that is created from another command must not, with
  42 very very few exceptions, be added to the repository.  The reason is
  43 simple: each time a source file is modified, the auto-generated
  44 (compiled) output **also** changes.  If those changes are added
  45 to the repository, they become confused with the source code (a git
  46 diff will show *both* the source *and* changes to the auto-generated
  47 output).  If they are **not** added to the repository, the source and
  48 its auto-generated output become out-of-sync.
  49
  50 **Either way is bad**.
  51
  52 Instead, the following is advised:
  53
  54 * add the source code *only*
  55 * add a script or command that builds the source code, generating the output
  56 * do *NOT* add the *output* to the repository
  57 * add the script or command to the Makefile
  58 * list the command as a "build dependency" in the documentation
  59
  60 As a convenience and a courtesy, consider creating "release tarballs"
  61 (also adding the means to create them to the Makefile) so that people who
  62 for one reason or another cannot get or install the build dependencies
  63 may at least get the end-result of the work.  However this should be
  64 done as a low priority, or if there are financial offers of sponsorhip
  65 or other incentives received or to be gained by doing so.
  66