HDL_workflow/libresoc_bug_process.mdwn

   1 # LibreSOC Bug Process
   2
   3 * [Bug #1126](https://bugs.libre-soc.org/show_bug.cgi?id=1126)
   4
   5 * HDL workflow guide page: [[HDL_workflow]]
   6
   7 This page describes in detail how to raise new tasks (bugs) and how to approach
   8 development within the project in order to get appropriate amount of funding
   9 for the tasks completed.
  10
  11 # Why raise issues
  12
  13 * [Bug #1126](https://bugs.libre-soc.org/show_bug.cgi?id=1126)
  14
  15 If you have discovered a problem in Libre-SOC (software, hardware, etc.),
  16 please raise a bug report!
  17 Bug reports allow tracking of issues, both to make the developers lives easier,
  18 as well as for tracking completed grant-funded work.
  19
  20 It is **extremely** important to link the new bug to previous ones. As Luke
  21 mentioned on [this bug](https://bugs.libre-soc.org/show_bug.cgi?id=1139#c3),
  22 "it is a mandatory project requirement that the graph from any bug
  23 contain all other bugs (one "Group")".
  24
  25 The primary reason for this is to ensure bugs don't get buried and lost,
  26 and will aid those tackling similar problems at a later time.
  27
  28 Also, for project management and financing purposes, it helps developers
  29 to keep an up-to-date list of their tasks.
  30
  31 ##How to raise issues
  32
  33 1. Create a bug report.
  34 2. Add in any links from the mailing list or IRC logs to the bug report for
  35 back tracking (this is mandatory). Also fill in the URL field if there is a
  36 relevant wiki page.
  37 3. CC in relevant team members
  38 4. Make absolutely sure to fill in "blocks", "depends on" or "see also" so
  39 that the bug is not isolated (otherwise bugs are too hard to find if isolated
  40 from everything else)
  41 5. Ping on IRC to say a bug has been created
  42 6. Unless you know exactly which milestone to use, leave blank initially. This
  43 also applies when editing milestone, budget parent/child, toml fields. See
  44 section [[HDL_workflow#Task management guidelines]] further down.
  45 7. After setting the milestone, it is **absolutely required** to run
  46 [budget-sync](https://git.libre-soc.org/?p=utils.git;a=blob;f=README.txt;hb=HEAD),
  47 as it will point out any discrepancies. The budget allocations will be used for
  48 accounting purposes and **MUST** be correct. *Note you can only get paid for
  49 stuff done **after the nlnet grant is approved** (before the MOU is signed)*
  50
  51 If a developer ever needs to check which bugs are assigned to them, go to the
  52 Libre-SOC bug tracker
  53 [advanced search page](https://bugs.libre-soc.org/query.cgi?format=advanced),
  54 and in the "Search by People" section, check "Bug Assignee" and "contains"
  55
  56 # Adding sub-tasks to tasks under existing milestone
  57
  58 * notify Michiel and the relevant NNNN-NN@nlnet.nl team of
  59   advance notice of intent to add new sub-tasks, cc'ing bob
  60   goudriaan
  61   - confirm with them that this is NOT a change in the AGREED
  62     MILESTONE BUDGETs, because it is just sub-task allocation.
  63   - confirm that they are happy to add the sub-tasks to the MoU
  64     (this needs approval of bob goudriaan)
  65 * *re-generate* the JSON file
  66 * make a DIFF against the *PREVIOUS* JSON file
  67 * create a MANUAL report/summary of "changes" that
  68   NLnet may easily action
  69   - "add the following task X to parent Y of amount W",
  70   - and if any: "change parent Z available amount to V as a WRAPUP")
  71   (this latter is because occasionally there are subtasks **not**
  72    totalling the full parent amount, usually because a summary
  73    report is needed. Michiel and I privately agreed to call
  74    this "wrapup")
  75 * obtain a confirmation that this has been actioned
  76 * **double-check** that the RFP database correctly matches the new
  77   bugzilla status.
  78
  79 PLEASE NOTE: YOU CANNOT ACTION THE ABOVE UNDER THE FOLLOWING CIRCUMSTANCES
  80
  81 1. to make a change to the actual budgetary amounts of the
  82    Grant Milestones, without written authorization from Bob
  83    and Michiel. a DIFFERENT PROCEDURE is needed.
  84    this is because NLnet had to go through a 3rd party Verification
  85    Process with the European Union: changing the amounts without
  86    consent is therefore tantamount to fraud.
  87
  88 2. if there has been an RFP already submitted under a given Milestone,
  89    it becomes NO LONGER POSSIBLE to change the JSON file in NLnet's
  90    system because it is too complex.
  91
  92    there is one Grant in this complex situation: bug #690, the crypto
  93    grant.  it is made much more complex because it *pre-dates* NLnet's
  94    current RFP system, where RFPs were submitted by EMAIL and there
  95    are manual records not fully integrated into the database.
  96
  97 also note: as the addition of sub-tasks *requires a change to the MOU*
  98 it should NOT be taken lightly, i.e. should not be arbitrarily done
  99 one by one, but only in "batches".
 100
 101 considerable care therefore has to be taken to ensure that NLnet are
 102 not overloaded, nor that the EU Auditor is given grounds to become
 103 "suspicious" because of a dozen or more alterations to the MOU.
 104 and write your nickname (i.e. andrey etc.).
 105
 106 # Budget Estimation
 107
 108 Working out a time taken (and budget) for a sub-tasks requires
 109 guestimating. A small self-contained task should take
 110 approximately **1/2 a day up to 8 days (+/- 40%)**.
 111
 112 The total for a group of sub-tasks should be approximately
 113 **5-25 days**. If a single tasks looks like it might take
 114 longer than 8 days, it is **required** to break it into
 115 smaller subtasks. Big tasks can quickly get out of hand, so
 116 if in doubt, splitting a task is the better option.
 117
 118 Assume *1 month is appx EUR 3000* (this is an average; the value
 119 may be higher depending on circumstances) and back-calculate.
 120
 121 These numbers come from Luke's
 122 [comment #8 on bug #1126](https://bugs.libre-soc.org/show_bug.cgi?id=1126#c8)
 123
 124 Statistically speaking using the +/- 40% variance for each task,
 125 and adding up over 20+ tasks will give a time estimate
 126 **that is accurate to +/- 10%**.
 127
 128 *(Any sources on this?)*
 129
 130 However it is very important to have a *clear idea of what is
 131 actually needed*, and to *not leave anything out*.
 132
 133 For example, when determining the task of adding instructions:
 134
 135 - For each instruction perform a thought experiment:
 136   "how many lines of HDL, how many unit tests?"
 137 - Then from *- past experience -* estimate the total number
 138   of days.
 139 - Assume 1 month is appx EUR 3000 and back-calculate.
 140 - Put that number for each instruction (or group)
 141 into comment 0, add them up, and make that the total
 142 for the task.
 143
 144 *(Luke has used this method for the last 5 years based on 20 years
 145 of project management, and it is **expected for the team to familiarise
 146 themselves with it**)*
 147
 148 Also, make sure not to forget including **documentation** in your
 149 estimate. This ensures a portion of grant money is allocated
 150 to actually documenting the work involved.
 151
 152 Without documentation, it is not only difficult to teach newcomers about
 153 the code in question, it makes it difficult to come back to the code
 154 6-12 months later for maintenance and/or improvement
 155 (not a rare situation in LibreSOC).
 156
 157 Don't forget to ask fellow project for help, they might be able
 158 to help determine the scope of the work involved.
 159