X-Git-Url: https://git.libre-soc.org/?a=blobdiff_plain;f=HDL_workflow.mdwn;h=7a1ee18c40b27172dcf5a11c2262b3bd16979257;hb=eb93d93bb6fa4f31f71816f06473a6589c0bb7c5;hp=38bd6f0f619b6d7262e1f1b60c77ac5c19bbe453;hpb=b1049bd2d9041bcbe517235523e091d21f921132;p=libreriscv.git diff --git a/HDL_workflow.mdwn b/HDL_workflow.mdwn index 38bd6f0f6..7a1ee18c4 100644 --- a/HDL_workflow.mdwn +++ b/HDL_workflow.mdwn @@ -126,6 +126,8 @@ send this to Spam" option. ## Bugtracker +* **LibreSOC bug/task process**: [[libresoc_bug_process]] + bugzilla. old and highly effective. sign up in the usual way. any problems, ask on the list. @@ -135,27 +137,6 @@ lions are getting wind and gout from overfeeding on that one. one. -### Why raise issues - -* [Bug #1126](https://bugs.libre-soc.org/show_bug.cgi?id=1126) - -If you have discovered a problem in Libre-SOC (software, hardware, etc.), -please raise a bug report! -Bug reports allow tracking of issues, both to make the developers lives easier, -as well as for tracking completed grant-funded work. - -####How to raise issues - -1. Create a bug report. -2. Add in any links from the mailing list or IRC logs to the bug report for back tracking - (this is mandatory). Also fill in the URL field if there is a relevant wiki page. -3. CC in relevant team members -4. make absolutely sure to fill in "blocks", "depends on" or "see also" so that the - bug is not isolated (otherwise bugs are too hard to find if isolated from everything else) -5. Ping on IRC to say a bug has been created -6. Unless you know exactly which milestone to use, leave blank initially. This also applies when editing milestone, budget parent/child, toml fields. See section [[WikiLink#Task management guidelines]] further down. -7. After setting the milestone, it is **absolutely required** to run [budget-sync](https://git.libre-soc.org/?p=utils.git;a=blob;f=README.txt;hb=HEAD), as it will point out any discrepancies. The budget allocations will be used for accounting purposes and **MUST** be correct. *Note you can only get paid for stuff done **after the nlnet grant is approved** (before the MOU is signed)* - ## ikiwiki Runs the main libre-soc.org site (including this page). effective, @@ -363,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 @@ -436,6 +418,7 @@ In the meantime, sfpy can be built as follows: git clone --recursive https://github.com/billzorn/sfpy.git cd sfpy + git apply /path/to/ieee754fpu/sfpy.patch cd SoftPosit git apply ../softposit_sfpy_build.patch git apply /path/to/ieee754fpu/SoftPosit.patch @@ -775,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 @@ -882,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 @@ -1181,8 +1237,78 @@ Simply mark it with an appropriate 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. +## Liskov Substitution Principle + +* [Wikipedia entry](https://en.wikipedia.org/wiki/Liskov_substitution_principle) +* [Stackoverflow answer on LSP](https://stackoverflow.com/questions/56860/what-is-an-example-of-the-liskov-substitution-principle) +* [Article on LSP](https://reflectoring.io/lsp-explained/) + +Copying from Wikipedia: + +``` +The Liskov substitution principle (LSP) is a particular definition of a +subtyping relation, called strong behavioral subtyping, that was initially +introduced by Barbara Liskov in a 1987 conference keynote address titled +Data abstraction and hierarchy. It is based on the concept of +"substitutability" - a principle in object-oriented programming stating +that an object (such as a class) may be replaced by a sub-object (such as +a class that extends the first class) without breaking the program. +It is a semantic rather than merely syntactic relation, because it intends +to guarantee semantic interoperability of types in a hierarchy, object +types in particular. +``` + +To paraphrase: an *original object/class may be replaced with another object* +(whose class extends the first class) *without breaking* the program. + +Python is a programming language which makes using LSP pretty straightforward. + +In LibreSOC, we aim to follow this principle whenever possible and (bearing +time and budget constraints). + +*(Luke, please include some examples from LibreSOC source here)* + +## Principle of Least Astonishment/Surprise (POLA) + +* Example shown by Luke on +[comment #33 bug #1039](https://bugs.libre-soc.org/show_bug.cgi?id=1039#c33) +* [Wikipedia entry](https://en.wikipedia.org/wiki/Principle_of_least_astonishment) +* Example answer on +[software eng. stack exchange](https://softwareengineering.stackexchange.com/questions/187457/what-is-the-principle-of-least-astonishment) + +Wikipedia mentions that the origin of the term "Principle of Least +Astonishment" (or Surprise) comes from a PL/I programming language bulletin +board from 1957: + +``` +For those parts of the system which cannot be adjusted to the peculiarities +of the user, the designers of a systems programming language should obey +the "Law of Least Astonishment." In short, this law states that every construct +in the system should behave exactly as its syntax suggests. Widely accepted +conventions should be followed whenever possible, and exceptions to previously +established rules of the language should be minimal. +``` + +If a method name has a prefix `test_` it should be a unit test (or some other +test which is there to check the functionality of a given feature). + +A method/function (or attributes/variables, etc.) *shouldn't* be given a name +which is wildly different from the what the user would expect it to do. + +*Andrey*: One example which may meet this rule is `TestIssuer`, +which is the FSM-based nMigen HDL CPU core used by LibreSOC (so far). +It is so called because it is used to issue unit tests (while also +being synthesisable). This name was however was initially confusing +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".