bug 1244: separate frame for linked list image

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

diff --git a/3d_gpu/devnotes.mdwn b/3d_gpu/devnotes.mdwn
index 96214deae2c603126edbb646b882ae24169ecb67..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,9 +29,14 @@
   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
@@ -42,16 +51,18 @@ 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.
-If they are **not** added to the repository, the source and its
-auto-generated output become out-of-sync.
+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*
-* add a script or command that builds the source code, generating the output
+* 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
@@ -60,6 +71,6 @@ 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 sponsorhip
+done as a low priority, or if there are financial offers of sponsorship
 or other incentives received or to be gained by doing so.