Maintenance Workflow

Lessons

Maintenance Workflow

Any user/PH Team member/Editor/Editor of Translation/Managing Editor may report a bug. The options for how to do so, are outlined here.

1. Upon receiving a report, our Publishing Assistant will open an Issue on GitHub. She will then carry out an initial assessment to confirm whether the bug reported represents an error caused by the user (editing the lesson's code or changing its dataset, for example) or an error within the lesson itself.

   a) If the former, our Publishing Assistant will close the Issue.
   b) If the latter, our Publishing Assistant will re-test the relevant part(s) of the lesson and undertake research to identify a fix, step 2).

2. Publishing Assistant will assess, test and research a fix. As part of this process, she may contact extended members of the Programming Historian team and (if appropriate) the author, to ask for advice.

   a) If the Publishing Assistant can identify a fix, she will propose a solution and generate a Pull Request to edit the lesson appropriately, moving to step 5).

   b) In the case that the Publishing Assistant cannot identify a fix, she will move to step 3).

3. a) Publishing Assistant will propose adding a warning to the lesson explaining that some users may encounter an error. Where possible, this warning should include links to further reading, empowering users to identify a solution themselves. She will generate a Pull Request to edit the lesson appropriately, then move to step 5).

   or

   b) Publishing Assistant will proceed to check budget for an external practitioner to carry out an assessment. If budget is available, the Publishing Assistant will contact an external practitioner (list to be kept below on this Wiki page), agreeing a fee and the standard terms of service, moving to step 4).

   Note: External assessors will be hired as sole traders for individual pieces of work, and will not be employees of ProgHist ltd. The Publishing Assistant will remain external assessors' point of contact.

4. a) If the external assessor can identify a fix, they will propose a solution and generate a Pull Request to edit the lesson appropriately, moving to step 5).

   b) In the case that the external assessor cannot identify a fix, they may propose adding a warning to the lesson explaining that some users may encounter an error. Where possible, this warning should include links to further reading, empowering users to identify a solution themselves. External assessor or Publishing Assistant will generate a Pull Request to edit the lesson appropriately, moving to step 5).

   Note: If the lesson is written in Spanish, French or Portuguese, the relevant team will be assigned as 2nd Reviewers.

   c) Either way, the external assessor submits their invoice to the Finance Manager via programminghistorian@gmail.com.

   Note: Invoices must include the title of the lesson.

5. At this stage, the appropriate Managing Editor will review the proposed solution, and advise either:

   a) they are happy with the fix and can Approve the Pull Request
   b) they are happy with the warning and can Approve the Pull Request

   or

   c) (as a last resort) and drawing upon our retirement policy, that it would be better to retire the lesson.

   Note 1: Depending whether the agreed solution represents a minor/major change to a lesson or its retirement, it will be important to consider our DOI Policy as well as the possibility that additional translation work may be required.

   Note 2: In the case that the agreed solution represents a minor/major change to a lesson, our Publishing Assistant will add a link from our Wiki page outlining our DOI Policy to the Issue in question. The objective is to provide examples of changes deemed 'minor' and 'major' changes, so that future decisions are consistent.

This workflow will be revisited at least once per year at the ProgHist Ltd AGM.

List of approved external assessors.

English & French

Spanish

• Jairo Melo