Project management

When completing the design of our ventilator, we will have to produce extremely meticulous summaries of how we arrived at this design for regulatory purposes. We want to make it easy for ourselves at a later time to go back and see exactly how solutions were arrived at, on the basis of what requirements work was undertaken. The best way to do that is to track our work now and cross-link relevant information as much as possible.

In this endeavor, the goal of the project manager is not to close as many issues as possible. The goal is to help the engineers track all progress systematically and painlessly. Voiced concerns should always be captured. Decisions should always be documented. Relevant information should always be easy to find. Some of this can be ensured by everyone following the same guidelines. However, people may be focusing on different aspects of this work and may not have attention to spare for all the details. The project manager's role here is to prevent things falling through the cracks. In many cases this may boil down to periodic review of all filed tickets and tracking down of missing information to ensure complete follow-through and full traceability of all decisions.

How to use issues/tickets

• An issue (also referred to as ticket) is the main unit for tracking tasks and decisions. An issue is opened or closed from the issue interface. Project boards are only helper tools for having a "big picture" view. Follow the actual status of the issue in categorizing it.
• Never delete tickets.
• Tickets should never be closed without a comment. If you are closing a ticket you must understand the technical details of the solution and explain them in your closing comment. If you find a ticket that was closed without explanation, seek out appropriate owner or stakeholder and help add the necessary information.
• A ticket should only be closed by someone who actually worked on solving that particular ticket, preferably whoever was assigned to that ticket. This means that engineering related tickets shall only be closed by engineers. Administrative or general-documentation tickets may be closed by whoever worked on updating the appropriate pages.
• All tickets should have appropriate labels for categorizing them. Periodically check that the labels are appropriate.
• All tickets should be assigned to at least one project board. Some may straddle a few domains and thus be assigned to multiple projects. Periodically check that they are appropriately assigned.
• Open tickets should preferably be linked to an upcoming milestone. Low priority tickets may be filed with a "down the road" milestone for a version that is after the one currently being worked on. Assignment of issue to a milestone should reflect prioritization of features intended for upcoming prototype iteration and should be determined by appropriate team leads.
• Related issues should be cross-linked. Read what is written. If it seems like you have come across similar language before, do a search of all (closed and open) tickets and see if there is a related one. Identify hierarchically and laterally related tickets. If A is related to B and B is related to C, it may be necessary to also link A to C. And so forth.
• We want PRs to trace back to tickets. Link PRs to the originating issue. If someone claims that the ticket was closed by implementing code or adding documentation, they should identify which PR entailed those changes and link to it from the ticket.
• If you are asked to or have to create a ticket for someone else, for an issue that you do not fully understand, make sure to mark it with the NEEDS DETAIL label and follow up by sending a link to the appropriate person who likely has the missing information. It may also be that we do not (yet) have the right expert in our midst to provide that information, and the ticket might retain this tag for a while. It might be good to periodically review such tickets and bring them to the attention of everyone on the team.
• Make sure you are familiar with our issue templates and have an idea of what an adequately informative ticket looks like. Keep an eye on newly created tickets and prompt their creators to add whatever information is missing. Some older tickets might predate the creation (or latest edition) of the templates. It might be a good idea to go back to those older (unclosed) tickets and help add the missing information.
• Make sure you are familiar with the issue-tracking guidelines provided to contributors on the main wiki page. If the processes don't make sense, please suggest improvements and let's adopt a new set of guidelines with some consensus among contributors.

How to use a project board

• Project boards are thematic, i.e. a project is related to the team that will use it or set of technical disciplines that it encompasses.
• Project are not milestones. New projects shall not be created for time-constrained milestones. The milestones feature is to be used for that purpose.
• Projects may be accessed and created in the Projects tab.
• New projects should use the Basic Kanban as the template.
• Change the column names to mirror other boards in the project, unless yours has to be designed differently.
• When creating columns in projects, do not automate anything with regard to PRs. PRs may be related to software, hardware, PCB, or anything else, i.e. issues that are already handled by different boards. They should not end up on the same board.

Project columns

The columns in our boards shall be used as follows:

1. Backlog - is automated to claim all new tickets. As such, new tickets are not prioritized for immediate work. No tickets marked with the PRIORITY label should be here. Any BLOCKED tickets should likely be here, unless they are PRIORITY.
2. Up next - these are tickets that are (moderately) prioritized to be worked on next. All previously closed but re-opened tickets are automated to end up here. PRIORITY tickets should be here and should be periodically brought up in meetings to encourage appropriate action.
3. In progress - any tickets actively worked on should be in this column. The column has no automation. If someone has begun working on an issue, the appropriate ticket should be manually moved here. If a ticket history has commits that reference this ticket, this is a sign that is being worked on. If a someone mentions working on a particular task in a meeting, there might be an affected ticket that needs to be moved here. People might be working on an issue that is not being tracked, in which case an issue might have to be created to track it.
4. Done - is automated to claim closed issues. Only closed tickets should be in this column. Do not move unclosed issues to this column. If an open issue ends up in this column, it should not be closed, but rather moved back to one of the other columns and brought to the attention of appropriate owners/stakeholders.