[SD-1] Use GitLab Issues as Decision Record
Context
We need for a way to represent our work that potential partners can observe and understand.
To accomplish this, we want a system which is well-aligned with the rest of our work processes.
Proposal
For each decision we wish to take as a team, create a GitLab Issue. Use the issue to draft a proposal which, if accepted, will represent a Team Decision.
GitLab will auto-number the new issue upon creation. The designation of each proposal shall be this number prefixed with SD-
, for Science publishing dao Decision
, e.g. SD-1
. The title of the issue should then be prefixed as [SD-#]
, e.g. [SD-1] Use GitLab...
Proposal Lifecycle
flowchart LR
draft --> discussion
discussion --> vote
vote --> unanimous
unanimous --> discussion
Because GitLab Issues do not appear to support complex workflows through myriad ticket status values, we may instead represent our lifecycle stages/statuses using labels.
Labels and their definitions and usages
Label | Definition |
---|---|
draft | The author is actively engaged in shaping the content of the proposal. |
discussion | The author requests input from the team |
vote | The author requests that the team approve the decision |
unanimous | All team members have approved the decision |
Voting
To vote in favor, add
- At the time of this writing,
✅ appears as a green check mark:. The GitLab symbol for this is:white_check_mark:
.
Voting may only be finalized by unanimous consent, as measured by the count (at this time 4) of check mark :white_check_mark:
reactions on the GitLab issue.
To vote against, add x
, and its GitLab symbol is :x:
.
- This is to distinguish it from abstention
If an approval later chooses for any reason they may revoke their approval by removing their check mark symbol.
The labels applied to a given issue should be reviewed periodically, and should NOT be considered authoritative. Only the pure count of approvals should be considered authoritative, and the labels should be updated accordingly.
As a practice, whenever a team member adds the final vote
label and add unanimous
.
Mutability
State | Condition |
---|---|
vote unanimous
|
When a proposal is in the vote or unanimous stage it should NOT be modified, EXCEPT to add a reference to another proposal. For example, if a later proposal overrides an earlier one, the earlier proposal should be updated ONLY to add a reference to the newer proposal. The precise nature of the relationship must be described in the newer proposal. |
Notes
This ticket itself is meant to serve as the first recorded decision, thus demonstrating the proposed process.