* 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 * !
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")
+* 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.
-* whitespace to be separate, "autopep8 cleanup" is sufficient.
+ 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