From: lkcl <lkcl@web>
Date: Sat, 15 May 2021 11:05:37 +0000 (+0100)
Subject: (no commit message)
X-Git-Tag: DRAFT_SVP64_0_1~917
X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=36d2c68549b067bbe04567b364a25b9c9b3c69fc;p=libreriscv.git

---

diff --git a/HDL_workflow.mdwn b/HDL_workflow.mdwn
index 35a9199c7..d2dfa6b50 100644
--- a/HDL_workflow.mdwn
+++ b/HDL_workflow.mdwn
@@ -669,7 +669,8 @@ for actual code development
 
 * commit often. several times a day, and "git push" it.  this is
   collaboration. if something is left even overnight uncommitted and not
-  pushed so that other people can see it, it is a red flag.  if you find
+  pushed so that other people can see it, it is a red flag.
+* if you find
   yourself thinking "i'll commit it when it's finished" or "i don't want to
   commit something that people might criticise" *this is not collaboration*,
   it is making yourself a bottleneck.  pair-programming is supposed to help
@@ -682,6 +683,16 @@ This is important.  "`git pull`" will merge in changes.  If you then
 arbitrarily save a file without re-loading it, you risk destroying
 other people's work.
 
+You can avoid damaging the repositories by following some simple procedures:
+
+    run appropriate unit tests
+    git pull
+    run appropriate unit tests again (checks other people's work)
+    git diff    # and actually read and review the output
+    git status  # check for any missing files
+    git commit  # with appropriate arguments and message
+    git push    # always always always do this
+
 ### Absolutely no auto-generated output
 
 * **do not commit autogenerated output**. write a shell script and commit
@@ -689,10 +700,13 @@ other people's work.
   **do not** add the actual output of **any** command to the repository.
   ever.  this is really important.  even if it is a human-readable file
   rather than a binary object file.
-  it is very common to add pdfs (the result of running `latex2pdf`) or
+* it is very common to add PDFs (the result of running `latex2pdf`) or
   configure.in (the result of running `automake`), they are an absolute
   nuisance and interfere hugely with git diffs, as well as waste hard
   disk space *and* network bandwidth. don't do it.
+* do not add multi-megabyte or multi-gigabyte "test data".
+  use shell scripts and commit that, which automatically downloads the
+  "test data" from a well-known known-good reliable location instead.
 
 ### Write commands that do tasks and commit those