Notes for dev

  • nmigen is python, therefore use pep8. Install autopep8 and use -v -a -a -a --experimental. goes in Makefile
  • recommended to use "python3 setup.py develop", it makes life a lot easier.
  • epydoc (old but still relevant) to be used to extract docstrings. again goes in Makefile
  • some people may use pypy3, others python3.6, others python3.7. do NOT hard-code the python executable name into Makefiles / scripts, use $(PYTHON3) as an optional env-var (PYTHON3 ?= "python3")
  • unit tests (python setup.py test) always to be developed extensively (synergistically) at time of code writing, NOT as an afterthought.
  • do not use import * !
  • modules to be kept very small, such that "yosys show" on reading verilog produces a small, legible diagram
  • module header to actually explain what the module does. link to requirements spec, and any other useful stuff.
  • ascii art recommended in module header to illustrate where bits go.
  • class header likewise required and explain purpose of the class.
  • code comments to be useful but not excessive to the point of drowning the code
  • functions not to exceed 60-70 (or so) lines, if possible. if too big, split into multiple functions (remember, nmigen constructs can be returned from a function)

Git commits

  • commits to be SMALL (5 - 15 lines max) and MUST not disrupt existing unit tests. unit tests always to be run prior to commit.
  • commits MUST be SINGLE PURPOSE. clue (red flag) is if the commit message includes the word "and".
  • commit message to explain purpose (ie not be "changed this" or "added that"). if rollback is ever needed (possibly even months later), the commit log is only useful to find that one commit if the commit message is useful.
  • large commits ok as long as they are additions rather than modifications. examples: a completely new class that is not in use anywhere, or a new unit test.
  • whitespace to be separate, commit msg "autopep8 cleanup" or "whitespace cleanup" is sufficient.
  • when using bugtracker, include link to bugreport in commit message. Cross ref commit id to bugreport.
  • large refactoring (e.g. renaming functions) needs to be atomic and single-purpose as best as possible. unit tests still need to pass, post-refactor.

Which files should be added to the repository

Only source files must be added to the repository.

Output that is created from another command must not, with very very few exceptions, be added to the repository. The reason is simple: each time a source file is modified, the auto-generated (compiled) output also changes. If those changes are added to the repository, they become confused with the source code (a git diff will show both the source and changes to the auto-generated output). If they are not added to the repository, the source and its auto-generated output become out-of-sync.

Either way is bad.

Instead, the following is advised:

  • add the source code only
  • create a script or use a command that builds the source code, generating the output
  • do NOT add the output to the repository
  • add the script or command to the Makefile
  • list the command as a "build dependency" in the documentation

As a convenience and a courtesy, consider creating "release tarballs" (also adding the means to create them to the Makefile) so that people who for one reason or another cannot get or install the build dependencies may at least get the end-result of the work. However this should be done as a low priority, or if there are financial offers of sponsorship or other incentives received or to be gained by doing so.