A Protocol for creating ADRs

[krzywon]

Using the easyscience ADR protocol as a basis, this suggestion outlines how SasView should propose, review, and implement new Architecture Design Records (ADR). This was discussed at todays technical meeting.

1. Suggestion Phase

1. At the appropriate GitHub level (Organization or Repo) create a new discussion and apply the ADR Suggestions category.
2. Use a title that describes what the ADR concerns. e.g.: Qt GUI element naming convention. The title may include ADR Suggestion if desired, but is not required.
3. Technical meeting participants will review any recent ADRs submissions.
   • Implementation Phase: 2-3 discussion and/or ADRs will be brought to each meeting until all outstanding discussions are resolved
4. Technical meeting participants will offer a suggestion on whether to implement the ADR, including any proposed changes.
5. All technical meeting suggestions, whether to approve or deny, will be presented at the bi-weekly meeting for a larger review.
6. All discussion points from the two meetings will be added as comments to the Discussion.
7. The results of the larger review will be sent to the developers mailing list to give developers unable to attend meetings a chance to review the suggestion. This announcement shall have a date of final decision, which should coincide with a bi-weekly meeting at least 3 weeks in the future.
8. Comments to the proposal may be included either during the final meeting or by email.
9. A final decision on an ADR will be made at the announced meeting by the participants in attendence and tasks from the following headings 2, 3, and 4 will be assigned to a specific person or people at the time of decision.

2. Accepted ADR

1. A SasView maintainer or admin will create a new Discussion under the ADR category.
2. The title should describe the issue the ADR is addressing, and should be similar to title from the Suggestion Phase.
3. The description of the ADR should be a comprehensive resume of what has been accepted.
4. The description should include a revision number and link to the previous revision of the ADR, if it exists.
5. The description should include links to the original discussion(s).
6. The original discussion(s) should be closed.

3. Rejected ADR

1. An outline of why the ADR was rejected will be entered into the discussion as a final comment.
2. The original discussion(s) will be closed.
3. Appealing a rejection may be made if new information or ideas are brought to either the bi-weekly or techinical meetings and the attendees agree the ADR be revisited. In this case, the person appealing the ADR should reopen the discussion, and include the new information.
4. Reopening a rejected ADR restarts the process at step 7 of the Suggestion Phase.

4. Tracking Implementation

1. Once the ADR is accepted and finalized, create a corresponding issue in the relevant repository (or repositories) to track the implementation.
2. The issue body should include a reference to the ADR the issue is based off.
3. If the ADR impacts multiple projects or components, apply the label Cross Package Issue to each related issues and, once all are created, edit the issue descriptions to include links to all related issues.

5. Revision Process

1. To revise an ADR start a new discussion (Idea or Poll category) as in Suggestion Phase (1), but start the title with the word Revision: and follow it with the ADR title.
2. The revision process will be the same as the normal process.
3. As described in Accepted ADR (4), increment the revision number and add a link to the previous revision in the updated ADR.

[krzywon]

Suggested changes I already have for this:

• No ADR suggestion should be edited for content. Any additions/modification suggestions or edits should be made through comments (such as this comment!) to ensure transparency in the process
• Rejected ADRs should still be put out to the community, but no follow up meeting time should be given, unless the ADR is reopened

[rozyczko]

Rejected ADRs should still be put out to the community, but no follow up meeting time should be given, unless the ADR is reopened

Which just means we close them but don't delete them, so they can be accessed on GH, right?

[rozyczko]

No ADR suggestion should be edited for content.

Yes but we sometimes want to correct spelling, layout, etc. This sounds too restrictive. What we can do is to lock the ADR once it is agreed on, so no further changes/updates can be made

[krzywon]

Which just means we close them but don't delete them, so they can be accessed on GH, right?

Correct. I'll add that as a step to closed ADRs. We should never delete any git history.

Yes but we sometimes want to correct spelling, layout, etc. This sounds too restrictive. What we can do is to lock the ADR once it is agreed on, so no further changes/updates can be made

I was more thinking content changes, but I see your point. Alternate: To ensure the process remains transparent to someone who hasn't followed the suggestion from the start, ADR suggestions should only be edited for typos, format changes, and spelling mistakes. Substantive changes should be included as comments.

[krzywon]

Comments from technical meeting:

• Unending meetings on ADRs - how can we streamline this process?
• How do we not limit new contributors in that same light?
• Will there be too many for the Tuesday meeting? Already a longer meeting.
• Rejected ADRs do not go beyond Tuesday meetings
• Github repo of ADRs vs. Discussions? Discussions have immediate feedback option vs reading through markdown files

[butlerpd]

Unending meetings on ADRs - how can we streamline this process?

I'm not sure I follow this point. "unending meetings" suggests that there is no consensus doesn't it? If so, all that means it seems to me is that it is not ready to be implemented in the current form. Is the question about ADRs where there are strong opinions for and against? in which case the question is more one of process: does approval require unanimity, a majority or a supermajority? and anything not making it past that gets rejected?

[krzywon]

'Unending meetings' was more hyperbole. Three meetings being required to fully approve an ADR seems a bit much, but we discussed this at the technical meeting today, and the initial proposal to send each ADR out for a broader discussion if approved at a general meeting is the implementation we are going to pursue. If this process becomes too time consuming or does not garner the discussion we hope, we can revisit this in the future.

[butlerpd]

Sounds good. Just for the record, since that is what this discussion becomes, IMO, the worry about an ADR should not be how long it takes to resolve as much as making sure that it is not being dropped and/or forgotten. There should be a resolution one way or the other. The concern I think is that historically, without a process, many things just languish forever and are forgotten. This process, if followed, should prevent that. Given the expected weight of an ADR, the process should be slow and deliberate making sure that everyone in the community has the opportunity to think through any implications and to comment should they choose to do so.

[butlerpd]

From the implementation section, I assume we are thinking of ADRs as very hard inviolate rules? If so I would argue we need to keep those to a manageable number. In this case the question of being overwhelmed by suggested ADRs I would think is moot?

Also is there space/room for a "highly encouraged" category?

[krzywon]

Each ADR should outline what is required versus suggested. I guess we need to specify that here.

[krzywon]

As discussed at the biweekly meeting today, this proposal is moving to the next step and will be sent out to the developers list for further comment. The original body of work will remain with the following changes, based on feedback here and at the meeting:

• The timeline will remain as in the original proposal, with a discussion at a technical meeting, a tentative approval at the biweekly meeting, a window of at least 3 weeks for review, and, finally, a final discussion and approval at the next biweekly meeting after the 3 week window.
• ADRs rejected by both the technical group and at the biweekly meeting will be closed and not put out for further discussion.
• ADR suggestions should not be edited for substantive content. Typos and formatting should be the only edits made to suggestions and comments, otherwise some of the discussion may be lost to people first coming into the conversation.
• Recommended and required fiedls should be clearly labelled. In this suggestion, all fields are required.

[krzywon]

This has been approved and is now active as https://github.com/orgs/SasView/discussions/3357