[SD-1] Use GitLab Issues as Decision Record #1

New Issue

2022-07-13T18:00:56-05:00

daedelan commented

2022-07-13 18:00:56 -05:00

(Migrated from gitlab.com)

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 ✅ reaction to the GitLab issue description.

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 ❌. At the time of writing this appears as a large red 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 ✅, they should remove the 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.

**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 ```mermaid 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 :white_check_mark: reaction to the GitLab issue description. - At the time of this writing, :white_check_mark: 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:. At the time of writing this appears as a large red `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 :white_check_mark:, they should remove the `vote` label and add `unanimous`. ## Mutability | State | Condition | | --- | --- | | `vote`<br>`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.

daedelan commented

2022-07-13 18:00:56 -05:00

(Migrated from gitlab.com)

changed due date to July 13, 2022

daedelan commented

2022-07-13 18:00:57 -05:00

(Migrated from gitlab.com)

assigned to @daedelan

laddhoffman commented

2022-07-13 18:04:27 -05:00

(Migrated from gitlab.com)

I like GL

laddhoffman commented

2022-07-14 02:12:19 -05:00

(Migrated from gitlab.com)

changed title from {-GH vs. GL-} to {+Use GitLab Issues as Decision Record+}

changed title from **{-GH vs. GL-}** to **{+Use GitLab Issues as Decision Record+}**

laddhoffman commented

2022-07-14 02:12:19 -05:00

(Migrated from gitlab.com)

changed the description

laddhoffman commented

2022-07-14 13:41:15 -05:00

(Migrated from gitlab.com)

I am going to update this ticket to reflect the conclusions of ClickUp task Documentation Tooling: Decision Records.

