Bug 1126 - How to document new bugs/issues
Summary: How to document new bugs/issues
Alias: None
Product: Libre-SOC's first SoC
Classification: Unclassified
Component: Documentation (show other bugs)
Version: unspecified
Hardware: PC Linux
: --- enhancement
Assignee: shriya.sharma
URL: https://libre-soc.org/HDL_workflow/
Depends on:
Blocks: 961
  Show dependency treegraph
Reported: 2023-08-01 11:53 BST by Andrey Miroshnikov
Modified: 2023-09-22 23:00 BST (History)
6 users (show)

See Also:
NLnet milestone: ---
total budget (EUR) for completion of task and all subtasks: 0
budget (EUR) for this task, excluding subtasks' budget: 0
parent task for budget allocation:
child tasks for budget allocation:
The table of payments (in EUR) for this task; TOML format:


Note You need to log in before you can comment on or make changes to this bug.
Description Andrey Miroshnikov 2023-08-01 11:53:23 BST
This bug is for demonstrating a good way to raise issues discovered within the Libre-SOC project (code, hardware, documentation, etc.).

Started the wiki page section is called "How to raise issues" (2.2.1) and can be found here:
Comment 1 Andrey Miroshnikov 2023-08-01 11:56:25 BST
Forgot to include my commit on the wiki repo:
Comment 2 Luke Kenneth Casson Leighton 2023-08-01 14:17:07 BST
(In reply to Andrey Miroshnikov from comment #0)

> Started the wiki page section is called "How to raise issues" (2.2.1) 

"how" does not emphasise "why", and it is the WHY that stops resentment
at being "forced" to "waste time" on "stupid project management"

that alone is important enough to have its own section... *and then*
under that have the "actions" (the "how"s)

can you both now have a conversation on IRC
(placing links back here as you do so) recounting
your recollection of what i said on the conf. call
today?  it may take some time, it may take only minutes,
but whatever happens you will see *and experience* the
very issues that then need themselves to be documented.
Comment 3 Luke Kenneth Casson Leighton 2023-08-01 14:27:30 BST
i have added some additional advice especially "why"

you (one of you) need to coordinate amongst yourselves to decide
who s going to document *this* practice.

see what jacob did here:

it is not perfect but pretty good, i much prefer the links to
the diffs as it is quicker and easier to review.
Comment 4 Andrey Miroshnikov 2023-08-02 21:32:37 BST
After group call, Luke made useful comments on including milestones and budget information, so I included a few extra points in HDL_workflow.

See commit diff: https://git.libre-soc.org/?p=libreriscv.git;a=commitdiff;h=fccae2f02cb75bf5658bd1ae983f530df630f51c
Comment 5 Luke Kenneth Casson Leighton 2023-08-14 08:34:59 BST
andrey shriya: https://bugs.libre-soc.org/show_bug.cgi?id=1139#c5
needs to be in the "why" and then in the "how/what"
Comment 6 Luke Kenneth Casson Leighton 2023-08-15 00:09:57 BST
andrey, shriya: more to be added to the "why and how"


yes this is the process that i have been following for five years.
i expect everyone to know it, know *why* it exists, and follow it
strictly because the damage done, time wasted and jeapordy to the
project by failing to meet its unwritten obligations to NLnet,
is otherwise unacceptable.
Comment 7 Andrey Miroshnikov 2023-08-15 21:36:54 BST
(In reply to Luke Kenneth Casson Leighton from comment #5)
> needs to be in the "why" and then in the "how/what"

(In reply to Luke Kenneth Casson Leighton from comment #6)
> andrey, shriya: more to be added to the "why and how"

Added a few more lines based on your conversations:

Forgot about the two sections, so I moved the 'why' sentences to their respective place:
Comment 8 Luke Kenneth Casson Leighton 2023-08-17 06:08:04 BST
andrey, ths also needs adding, "how to do budget estimation"

it involves guestimating +/- 40% a number of days where "number"
is less than appx 8, but no smaller than 1/2 a day,
and the total subtasks so estimated is appx 5-25.
if greater than 8 days it is REQUIRED to break it into
smaller subtasks.

statistically speaking the +/- 40% variance when added up
over 20+ tasks gives a time estimate that is accurate to +/- 10%.

... but you have to actually have a fricking clue and a clear
idea of what is actually needed, and NOT leave anything out.
forget to add say "do the documentation" to the list of tasks
to be estimated for funding and you just screwed the project by
failing to put in the Grant Request to cover 80% more work than
there is available money.
or your project just has no documentation and is worthless due to
noone being able to maintain it in future.
Comment 9 Luke Kenneth Casson Leighton 2023-08-23 08:59:08 BST
also the following need adding to the HDL_workflow along with

* Liskov Substitution Principle
* Principle of Least Surprise

Comment 10 Luke Kenneth Casson Leighton 2023-08-25 11:00:41 BST
always put "bug #NNN" not "#NNN".  add the insight about saving time
and making things easier to track in order to focus on accelerating

slogging through bugs forcing developers to type "NNN" into the bug/search
field (if they even know about that), rather than just clicking on a link?
this is hostile to forward progress, and aggravating.

Comment 11 Luke Kenneth Casson Leighton 2023-09-02 08:40:08 BST
also need to be aware of the level of inter-dependencies, the specification
being *the* absolute top priority for maintaining as "100% up-to-date",
followed by a cascade of inter-dependent bugreports that trickle down from
that to cover the CSV files, insndb, ISACaller, binutils, and then to
TestIssuer which has its own set of dependencies especially if a new
regfile or SPR is added.

Comment 12 Luke Kenneth Casson Leighton 2023-09-03 08:24:53 BST
"do not attempt to re-use bugs" section needed. rationale here:
Comment 13 Luke Kenneth Casson Leighton 2023-09-14 07:58:34 BST
all code MUST have copyright notices license headers and an NLnet
grant and EU ref number

extremely important.
Comment 14 Luke Kenneth Casson Leighton 2023-09-19 18:00:00 BST
Also link #1164 into HDL_workflow and into the main front page in
order to make it easy for people to find examples of other people
going through onboarding, and also to find a template for the same.
Comment 15 Luke Kenneth Casson Leighton 2023-09-20 14:12:57 BST
another necessary task, highlighted from bug #1171:
whenever new sub-tasks are added which have a sub-budget
assigned from an existing Milestone, it is necessary to:

* notify Michiel and the relevant NNNN-NN@nlnet.nl team of
  advance notice of intent to add new sub-tasks, cc'ing bob
  - confirm with them that this is NOT a change in the AGREED
    MILESTONE BUDGETs, because it is just sub-task allocation.
  - confirm that they are happy to add the sub-tasks to the MoU
    (this needs approval of bob goudriaan)
* *re-generate* the JSON file
* make a DIFF against the *PREVIOUS* JSON file
* create a MANUAL report/summary of "changes" that
  NLnet may easily action
  - "add the following task X to parent Y of amount W",
  - and if any: "change parent Z available amount to V as a WRAPUP")
  (this latter is because occasionally there are subtasks NOT
   totalling the full parent amount, usually because a summary
   report is needed. Michiel and I privately agreed to call
   this "wrapup")
* obtain a confirmation that this has been actioned
* DOUBLE-CHECK that the RFP database correctly matches the new
  bugzilla status.


1. to make a change to the actual budgetary amounts of the
   Grant Milestones, without written authorization from Bob
   and Michiel. a DIFFERENT PROCEDURE is needed.
   this is because NLnet had to go through a 3rd party Verification
   Process with the European Union: changing the amounts without
   consent is therefore tantamount to fraud.

2. if there has been an RFP already submitted under a given Milestone,
   it becomes NO LONGER POSSIBLE to change the JSON file in NLnet's
   system because it is too complex.

   there is one Grant in this complex situation: bug #690, the crypto
   grant.  it is made much more complex because it *pre-dates* NLnet's
   current RFP system, where RFPs were submitted by EMAIL and there
   are manual records not fully integrated into the database.

also note: as the addition of sub-tasks *requires a change to the MOU*
it should NOT be taken lightly, i.e. should not be arbitrarily done
one by one, but only in "batches".

considerable care therefore has to be taken to ensure that NLnet are
not overloaded, nor that the EU Auditor is given grounds to become
"suspicious" because of a dozen or more alterations to the MOU.
Comment 16 Andrey Miroshnikov 2023-09-22 10:17:19 BST
Created a new page which will be used to document points covered under this bug:


I will be gradually adding bits over the course of today.
Comment 17 Andrey Miroshnikov 2023-09-22 10:25:01 BST
(In reply to Andrey Miroshnikov from comment #16)
> Created a new page which will be used to document points covered under this
> bug:
> https://libre-soc.org/libresoc_bug_process/

(In reply to Luke Kenneth Casson Leighton from comment #15)
> another necessary task, highlighted from bug #1171:
> whenever new sub-tasks are added which have a sub-budget
> assigned from an existing Milestone, it is necessary to:

Added information from your comment Luke:

Jacob please have a good read over it to familiarise yourself (I need to do so too, as well as the rest of team).
Comment 18 Luke Kenneth Casson Leighton 2023-09-22 10:28:51 BST
(In reply to Andrey Miroshnikov from comment #16)
> Created a new page which will be used to document points covered under this
> bug:
> https://libre-soc.org/libresoc_bug_process/

it goes under HDL_workflow
Comment 19 Luke Kenneth Casson Leighton 2023-09-22 10:32:31 BST
(In reply to Luke Kenneth Casson Leighton from comment #18)

> it goes under HDL_workflow


done. TODO: link in a section in HDL_workflow
Comment 20 Jacob Lifshay 2023-09-22 17:29:27 BST
luke asked to post the "i'm thinking of doing ..." procedure:
Comment 21 Luke Kenneth Casson Leighton 2023-09-22 23:00:35 BST
(In reply to Jacob Lifshay from comment #20)
> luke asked to post the "i'm thinking of doing ..." procedure:
> https://lists.libre-soc.org/pipermail/libre-soc-dev/2023-September/005678.
> html

i meant, "track down the email from last week"
and track down the mailing list posts on the
same topic (when i first sent them, nearly a year
ago), and explicitly post the copy here so that it can
be put into the wiki.

i am not going to repeat it or write it out again for the
seventh time in one year 

*your* responsibility is to listen the first time.