+* firstly, we will not be doing a full automated layout-and-hope
+ using alliance/coriolis2, we will be doing leaf-node thru tree node
+ half-automated half-manual layout, finally getting to the floorplan,
+ then revising and iteratively adjusting.
+* secondly, examining modules at the gate level (or close to it) is just
+ good practice. poor design creeps in by *not* knowing what the tools
+ are actually doing (word to experienced developers: yes, we know that
+ the yosys graph != final netlist).
+* thirdly, unit testing, particularly formal proofs, is far easier on
+ small sections of code, and complete in a reasonable time.
+
+## Special warning / alert to vim users!
+
+Some time around the beginning of 2019 some bright spark decided that
+an "auto-recommend-completion-of-stuff" option would be a nice, shiny
+idea to enable by default from that point onwards.
+
+This incredibly annoying "feature" results in tabs (or spaces) being
+inserted "on your behalf" when you press return on one line, for your
+"convenience" of not needing to type lots of spaces/tabs just to get
+to the same indentation level.
+
+Of course, this "feature", if you press return on one line in edit
+mode and then press "escape", leaves a bundle-of-joy extraneous
+whitespace **exactly** where you don't want it, and didn't ask for it,
+pooped all over your file.
+
+Therefore, *please*: **before** running "git commit", get into the
+habit of always running "git diff", and at the very minimum
+speed-skim the entire diff, looking for tell-tale "red squares"
+(these show up under bash diff colour-syntax-highlighting) that
+inform you that, without your knowledge or consent, vim has
+"helpfully" inserted extraneous whitespace.
+
+Remove them **before** git committing because they are not part
+of the actual desired code-modifications, and committing them
+is a major and constant distraction for reviewers about actual
+important things like "the code that actually *usefully* was
+modified for that commit"
+
+This has the useful side-effect of ensuring that, right before
+the commit, you've got the actual diff right in front of you
+in the xterm window, on which you can base the "commit message".
+
+## Unit tests
+
+For further reading, see the wikipedia page on
+[Test-driven Development](https://en.wikipedia.org/wiki/Test-driven_development)
+
+This deserves its own special section. It is extremely important to
+appreciate that without unit tests, python projects are simply unviable.
+Python itself has over 25,000 individual tests.
+
+This can be quite overwhelming to a beginner developer, especially one
+used to writing scripts of only 100 lines in length.
+
+Thanks to Samuel Falvo we learned that writing unit tests as a formal
+proof is not only shorter, it's also far more readable and also, if
+written properly, provides 100% coverage of corner-cases that would
+otherwise be overlooked or require tens to hundreds of thousands of
+tests to be run.
+
+No this is not a joke or even remotely hypothetical, this is an actual
+real-world problem.
+
+The ieee754fpu requires several hundreds of thousands of tests to be
+run (currently needing several days to run them all), and even then we
+cannot be absolutely certain that all possible combinations of input have
+been tested. With 2^128 permutations to try with 2 64 bit FP numbers
+it is simply impossible to even try.
+
+This is where formal proofs come into play.
+
+Samuel illustrated to us that "ordinary" unit tests can then be written
+to *augment* the formal ones, serving the purpose of illustrating how
+to use the module, more than anything.
+
+However it is appreciated that writing formal proofs is a bit of a
+black art. This is where team collaboration particularly kicks in,
+so if you need help, ask on the mailing list.
+
+## Don't comment out unit tests: add them first (as failures) and fix code later
+
+Unit tests serve an additional critical purpose of keeping track of code
+that needs to be written. In many cases, you write the unit test *first*,
+despite knowing full well that the code doesn't even exist or is completely
+broken. The unit test then serves as a constant and important reminder
+to actually fix (or write) the code.
+
+Therefore, *do not* comment out unit tests just because they "don't work".
+If you absolutely must stop a unit test from running, **do not delete it**.
+Simply mark it with an appropriate
+["skip" decorator](https://docs.python.org/3/library/unittest.html#skipping-tests-and-expected-failures),
+preferably with a link to a URL in the [bugtracker](https://bugs.libre-soc.org/)
+with further details as to why the unit test should not be run.