mention page number of vgbbd

[libreriscv.git] / HDL_workflow.mdwn

diff --git a/HDL_workflow.mdwn b/HDL_workflow.mdwn
index 0d42fe402992181e34983ad97bc6e5e394d965c2..7a1ee18c40b27172dcf5a11c2262b3bd16979257 100644 (file)
--- a/HDL_workflow.mdwn
+++ b/HDL_workflow.mdwn
@@ -344,9 +344,10 @@ and that people communicate and coordinate with each other.
 This is not a hard rule: under special cirmstances branches can be useful.
 They should not however be considered "routine".
 
-For advice on commit messages see
-[here](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html),
-and [here](https://github.com/torvalds/subsurface-for-dirk/blob/master/README.md#contributing)).
+For guidance on when branches are appropriate,
+see [[HDL_workflow/libresoc_bug_process]].
+
+For advice on commit messages see the Coding section further down on this page.
 
 ## yosys
 
@@ -757,6 +758,35 @@ out punishment".
 
 for actual code development
 
+### Copyright Notices
+
+**All code must have copyright and grant notices (where work was done
+under budget).**
+
+* [Example from soc.git repo](https://git.libre-soc.org/?p=soc.git;a=blob;f=src/soc/fu/div/experiment/goldschmidt_div_sqrt.py;h=3f7c2480742d6913859461da120099385f99d18a;hb=HEAD)
+
+Breakdown of the header in the above example:
+
+- Code was worked on by Jacob Lifshay during 2022.
+- Work was done under LibreSOC's Crypto Router
+[grant](https://libre-soc.org/nlnet_2021_crypto_router/) submitted to NLnet.
+NLnet grant code is `2021-02-052`.
+- The NLnet grant was under the
+[NLnet Assure fund](https://nlnet.nl/assure).
+- Financial support for NGI Assure comes from European Commission's
+[Next Generation Internet](https://ngi.eu/) Programme,
+grant agreement no. 957073.
+
+Template:
+
+```
+# SPDX-License-Identifier: LGPL-3-or-later
+# Copyright 202X [Name] [email]
+#
+# Funded by NLnet [Programme Name] Programme [202X-YY-ZZZ], [NLnet URL] part
+# of [EU Programme Name] 202X EU Programme [Programme Number].
+```
+
 ### Plan unit tests
 
 * plan in advance to write not just code but a full test suite for
@@ -864,6 +894,50 @@ You can avoid damaging the repositories by following some simple procedures:
   that the commit has not been properly broken down into separate-purpose
   commits. ask for advice on-list on how to proceed.
 
+### *Git commit message format*
+
+* Additional articles on commit messages
+[here](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
+and
+[here](https://github.com/torvalds/subsurface-for-dirk/blob/master/README.md#contributing)
+
+LibreSOC message format based on description given in
+[bug #1126#c40](https://bugs.libre-soc.org/show_bug.cgi?id=1126#c40):
+
+1. Every commit MUST start with a short title, up to 50 characters.
+2. The commit title MUST contain either subsystem, or a file path,
+or a subsystem/path, or a subsystem/subsubsystem combination, which got
+modified or introduced, and a short summary. These parts must be separated
+by the colon.
+3. A good rule is to imagine that the short message begins with
+"if this patch is applied, it will". For example, a good title is
+"X: update Y", not "updated Y in X".
+4. After the title, there must be an empty line, which documents the
+changes. The limit is 72 characters per line.
+5. The long description can be omitted if the short description provides
+enough information or if the commit itself is simple enough.
+
+Example:
+
+```
+subsystem/file.py: document usage
+
+Here goes the long description, which explains everything. First of all,
+we stick to limit of 72 characters. Then, perhaps, we'd like to explain
+the rationale in more details.
+```
+
+It is suggested to stick to common sense whenever choosing subsystem names
+or files or long descriptions.
+
+Primary concerns are:
+
+1. short titles
+2. short summaries
+3. wording for the first line
+
+The rest is up for the committers.
+
 ### Exceptions to small commit: atomic single purpose commit
 
 * if it is essential to commit large amounts of code, ensure that it
@@ -1230,6 +1304,11 @@ to me, because my background is in hardware not software engineering.
 
 # Task management guidelines
 
+* New guide for RfP submission (in-progress):
+[[HDL_workflow/rfp_submission_guide]]
+
+(This section needs to be compared with [[HDL_workflow/libresoc_bug_process]])
+
 1. Create the task in appropriate "Product" section with appropriate
   "Component" section. Most code tasks generally use "Libre-SOC's
   first SOC".