(no commit message)

[libreriscv.git] / HDL_workflow.mdwn

diff --git a/HDL_workflow.mdwn b/HDL_workflow.mdwn
index ab97903b2101c7751115045d685db08b4fd8bfe1..9d7fb9ac1ff8dc4ced9d3a597178451cb2c1743a 100644 (file)
--- a/HDL_workflow.mdwn
+++ b/HDL_workflow.mdwn
@@ -243,6 +243,13 @@ including its 80 character limit.  In short: not everyone has the same
 "modern" GUI workflow or has access to the same computing resources as
 you, so please do respect that.
 
+More on this concept is
+[here](https://www.linuxjournal.com/content/line-length-limits).
+Note *very pointedly* that Linus Torvalds *specifically* states that
+he does not want Linux kernel development to become the exclusive
+domain of the "wealthy".  That means **no** to assumptions about
+access to ultra-high resolution screens.
+
 # Software prerequisites
 
 Whilst many resources online advocate "sudo" in front of all root-level
@@ -305,7 +312,7 @@ nmigen may be installed as follows:
 
 * mkdir ~/src
 * cd !$
-* git clone https://github.com/m-labs/nmigen.git
+* git clone https://github.com/nmigen/nmigen.git
 * cd nmigen
 * sudo bash
 * python3 setup.py develop
@@ -316,7 +323,7 @@ testing can then be carried out with "python3 setup.py test"
 ## Softfloat and sfpy
 
 These are a test suite dependency for the ieee754fpu library, and
-will be changed in the future to use Jacob's algorithmic numeric
+will be changed in the future to use Jacob's [simple-soft-float](https://crates.io/crates/simple-soft-float)
 library.  In the meantime, sfpy can be built as follows:
 
     git clone --recursive https://github.com/billzorn/sfpy.git
@@ -575,7 +582,7 @@ and follow up the next day *after* running the full relevant unit tests.
 
 ### Why such strict rules?
 
-the reason for all the above is because python is a weakly typed language.
+the reason for all the above is because python is a dynamically typed language.
 make one tiny change at the base level of the class hierarchy and the
 effect may be disastrous.
 
@@ -765,6 +772,21 @@ 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](http://bugs.libre-riscv.org)
+with further details as to why the unit test should not be run.
+
 # TODO Tutorials
 
 Find appropriate tutorials for nmigen and yosys, as well as symbiyosys.