## 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.
proprietary nonfree service "because it's soooo convenient", as the
lions are getting wind and gout from overfeeding on that one.
-### How to raise issues
-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.
-
-1. Create a bug report.
-2. CC in Luke (or other relevant member of Libre-SOC).
-3. Ping on IRC to say a bug has been created.
+one.
## ikiwiki
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
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
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
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
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".
projects / libreriscv.git / blobdiff