I am going to update this ticket to reflect the conclusions of ClickUp task [Documentation Tooling: Decision Records](https://app.clickup.com/t/2mucqtp).

laddhoffman commented

2022-07-14 13:48:45 -05:00

(Migrated from gitlab.com)

The following was copied from Documentation Tooling: Decision Records

This ticket is meant to represent the considerations surrounding the documentation the team will produce and utilize during the development and decision-making process of building our operations and technology.

Craig has expressed a strong desire for there to be transparency of connection between code we produce, and the perspectives and conversations leading to producing that code.

This suggests that individual decisions should be uniquely identifiable. Hence, a collorary to this ticket is that we need to articulate our decision-making processes. This may become a separate ticket but for now let's try to unpack it here. It may be something like the following:
Make observations
Think of an idea
Conceptualize the idea in relation to the current context.
Include notes about observations, as they may enable others to make similar observations of their own.
Team members provide input, articulating their own perspective.
Consider the meta-process of forming and maintaining conventions. Have team conversations around this.
Discussions unfold
At some point a decision is reached and recorded.

Code and documentation will be able to uniquely reference this conversation. Perhaps there can be options regarding the way it's referenced:
A decision was reached
An idea was proposed and we're exploring it
A consideration was raised that influenced some implementation choices

There is overlap in the requirements here with those of the EIP (Ethereum Improvement Proposal) process.https://eips.ethereum.org/EIPS/eip-1.
Another related process is the RFC process, https://en.wikipedia.org/wiki/Request_for_Comments
We can likely trim a bit of the bureaucracy at this stage.
At some point we may want to adapt the decision-making process to use an MVPR (style) informal/formal voting system.

The following is a discussion of a possible short-term approach. We can use any platform for this. Easily available possibilities include Github wiki, Github issues, Clickup tasks, Google Docs, or even files in a Github repo.

The process:
Create a {document, page, ticket, file}
Assign it a unique identifier as the title or filename, following some pattern, TBD. Subtask.
Draft phase: Populate the initial description.
Discussion phase: Team members provide their views on the subject, as comments or document subsections
May be informal and have no direct effect on the proposal
May propose modifications. Two options:
Comment serves to record a change delta with, or body of, the current description. Modification is made directly to the current description. Description metadata (discussed below) MUST be updated to indicate the provisional status of the item.
Comment serves to propose a change delta with, or body of, the current description. IFF accepted the current description SHALL be modified or replaced.
These options may be selected per comment as needed.
Definition of acceptance TBD.
The main description may also be updated with metadata about the status of the item.
For example, if it has been called into question and a conclusion has not been confirmed.
Such metadata may be represented in text under a specifically identifiable heading with a bulleted list of items in a proscribed format, TBD.
Possible implementation: files stored in git
Advantage: This could enable us to render user-facing presentations derived from content that has been merged into the git repository.
This can be done from, in principle, any commit ref. In practice we could use a main-based git flow, and discussions can occur around merge requests.
Possible implementation: GitHub wiki
Advantage: This provides an easy on-ramp for a documentation process, requiring minimal setup efforts.
Disadvantage: It would rely heavily on the team manually adhering to some process conventions.
Counterpoint: Although burdensome, this would incentivize us to keep our processes lean, which may be appropriate at this early stage
Advantage: The wiki could serve directly as user-visible documentation, without requiring any additional dev or config work beyond simple permissions settings making the content read-only to the public.
Possible implementation: ClickUp
Advantage: Clickup provides a nice interface for ticket management.
Advantage: If we can expand the use case coverage of a single tool, we will have less context-switching to navigate.

Feature comparison matrix

Feature vs Platform	GH/GL Wiki	GH/GL Files	ClickUp Tasks	GH/GL Issues	Google Docs
Diagrams	(Mermaid soon)	Any format, but requires tooling	As images; Miro; ...?	Mermaid	As images
Data export	Yes	Yes	CSV	Yes	Yes but not nicely
Automatic metadata	No	Yes, detailed	Yes	Yes	Partial
Can be directly published	Yes	Yes, but requires tooling	Yes	Yes	Yes but not nicely
Can derive views of items e.g. by status	Would require tooling and adherence to conventions	Would require tooling and adherence to conventions	Yes	Yes	No

The following was copied from [Documentation Tooling: Decision Records](https://app.clickup.com/t/2mucqtp) This ticket is meant to represent the considerations surrounding the documentation the team will produce and utilize during the development and decision-making process of building our operations and technology. Craig has expressed a strong desire for there to be transparency of connection between code we produce, and the perspectives and conversations leading to producing that code. This suggests that individual decisions should be uniquely identifiable. Hence, a collorary to this ticket is that we need to articulate our decision-making processes. This may become a separate ticket but for now let's try to unpack it here. It may be something like the following: Make observations Think of an idea Conceptualize the idea in relation to the current context. Include notes about observations, as they may enable others to make similar observations of their own. Team members provide input, articulating their own perspective. Consider the meta-process of forming and maintaining conventions. Have team conversations around this. Discussions unfold At some point a decision is reached and recorded. Code and documentation will be able to uniquely reference this conversation. Perhaps there can be options regarding the way it's referenced: A decision was reached An idea was proposed and we're exploring it A consideration was raised that influenced some implementation choices There is overlap in the requirements here with those of the EIP (Ethereum Improvement Proposal) process.https://eips.ethereum.org/EIPS/eip-1. Another related process is the RFC process, https://en.wikipedia.org/wiki/Request_for_Comments We can likely trim a bit of the bureaucracy at this stage. At some point we may want to adapt the decision-making process to use an MVPR (style) informal/formal voting system. The following is a discussion of a possible short-term approach. We can use any platform for this. Easily available possibilities include Github wiki, Github issues, Clickup tasks, Google Docs, or even files in a Github repo. The process: Create a {document, page, ticket, file} Assign it a unique identifier as the title or filename, following some pattern, TBD. Subtask. Draft phase: Populate the initial description. Discussion phase: Team members provide their views on the subject, as comments or document subsections May be informal and have no direct effect on the proposal May propose modifications. Two options: Comment serves to record a change delta with, or body of, the current description. Modification is made directly to the current description. Description metadata (discussed below) MUST be updated to indicate the provisional status of the item. Comment serves to propose a change delta with, or body of, the current description. IFF accepted the current description SHALL be modified or replaced. These options may be selected per comment as needed. Definition of acceptance TBD. The main description may also be updated with metadata about the status of the item. For example, if it has been called into question and a conclusion has not been confirmed. Such metadata may be represented in text under a specifically identifiable heading with a bulleted list of items in a proscribed format, TBD. Possible implementation: files stored in git Advantage: This could enable us to render user-facing presentations derived from content that has been merged into the git repository. This can be done from, in principle, any commit ref. In practice we could use a main-based git flow, and discussions can occur around merge requests. Possible implementation: GitHub wiki Advantage: This provides an easy on-ramp for a documentation process, requiring minimal setup efforts. Disadvantage: It would rely heavily on the team manually adhering to some process conventions. Counterpoint: Although burdensome, this would incentivize us to keep our processes lean, which may be appropriate at this early stage Advantage: The wiki could serve directly as user-visible documentation, without requiring any additional dev or config work beyond simple permissions settings making the content read-only to the public. Possible implementation: ClickUp Advantage: Clickup provides a nice interface for ticket management. Advantage: If we can expand the use case coverage of a single tool, we will have less context-switching to navigate. Feature comparison matrix | Feature vs Platform | GH/GL Wiki | GH/GL Files | ClickUp Tasks | GH/GL Issues | Google Docs | | --- | --- | --- | --- | --- | --- | | Diagrams | (Mermaid soon) | Any format, but requires tooling | As images; Miro; ...? | Mermaid | As images | | Data export | Yes | Yes | CSV | Yes | Yes but not nicely | | Automatic metadata | No | Yes, detailed | Yes | Yes | Partial | | Can be directly published | Yes | Yes, but requires tooling | Yes | Yes | Yes but not nicely | | Can derive views of items e.g. by status | Would require tooling and adherence to conventions | Would require tooling and adherence to conventions | Yes | Yes | No |

laddhoffman commented

2022-07-14 14:12:14 -05:00

(Migrated from gitlab.com)

Copy-paste from ClickUp did not preserve formatting. I manually corrected the formatting of the table, but left the bulleted lists in their collapsed form.

laddhoffman commented

2022-07-14 14:46:17 -05:00

(Migrated from gitlab.com)

Diagram of the decision-making process sketched in the above pasted content.

sequenceDiagram
actor author as Proposer
participant draft as Proposal
actor team as Team Members
author ->> draft : Create a draft proposal
author ->>  team : Solicit feedback 
team ->> draft : Comment, Like/Dislike
author ->> draft : Update draft
author ->> team : Solicit approval 
team ->> draft : May approve

Diagram of the decision-making process sketched in the above pasted content. ```mermaid sequenceDiagram actor author as Proposer participant draft as Proposal actor team as Team Members author ->> draft : Create a draft proposal author ->> team : Solicit feedback team ->> draft : Comment, Like/Dislike author ->> draft : Update draft author ->> team : Solicit approval team ->> draft : May approve ```

laddhoffman commented

2022-07-14 14:50:33 -05:00

(Migrated from gitlab.com)

assigned to @laddhoffman and unassigned @daedelan

laddhoffman commented

2022-07-14 15:23:58 -05:00

(Migrated from gitlab.com)

changed title from Use GitLab Issues as Decision Record to {+[SDR-1] +}Use GitLab Issues as Decision Record

changed title from **Use GitLab Issues as Decision Record** to **{+[SDR-1] +}Use GitLab Issues as Decision Record**

laddhoffman commented

2022-07-14 15:23:58 -05:00

(Migrated from gitlab.com)