-
Notifications
You must be signed in to change notification settings - Fork 554
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
[Style] Remove "should" not related to conformance #536
Closed
Closed
Changes from 1 commit
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -2,21 +2,21 @@ | |
|
||
## One sentence per line | ||
|
||
To keep consistency throughout the Markdown files in the Open Container spec all files should be formatted one sentence per line. | ||
To keep consistency throughout the Markdown files in the Open Container spec format all files one sentence per line. | ||
This fixes two things: it makes diffing easier with git and it resolves fights about line wrapping length. | ||
For example, this paragraph will span three lines in the Markdown source. | ||
|
||
## Traditionally hex settings should use JSON integers, not JSON strings | ||
## Use JSON integers, not JSON strings, for traditionally hex settings | ||
|
||
For example, [`"classID": 1048577`][class-id] instead of `"classID": "0x100001"`. | ||
The config JSON isn't enough of a UI to be worth jumping through string <-> integer hoops to support an 0x… form ([source][integer-over-hex]). | ||
|
||
## Constant names should keep redundant prefixes | ||
## Keep redundant prefixes for constant names | ||
|
||
For example, `CAP_KILL` instead of `KILL` in [**`linux.capabilities`**][capabilities]. | ||
The redundancy reduction from removing the namespacing prefix is not useful enough to be worth trimming the upstream identifier ([source][keep-prefix]). | ||
|
||
## Optional settings should have pointer Go types | ||
## Have pointer Go types for optional settings | ||
|
||
So we have a consistent way to identify unset values ([source][optional-pointer]). | ||
The exceptions are entries where the Go default for the type is a no-op in the spec, in which case `omitempty` is sufficient and no pointer is needed (sources [here][no-pointer-for-slices], [here][no-pointer-for-boolean], and [here][pointer-when-updates-require-changes]). | ||
|
@@ -26,7 +26,7 @@ The exceptions are entries where the Go default for the type is a no-op in the s | |
### Anchoring | ||
|
||
For any given section that provides a notable example, it is ideal to have it denoted with [markdown headers][markdown-headers]. | ||
The level of header should be such that it is a subheader of the header it is an example of. | ||
The level of header for an example is ideally such that it is a subheader of the header it is an example of. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. This sentence was a bit twisty before. I think “should” vs. “SHOULD” is sufficiently distinct, but if folks want to drop non-SHOULD instances, we could maybe use an imperative like:
|
||
|
||
#### Example | ||
|
||
|
@@ -51,7 +51,7 @@ To use Some Topic, ... | |
|
||
Where necessary, the values in the example can be empty or unset, but accommodate with comments regarding this intention. | ||
|
||
Where feasible, the content and values used in an example should convey the fullest use of the data structures concerned. | ||
Where feasible, the content and values used in an example convey the fullest use of the data structures concerned. | ||
Most commonly onlookers will intend to copy-and-paste a "working example". | ||
If the intention of the example is to be a fully utilized example, rather than a copy-and-paste example, perhaps add a comment as such. | ||
|
||
|
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
“spec format” → “spec, format”