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