Open mattsb42-aws opened 4 years ago
The general pattern that we have settled on for repo organization is:
YYYY-MM-DD_NAME
, identifying the date when the change was proposed and a name that summarizes the change.Open questions:
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.
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).
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.
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: