add video link for FU-FU Dep Matrix

[libreriscv.git] / 3d_gpu / devnotes.mdwn

diff --git a/3d_gpu/devnotes.mdwn b/3d_gpu/devnotes.mdwn
index 0814cbdf01a618d1d3f3aa162f611b037540e4c1..97cfbc3d114ea1716ec99812557150093f4748fb 100644 (file)
--- a/3d_gpu/devnotes.mdwn
+++ b/3d_gpu/devnotes.mdwn
@@ -2,8 +2,12 @@
 
 * 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 * !
@@ -25,11 +29,48 @@
   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
   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.
+