Clarify annotation policies for issue management
There is frequent frustration about the status of issues and whether they are being managed in an appropriate way, but we have struggled to clearly articulate
- what the discrete states of an issue are,
- how they should progress through those states (and on what time scale),
- who shepherds them through each state,
- and how this is communicated to people examining the issue in the tracking system.
Without sufficient annotation and mutually understood semantics, we are also unable to identify and mitigate failures in such a process.
MR !2591 (closed) attempts to record the policy clarification from the developer video call on 9 March, 2022.
Whether or not what is recorded is accurate, it is not complete.
An ideal resolution to this issue would address the following
frequently asked questions
- When I open an issue, should I assign it to someone?
- From discussion: Assign it to yourself if you are willing to coordinate effort.
- How do we determine that an issue is something that the project wants to pursue or wants to accept into GROMACS, and how is this annotated?
- There are mixed messages about whether certain types of Milestone indicate that a proposal is accepted by project managers, and who should or should not set the Milestone on an issue.
- For historical reasons, we have a
Status::Accepted
label, but it doesn't seem to get used.
- How does someone (e.g. a project manager) know that an issue has effort allocated on a particular timeline?
- From discussion: A
release*
ordevcycle*
Milestone indicates that the assignee has identified and allocated the necessary resources to attempt delivery on corresponding time scale.
- From discussion: A
- How does a contributing developer or reviewer know whether an issue or MR is actually a high priority for a release target?
- When an issue is opened, what should happen (e.g. https://manual.gromacs.org/current/dev-manual/reportstyle.html#issue-workflow), and on what time scale? How do we track this evolution? (i.e. Who should take what action or make what decision, and what annotation should they use to indicate it has been done?)
- How do the quarterly planning meetings and the biweekly teleconferences fit into the above, if at all?
Reference
Following is a not-quite-comprehensive list of issue states that occur. We can consider for each case (a) whether the state is uniquely representable in the tracked issue, (b) what details of the tracked issue page convey the state, and (c) by whom and under what circumstances is that information expected to be applied to the Issue.
Bugs
-
A bug, reported by someone who does not intend to solve the bug, has not been verified or prioritized for a release target. -
A bug report is rejected as unverifiable, not a bug, or not something that we want to disrupt the repository or release schedule in order to fix. -
A bug, reported by someone who does not intend to solve the bug, has been verified but not yet prioritized for a release target. -
A bug, reported by someone who does not intend to solve the bug, is prioritized for the current release target, but does not have developer or reviewer resources allocated. -
A bug, reported by someone who is offering to solve the bug (or otherwise has developer resources available), has not yet been prioritized for a release target. -
A bug is prioritized for a future release target and has developer resources. -
A bug, prioritized for the current release target, has developer resources but does not have reviewer resources. -
A bug, prioritized for the current release target, has developer resources and reviewers.
(As a bug, a developer might allocate effort in either of the last two cases, but probably shouldn't bother submitting an MR in the earlier cases.)
Other issues
-
An issue, opened by someone who does not intend to contribute (feature request, "to do", etc), has not been discussed or prioritized for a release target. -
An issue is declared not to be a priority for a current release target, but may be targeted in the future. -
An issue is determined to represent a change or contribution that is not wanted in GROMACS. -
An issue has been declared a priority, but has not been allocated developer/reviewer resources or targeted to a specific release. -
An issue has been declared a priority, and targeted to the current release, but has not been allocated developer/reviewer resources. -
An issue, with available developer resources, has not been discussed or prioritized for a release target. -
An issue, with available developer resources, has been discussed but is deferred to a future release target. -
An issue, with available developer resources, has been targeted to a specific release target, but does not have reviewer resources. -
An issue, with developer resources and reviewers, is targeted to a specific release target.
(Realistically, a developer should not allocate their time to prepare an MR except in the last case.)
Descriptive matrix
In the most technical sense, the above illustrate the existence of the following matrix dimensions, which we can choose to represent (or not), either discretely or in some information-lossy way.
- Has the issue been discussed (rejected? accepted? how important?) as something to address in GROMACS?
- (dependent dimension) what is the targeted timeline to address?
- (dependent dimension) what is the target branch?
- (dependent dimension) when is the issue scheduled to be discussed (and accepted/rejected, effort allocated, etc)?
- (dependent dimension) has the issue gone stale or remained incomplete after its milestone has expired?
- On what timeline are developer resources available (if at all)?
- On what timeline are developer resources allocated?
- On what timeline are reviewer resources available (if at all)?
- What is the current level of completion?
Resolution
update: this issue was not discussed at the planning meeting on 2022-03-15
-
Update reportstyle.rst
andchange-management.rst
to clearly and accurately describe current practices.-
Document GitLab annotation features used. -
Document the information that should be conveyed apart from GitLab annotations, such as in issue description text or linked wiki pages. -
Remove or repair inaccurate documentation. (e.g. if the issue flow diagram and discussion is still relevant, clarify; otherwise remove; see also corresponding Status scoped labels.)
-
-
Optionally, schedule follow-up discussion.