Revision: Protocol for Creating ADRs in the SasView organization

[krzywon]

Original ADR: https://github.com/orgs/SasView/discussions/3357

Reasons for modifying the original ADR:

• The revision process does not include a procedure for showing what changes are proposed.
• A summary write-up step has been added to the suggestion phase.
• This suggestion uses the proposed revision scheme as an example.

This is the protocol for creating and approving Architectural Design Records for the SasView organization. This process extends to all repositories under the organization.

1. Suggestion Phase

1. At the appropriate GitHub level (Organization or Repo) create a new discussion under 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. The ADR should outline what items are required and what items are encouraged. For the purposes of this ADR, all items are required.
4. ADR suggestions and comments should not be edited for content. Typos and formatting issue edits are permissible, but substantive changes to the ADR should only be included as comments to ensure people new to the discussion can follow the entire course of the process.
5. Technical meeting participants will review any recent ADRs submissions.
   • During the Implementation Phase: no more than 3-4 discussion and/or ADRs will be brought to each meeting until all outstanding discussions are resolved.
6. Technical meeting participants will offer a suggestion on whether to implement the ADR, including any proposed changes, and any implementation phases, if required.
7. All technical meeting suggestions, whether to approve or deny, will be presented at the bi-weekly meeting for a larger review.
   - A person will be assigned to write the proposed final ADR wording. Prior to the bi-weekly meeting, this proposal will be added as a comment to the ADR Suggestion for easier review.
8. All discussion points from meetings will be added as comments to the Discussion by the person leading theany discussion on the ADR.
9. ADRs rejected by both the technical group and biweekly meetings will be closed, as described in heading 3 below and will not proceed beyond this point in the suggestion phase.
10. 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 include a title making it clear the message is related to ADR approvals, a link to the comment with the proposed ADR, and an anticipated date of final decision coinciding with a bi-weekly meeting at least 3 weeks in the future.
11. Developers may comment on the proposal in the ADR, during the final meeting, or by email, but all comments must be added to the Discussion by the person leading the ADR discussion.
12. A final decision on an ADR will be made at the announced meeting by the participants in attendeance 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 corresponding issues 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 as in Suggestion Phase (1), but start the title with the word Revision: and follow it with the ADR title.
   2. The original ADR should be copied/pasted in the new ADR and indented using the Quote option in the editor.
   3. Any changes to the text should use the following styles: Additions should be underlined, Modifications should be in italics, and deletions should be struckout.
   4. The reason(s) for modifying the ADR should be listed as a separate summary outside the quoted section.
   5. The revision process will be the same as the normal process.
   6. As described in Accepted ADR (4), increment the revision number and add a link to the previous revision in the updated ADR.

Revision Acceptance Date: May 6, 2025 TBD
Revision Number: 1 2
Original Suggestion: https://github.com/orgs/SasView/discussions/3243

[butlerpd]

As mentioned in the email to developers, this ADR was brought up for final approval at the October 7th meeting. However, by the time this discussion was put on the table there were only a few people remaining on the call. It was noted that there are zero comments to this proposal which can either be because people have not really had a chance to look at it or, more likely in view of those present, because it is so straightforward and obvious that there is nothing to comment on.

In view of the total lack of discussion and the very small number of people remaining on the call, final decision on this ADR was postponed to the next regularly scheduled developer's call on October 21, 2025.

[krzywon]

This was discussed during todays call and will be sent out for final review after the new year.