rhendric
commented
4 years ago I would roll milestones up into this as well and say that it would be good to codify workflows for issues and PRs, which can be implemented with labels, milestones, code reviews, and/or possibly other features.
I'd love for this to be a thing—it would make it easier for me to help out as a new collaborator—so if this is the right medium for the discussion let me make a rather more detailed proposal than the above. If this is ahhh too much process we hates it, no big deal; I just thought this might help to advance the metaprocess.
Workflow for issues
For each issue, the following questions should all get answered in roughly this order (or the issue should end up closed one way or another):
- Is the reporter misusing the issue tracker or mistaken about any question of fact? If not, add label confirmed. Non-core collaborators can apply this label.
- Is it clear what could be done to respond to the report? If so, add label designed. Non-core collaborators can apply this label.
- Is there an approach that would improve the project, in the opinion of the core team? If so, add label accepted. An accepted issue may be worked on by contributors.
- Does the core team know on what timescale they intend to implement the approach? If so, assign to milestone (either a release or a ‘Help Wanted’ milestone).
The above statuses are retained for the life of the issue, unless the conditions by which they were reached are determined to be incorrect. (E.g., an issue can have its designed label removed if the design is subsequently found to be substantially incomplete.)
Workflow for pull requests
For pull requests, the relevant questions are as follows:
- Does the PR represent an approach that would improve the project, in the opinion of the core team? If so, add label accepted. A PR addressing an accepted issue can automatically be marked accepted.
- Is the PR good? Individuals can conduct code reviews and record approvals or needs-changes. The governance document already describes the conditions for merging the PR based on who and how many approve. When those conditions are met, add label ready to merge.
- (Maybe there should be multiple ‘ready to merge’ labels of different durations, as @joneshf suggests? Specify these durations if so.)
- After the appropriate waiting period, a ready-to-merge PR can be merged.
Pull requests may be assigned to milestones if the core team decides to commit to landing a PR in that time frame.
Blocker labels for issues and PRs
If any of the above workflow questions can't be answered:
- Because of action needed from the reporter: add label needs info
- Because of information needed from the core team: add label needs core team
- This is intended to be a list the core team members can check periodically for things that have slipped through the cracks; it's not the complement of needs info. @-notifying specific members is better, but if you don't know who to @-notify, add needs core team.
- Because of a vote in progress: add label voting
- I don't want to codify at this time what situations require a vote; I figure anyone on the core team can call a vote when one is needed, and it's up to their judgment to determine when that is the case. Or, something more rigorous can be decided in a separate thread.
- Because of an event that hasn't occurred yet: add label deferred until [event] (e.g., deferred until 0.14 or deferred until polykinds)
- This can be used to express ‘we can't figure out how to do this yet’ (for issues not yet designed), ‘we can't determine if this is a good idea yet‘ (for issues not yet accepted), or ‘we can't know what our plan to implement this is yet’ (for accepted issues). For ‘we have higher priority things to work on for the time being, but you're welcome to give it a shot’, don't defer, just put in the appropriate milestone, with ‘Help Wanted’ as a catch-all fallback. These labels exist so that, when the specified event comes to pass, all the thus-labeled issues can be revisited at whatever stage in the workflow they were left in.
- For some reason not included in this workflow: add label stuck (hopefully this doesn't get used often)
The above statuses are removed when they no longer apply.
Category labels for issues and PRs
In order to make sure people can look at issues and PRs of interest to them, any of the following categories of labels can be applied at any point in the workflow:
Issue type
- bug, for unintended behavior
- enhancement, for desired new behavior
- regression, for bugs that used to work in an earlier release
- It may not be clear which of these types apply to an issue, and yet the issue may still capture something worth doing. It's okay for issues to not have any of these labels in that case. See also the housekeeping label.
Areas of interest
- aspects of the language (syntax, typechecker, optimizer)
- specific purs subcommands
- epic features (polykinds, coercible, modules)
- Or these could be GitHub projects?
- housekeeping (tests, build process, etc.)
- question (this appears to be a misuse of the issue tracker; however, sometimes the line between a question and an enhancement is thin—it can be appropriate to apply this label before an issue is confirmed or designed without immediately closing the issue)
- ...and so on; this is an open list
Other
- new contributor (issues only)
Issue resolutions
A closed issue doesn't need to be shepherded anymore, but it may still be useful to determine at a glance why the issue was closed. For this purpose, use the following resolution labels:
- invalid: blatant misuse of the issue tracker
- question: subtle misuse of the issue tracker
- duplicate: file with the Department of Redundancy Department
- abandoned: information is needed from the reporter but they have not been responsive for an excessive amount of time
- worksforme: the reported deficiency can't be reproduced
- notabug: the reported behavior is intentional
- notourbug: the reported deficiency is unintentional but not caused by this project
- wontfix: the reported deficiency may not be intentional but no possible change would result in a net improvement to the project
- fixed: the reported deficiency has been addressed
- retracted: the reporter closed the issue or PR themselves for reasons not covered by the other resolutions
thomashoneyman
JordanMartinez
garyb
In #3, @f-f suggested defining labels for use in GitHub issue trackers so that it's easier to cross-reference from this document to any particular issue and see what state it is in.
@f-f, https://github.com/purescript/governance/pull/3#discussion_r409556464
@joneshf, https://github.com/purescript/governance/pull/3#discussion_r415084285