Codify Architectural Decision Records and Changelog

Use Case

Consumers should know where the project has come and gone and contributors should clearly document changes.

Scope of Work

Formalize the process by which changelogs and decision logs are generated, and document this process.

Contextual Information

• Orchestrator has decision logs as a first iteration toward Architectural Decision Records.
• Orchestrator has a milestone file which is incomplete
• Orchestrator should have a changelog as part of the release process we are designing.

Acceptance Criteria

• Document how the decision records will be stored and organized
• Document the changelog process and requirements

Outputs

1. merge request to fit the existing decision records into the new format
2. merge request to document our decision record process
3. issue to review the milestones and create a basic changelog
4. merge request to document how Orchestrator changelogs will work

added Orchestrator devopssystems groupdistribution spike labels

marked this issue as related to #216 (closed)

I've talked about this a bit over the last few weeks and realized that I'd not gone back to create an issue to allow asynchronous discussion. It's coming more into mind as the release process is defined.

cc @WarheadsSE , @ghickey and @mnielsen

changed title from Codify Decision Logs and Changelog to Codify Architectural Decision Records and Changelog

Document the changelog process and requirements

For the process, you should be able to follow that already outlined by various projects throughout GitLab (bin/changlog, scripts/changelog ...) as you're likely familiar with in gitlab-org/gitlab & gitlab-org/charts/gitlab.

Clarity should be collected regarding what changes require an entry, and those that do not.

Document how the decision records will be stored and organized

I like this "MADR" proposal. https://adr.github.io/madr/

I do want to call out that we don't have to go full tilt. The key items needed for record are:

• title
• status
• context
• decision
• consequence / impact

Within the Helm charts, we implemented a minimal form of ADR, which has served us well. Here in this project, I think it may make sense to have individual documents, which are referenced from an index.

Weight Calculation

• 4 from Distribution
• 1 from Quality Assurance
• 1 from Docs
• 1 from Product
• Documentation Unclear or Partial
• No Known Definition of Done
• Requires Architectural Decisions

(4 + 1 + 1 + 1 + 12 + 12 + 4 ) * 4 = 140

set weight to 140

added OrchestratorCodex label

added to epic &4042 (closed)

I was looking at the tools that generate ADRs and it seems like the work on them all stopped in 2018.

I think a minimal thing to do for this project would be to make something simple that can:

1. generate an adr file
2. generate the decisions list page
3. understand that if B supercedes A, then C cannot supercede A too

Iterations

1. do the files manually after figuring out the format
2. figure out how to make a simplistic tool that does the above to maintain it automatically

marked this issue as related to #265

mentioned in issue #265

Opened #265 to discuss the automation part.

Manually converting existing decisions to this model:

Filename: /doc/architecture/decisions/0001_my_decision_record.md per documentation standards for markdown names and standards for file paths extending to create architecture.

# 0001. My Decision Record

Proposed: YYYY-MM-DD
Accepted|Rejected: YYYY-MM-DD
Deprecated|Superceded: YYYY-MM-DD

## Status

Accepted|Proposed|Rejected|Deprecated|Superceded

## Context

Link to initial issue to discuss

Prose describing contexts and constraints that impacted the decision making process.

## Decision

Document the outcome of the change proposal.

## Consequences

List tradeoffs made in this decision.

To handle relationships between decisions, we will do a JSON file named /doc/architecture/decisions/metadata.json that is manually edited until we have a better scope for how to make this more automated.

{
    "superseded": {
        new_decision: old_decision
    }
}

Opened gitlab!38102 (closed) to add the doc/architecture standard to our style guide.

mentioned in commit gitlab@5496e37b

mentioned in merge request gitlab!38102 (closed)

mentioned in commit efb370a8

mentioned in merge request !66 (merged)

Opened !66 (merged) to follow the GitLab style guidelines and put our docs in the doc/ directory instead of the docs/ directory.

added Deliverable priority3 severity3 labels

changed milestone to %13.3

mentioned in commit f646d2c1

mentioned in commit 2a6680e7

mentioned in merge request !67 (merged)

mentioned in commit a05d7a3b

mentioned in commit 0d4e4b20

mentioned in commit 8a4044f6

mentioned in merge request !68 (merged)

mentioned in commit 2240a37b

mentioned in commit ea350a4c

Looking at changelog scripts:

• GitLab repository changelog
• Omnibus repository changelog

These are slightly different, is this intentional, and do we have a source of truth?

Looks like the main difference here is the file it writes changelogs to when differentiating Community versus Enterprise Editions.

I opened !70 (merged) and posted questions to @axil and @yorickpeterse regarding the changelog process and where I'd like to put Orchestrator's changelog files.

mentioned in commit omnibus-gitlab@f44e6728

mentioned in merge request omnibus-gitlab!4464 (closed)

mentioned in commit 3e4317a5

mentioned in merge request !70 (merged)

mentioned in commit 8d3613e9

mentioned in commit 18f834db

mentioned in commit 11d7e4ea

changed the description

assigned to @rmarshall

mentioned in commit 98b427d6

mentioned in merge request !75 (merged)

changed the description

Opened !75 (merged) to document changelog and start a Contributor's guide.

When it merges, this deliverable is concluded.

mentioned in commit 7e3d004b

All work is merged; this can now be closed.

closed

set weight to 18