document spec change doc format and process

[mattsb42-aws]

Before we define this as "1.0", we need to document how to make changes to the spec and what process we use to take a change from idea to proposal to acceptance.

We've been roughly following a sketch of a process that I put together before we had an opportunity to try following it, and unsurprisingly, we've been finding places where it needs to change before being finalized here.

Points we need to hit include:

• [ ] Templates for changes
• [ ] Templates for PRs
• [ ] Templates for issues
• [ ] Repo organization (where to changes go, how to they reflect on spec docs, etc)
• [ ] Process for accepting a change into the spec
• [ ] Process for accepting a proposal that needs more review before integrating into the spec

[mattsb42-aws]

Organization

The general pattern that we have settled on for repo organization is:

• Spec documents (currently in "client-apis", "data-format", and "framework") describe the current state of the specification. Each spec document MUST contain a version and a changelog that describes what changed in each version with a link to the accepted change document that introduced that change.
• Change documents describe a change to the specification. Each change document MAY affect multiple spec documents.
• Accepted change documents are found in the "changes" directory.
• Each change has a dedicated directory with a name matching the pattern YYYY-MM-DD_NAME, identifying the date when the change was proposed and a name that summarizes the change.

Open questions:

• [ ] Do we want to collect all spec documents under a common parent directory to more clearly differentiate them from changes/etc?
• [ ] Where do proposed changes go?

[mattsb42-aws]

Templates for changes

The template that I have been using is:

[//]: # "Copyright Amazon.com Inc. or its affiliates. All Rights Reserved."
[//]: # "SPDX-License-Identifier: CC-BY-SA-4.0"

# TITLE GOES HERE

## Affected Features

This serves as a reference of all features that this change affects.

| Feature |
| ------- |

## Affected Specifications

This serves as a reference of all specification documents that this change affects.

| Specification |
| ------------- |

## Affected Implementations

This serves as a reference for all implementations that this change affects.

| Language   | Repository                                                                            |
| ---------- | ------------------------------------------------------------------------------------- |
| Python     | [aws-encryption-sdk-c](https://github.com/aws/aws-encryption-sdk-python)              |
| Java       | [aws-encryption-sdk-javascript](https://github.com/aws/aws-encryption-sdk-java)       |
| C          | [aws-encryption-sdk-c](https://github.com/aws/aws-encryption-sdk-c)                   |
| Javascript | [aws-encryption-sdk-javascript](https://github.com/aws/aws-encryption-sdk-javascript) |

## Definitions

Include any definitions of terms here.

### Conventions used in this document

The key words
"MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL"
in this document are to be interpreted as described in
[RFC 2119](https://tools.ietf.org/html/rfc2119).

## Summary

Short, 1-2 paragraph summary of this change.

## Out of Scope

What is this _not_?

## Motivation

Why did we do this? What problems did it solve?

## Drawbacks

What problems were introduced by this change, or what gaps in the original problems does
it leave open?

## Security Implications

Are there any security implications introduced by this change?

## Operational Implications

Are there any operational implications introduced by this change?

## Guide-level Explanation

Explain the change as it should be implemented as if you were teaching it to another developer
who wants to use the changed features. This generally includes:

- Introducing concepts.
- Explaining the change in terms of examples.
- Explaining how developers should think about the changed features.
- Explain any data structures that the change requires.
- If applicable, describe the differences between teaching this to new users and existing users.

## Reference-level Explanation

Explain the design in sufficient detail that a developer
already familiar with a given implementation
could implement this change without referencing other implementations.
This should include:

- Any new features.
- Any interactions with existing features.
- Any changes that this makes to interactions between other, related, features.
- Required API shapes.

    - note: specifically not exact names for any given language

- Edge cases to be aware of that might influence implementation-specific design.

    - Ex: Cryptographic materials managers should return raw keys rather than constructs
      that use those keys to simplify the interface between a caching CMM and a cache. Those
      raw keys must use a standard format to ensure that an off-box cache can be shared by
      multiple clients across implementations.

[robin-aws]

One point to address explicitly: change.md documents will contain links that may break over time as features or sub-sections are sometimes removed.

I propose that we still use relative links withing change documents and accept the fact that they may be invalid in future versions. Personally I'm even fine with a change that removes something linking to where it was previously (i.e. links that are immediately broken).

[acioc]

One point to address explicitly: change.md documents will contain links that may break over time as features or sub-sections are sometimes removed.

I propose that we still use relative links withing change documents and accept the fact that they may be invalid in future versions. Personally I'm even fine with a change that removes something linking to where it was previously (i.e. links that are immediately broken).

I'm against the idea of allowing broken links. I believe we should have a static checker that verifies link validity and blocks merges that break links - this ensures that whoever breaks the links (for example renames headers or a document) properly updates their relevant usage.