## 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.
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 [[HDL_workflow#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,
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