Skip to content

Commit eacc169

Browse files
mattsb42-awsmattsb42-aws
authored
docs: add required examples framing (#143)
* docs: add required examples change doc, requirements spec, and readme spec * docs: expand motivations and non-production comments * docs: autoformat
1 parent 31b0534 commit eacc169

File tree

3 files changed

+211
-0
lines changed

3 files changed

+211
-0
lines changed

‎changes/2020-06-16_required-examples/change.md

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
[//]: # "Copyright Amazon.com Inc. or its affiliates. All Rights Reserved."
2+
[//]: # "SPDX-License-Identifier: CC-BY-SA-4.0"
3+
4+
# Define Required Examples
5+
6+
## Affected Specifications
7+
8+
This serves as a reference of all specification documents that this change affects.
9+
10+
| Specification |
11+
| ----------------------------------------------------- |
12+
| [examples](../../examples/examples.md) |
13+
| [examples readme](../../examples/templates/readme.md) |
14+
15+
## Affected Implementations
16+
17+
This serves as a reference for all implementations that this change affects.
18+
19+
| Language | Repository |
20+
| ---------- | ------------------------------------------------------------------------------------- |
21+
| Python | [aws-encryption-sdk-python](https://github.com/aws/aws-encryption-sdk-python) |
22+
| Java | [aws-encryption-sdk-java](https://github.com/aws/aws-encryption-sdk-java) |
23+
| C | [aws-encryption-sdk-c](https://github.com/aws/aws-encryption-sdk-c) |
24+
| Javascript | [aws-encryption-sdk-javascript](https://github.com/aws/aws-encryption-sdk-javascript) |
25+
26+
## Definitions
27+
28+
### Conventions used in this document
29+
30+
The key words
31+
"MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
32+
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL"
33+
in this document are to be interpreted as described in
34+
[RFC 2119](https://tools.ietf.org/html/rfc2119).
35+
36+
## Summary
37+
38+
This document defines the examples that each implementation MUST include.
39+
40+
## Out of Scope
41+
42+
The specific implementations details for each example
43+
are out of scope for this document.
44+
The template document for each example contains those details.
45+
46+
## Motivation
47+
48+
The primary motivations for requiring examples include:
49+
50+
- Providing guidance to AWS Encryption SDK customers.
51+
- Facilitating documentation and interoperability.
52+
- Encouraging AWS Encryption SDK developers
53+
to work backwards from the caller experience
54+
to verify that APIs and components
55+
provide the intended functionality,
56+
clarity, and ease of use.
57+
- Demonstrating that all implementations
58+
can be used to solve the same problems.
59+
60+
## Drawbacks
61+
62+
Requiring each implementation to include many examples
63+
increases the level of effort to create each implementation.
64+
We believe that the value to customers of
65+
improving the usability of APIs
66+
and providing guidance on how to use them
67+
justifies this cost.
68+
69+
## Security Implications
70+
71+
We MUST assume that any example will be used in production.
72+
Because of this, every example MUST only contain logic
73+
that is reasonable for production use
74+
unless explicitly identified otherwise.
75+
76+
## Operational Implications
77+
78+
Each implementation MUST include all examples
79+
in its continuous integration testing.
80+
81+
## Guide-level Explanation
82+
83+
Every implementation MUST include an example
84+
for each required use-case.
85+
These examples MUST be tested as part of
86+
the implementation's continuous integration testing.
87+
88+
## Reference-level Explanation
89+
90+
- Every example MUST be tested
91+
as part of the implementation's continuous integration testing.
92+
- Every example MUST be independent and complete.
93+
- Every example SHOULD follow a consistent layout and framing.
94+
95+
- ex: Consistent function name and input parameters across examples.
96+
97+
- Every example MUST only contain logic that is reasonable for production use.
98+
- If an example MUST contain logic that is not reasonable for production use,
99+
it MUST include clear comments that
100+
MUST identify that logic as not fit for production use,
101+
SHOULD explain why it is not fit for production use,
102+
and MUST instruct the reader what they SHOULD do instead.
103+
104+
- ex: Raw keyring examples generate wrapping keys as part of the example.
105+
These examples MUST contain guidance that
106+
in production those keys SHOULD be managed by an HSM.

‎examples/examples.md

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
[//]: # "Copyright Amazon.com Inc. or its affiliates. All Rights Reserved."
2+
[//]: # "SPDX-License-Identifier: CC-BY-SA-4.0"
3+
4+
# Required Examples
5+
6+
## Version
7+
8+
0.1.0
9+
10+
### Changelog
11+
12+
- 0.1.0
13+
14+
- [Require examples](../changes/2020-06-16_required-examples/change.md)
15+
16+
## Implementations
17+
18+
- [Python (DEV)](https://github.com/aws/aws-encryption-sdk-python/blob/keyring/examples/)
19+
- [Java (DEV)](https://github.com/aws/aws-encryption-sdk-java/blob/keyring/src/examples/)
20+
21+
## Overview
22+
23+
Every implementation MUST include an example
24+
for each use-case described in [example templates](./templates).
25+
26+
## Definitions
27+
28+
### Conventions used in this document
29+
30+
The key words
31+
"MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
32+
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL"
33+
in this document are to be interpreted as described in
34+
[RFC 2119](https://tools.ietf.org/html/rfc2119).
35+
36+
## Requirements
37+
38+
- Every example MUST be tested
39+
as part of the continuous integration testing.
40+
- Every example MUST be independent and complete.
41+
- Every example SHOULD follow a consistent layout and framing.
42+
43+
- ex: Consistent function name and input parameters across examples.
44+
45+
- Every example MUST only contain logic that is reasonable for production use.
46+
- If an example MUST contain logic that is not reasonable for production use,
47+
it MUST include clear comments identifying that logic as such
48+
and instructing the reader what they SHOULD do instead.
49+
50+
- ex: Raw keyring examples generate wrapping keys as part of the example.
51+
These examples MUST contain guidance that
52+
in production those keys SHOULD be managed by an HSM.

‎examples/templates/readme.md

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
[//]: # "Copyright Amazon.com Inc. or its affiliates. All Rights Reserved."
2+
[//]: # "SPDX-License-Identifier: CC-BY-SA-4.0"
3+
4+
# Examples Section Readme
5+
6+
## Version
7+
8+
0.1.0
9+
10+
### Changelog
11+
12+
- 0.1.0
13+
14+
- [Require examples](../../changes/2020-06-16_required-examples/change.md)
15+
16+
## Implementations
17+
18+
- [Python (DEV)](https://github.com/aws/aws-encryption-sdk-python/blob/keyring/examples/README.md)
19+
- [Java (DEV)](https://github.com/aws/aws-encryption-sdk-java/blob/keyring/src/examples/README.md)
20+
21+
## Overview
22+
23+
Every implementation MUST include a readme
24+
that introduces all examples
25+
and identifies which use-cases
26+
map to which examples.
27+
28+
## Definitions
29+
30+
### Conventions used in this document
31+
32+
The key words
33+
"MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
34+
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL"
35+
in this document are to be interpreted as described in
36+
[RFC 2119](https://tools.ietf.org/html/rfc2119).
37+
38+
## Requirements
39+
40+
The readme MUST contain the following information:
41+
42+
1. A listing of each [API example](./api)
43+
with a short description of the use-case
44+
and a link to the example.
45+
1. A listing of each [configuration example](./configuration)
46+
with a short description of the use-case
47+
and a link to the example.
48+
1. Instructions for developers writing examples
49+
that describe any requirements
50+
(organization/layout/naming/etc)
51+
and any actions that need to be taken
52+
to make sure the continuous integration testing
53+
tests the new examples.

0 commit comments

Comments
 (0)