From: Andrey Miroshnikov Date: Mon, 13 Nov 2023 20:32:53 +0000 (+0000) Subject: Add section on procedure X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=09d4356bdc5775c5e136b2760a584a159efb7aaf;p=libreriscv.git Add section on procedure --- diff --git a/HDL_workflow/libresoc_bug_process.mdwn b/HDL_workflow/libresoc_bug_process.mdwn index 336fdc216..67adca24e 100644 --- a/HDL_workflow/libresoc_bug_process.mdwn +++ b/HDL_workflow/libresoc_bug_process.mdwn @@ -157,3 +157,92 @@ the code in question, it makes it difficult to come back to the code Don't forget to ask fellow project for help, they might be able to help determine the scope of the work involved. +# "I'm thinking of doing... procedure" + +## Preamble + +Given the scale of this project and the critical reliance on certain parts +of it (such as devscripts, ISA csv files, ISACaller, etc.) on the work done +by the team, it is extremely important to raise any proposed changes and/or +improvements, and to wait for feedback _before_ implementing said changes. + +Going forward, we all need to keep this in mind when working on +critical parts of the codebase. + +To make good use of available time and budget, the LibreSOC team should +focus on: + +1. Completing tasks under grant budget +2. Make small, incremental changes which keep the overall codebase functional. +3. When coming up with fixes or improvements which are intrusive to the + _current_ workflow (which may slow the team down from completing tasks + under grant budget), assign them to 'Future' milestone for grant + applications going forward. + +Why these three points? + +1. Work that cannot be related to grant sub-tasks (even if indirectly, by + bringing us closer to eventual completion), should be put aside _until + future funding is secured/confirmed_. +2. Small changes make it easier and quicker to find mistakes. That's one of + the reasons Luke has specified on [[/HDL_workflow]] to stick to small + commits. *(Andrey: I need to improve on this myself)* +3. Big changes are inherently risky. When LibreSOC was just a few people + (Luke and Jacob), it was easier to keep track of each other's progress. + 5 years down the line, the situation has changed. + Keep in mind that changes to critical parts (whether big or small) will + now affect at minimum Luke, Dmitry, Jacob, Sadoon, myself + (perhaps also Cesar and Konstantinos, and so on). + By going through the process of documenting a change in a new bug report, + not only there's an opportunity to take a pause and think about + repercussions, it also adds to the list of work for future grant + applications (which will make it easier to draft focussed grants with + realistic timescales and budget). + +## Procedure + +- If you discover a problem in code, raise a bug report, and use a +corresponding 'importance' setting depending on how serious you perceive the +issue to be. This will start a _discussion_. + +**No work is to be started yet.** + +- Based on generated discussion, determine if the issue is a *blocker to +current tasks under budget*. If it is a blocker , then the task 'importance' +to be set to 'major' or 'critical (or 'blocker'). +*Andrey: need to clarify this* +If possible, a budget may be assigned after discussion and confirmation with +Luke and Andrey (depends on remaining budget/tasks). + +- If the issue is *not a blocker*, but useful in future work, then the +'Future' milestone is to be assigned. The issue will be evaluated at a later +stage. At this point, no further time should be spent on this issue +(to prioritise outstanding tasks). + +*(Andrey): Sometimes determining whether to use WONTFIX or INVALID is +difficult. Perhaps more examples would help?* + +- If the issue is not a blocker, and the discussion shows that it is not +an issue at all, it is to be set to either of the following: + - `RESOLVED DUPLICATE` - If the issue raised already exists. + [Example, bug #962](https://bugs.libre-soc.org/show_bug.cgi?id=962) + - `RESOLVED WONTFIX` - If the issue requires too much time or budget. + [Example, bug #921](https://bugs.libre-soc.org/show_bug.cgi?id=921) + - `RESOLVED INVALID` - If the issue does not align with project goals or + methodology. + [Example, bug #76](https://bugs.libre-soc.org/show_bug.cgi?id=76) +- The final status will be confirmed after *at least two other people* (other + than the reporter) look at the bug report. + For cases considered to be `WONTFIX` or `INVALID`, 48h should be given + before the bug report is closed. This ensures the team has enough time to + see the discussion before the issue disappears. + +- Once the issue has been discussed and determined to be critical to current +grant sub-task/s, and budget considered, _then_ work can proceed in a separate +branch. Only after fixes have been confirmed to keep the CI tests passing, +can they be rebased (to keep commit history) into the master branch. + +This procedure adds a time delay between the issue discovery and +start of work. This is important however because it allows for team members +to read bug updates without being overwhelmed and have time to add input. +