Conventions used for specification, documentation, and code.
| Must | Should | Optional | |
|---|---|---|---|
| Specifications | ✔ | ❌ | ❌ |
| User Documentation | ❌ | ❌ | ❌ |
| Handbooks | ✔ | ✔ | ❌ |
| Runbooks | ❌ | ❌ | ✔ |
| Cookbooks | ❌ | ❌ | ❌ |
| Source Code | ❌ | ❌ | ❌ |
Documents using the Keywords section MUST use include the following text in it’s own section named Keywords.
The key words MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this specification are to be interpreted as described in RFC2119.
Since a document and project of this nature deals with a large number of technologies, each with their own set of acronyms, please refer to the glossary in Appendix A, which briefly explains some of them.
Formal grammers are given in this specification using a simple Extended Backus-Naur Form (EBNF) notation described in RFC4234. Further information and links can be found in the Wikipedia article Extended Backus–Naur Form.
The following code was in a comment on Stack Overflow:
(define-generic-mode 'bnf-mode
() ;; comment char: inapplicable because # must be at start of line
nil ;; keywords
'(
("^#.*" . 'font-lock-comment-face) ;; comments at start of line
("^<.*?>" . 'font-lock-function-name-face) ;; LHS nonterminals
("<.*?>" . 'font-lock-builtin-face) ;; other nonterminals
("::=" . 'font-lock-const-face) ;; "goes-to" symbol
("\|" . 'font-lock-warning-face) ;; "OR" symbol
("\{:\\|:\}" . 'font-lock-keyword-face) ;; special pybnf delimiters
)
'("\\.bnf\\'" "\\.pybnf\\'") ;; filename suffixes
nil ;; extra function hooks
"Major mode for BNF highlighting.")- RFC4234
- Wikipedia: Extended Backus–Naur Form
- BNF Examples
- http://condor.depaul.edu/ichu/csc447/notes/wk3/BNF.pdf
- http://www.ics.uci.edu/~pattis/ICS-33/lectures/ebnf.pdf
All dates SHOULD be written using ISO8601 format, unless a good reason to do otherwise. When using another date format the date must be unambigious.
Date formats are one of the oldest and thorniest problems in computing.
ISO8601 format is as follows:
YYYY-MM-DD
Compare this to the American convention:
10-10-10
This example could be any of, 10 January 1910, 10 January 2010, 10 October, 1910 or 10 October 2010.
The matter of Version numbers for software and documentation comprise no small amount of weeping and knashing of teeth so let’s make this clear and simple. All Version numbers MUST conform to the Semantic Versioning v2.0.0 specification. From the spec:
Given a version number MAJOR.MINOR.PATCH, increment the:
- MAJOR version when you make incompatible API changes,
- MINOR version when you add functionality in a backwards-compatible manner, and
- PATCH version when you make backwards-compatible bug fixes.
Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.
Version numbers SHOULD append a lower case letter v to version numbers unless there is a sound reason to do otherwise.
The EBNF definition for Semantic Version Numbers:
digit ::= 0 |1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
major ::= <digit>+
minor ::= <digit>+
patch ::= <digit>+
semantic-version ::= v<major>.<minor>.<patch> These rules are based on but not necessarily limited to pre-existing widespread common practices in use in both closed and open-source software. For this system to work, you first need to declare a public API. This may consist of documentation or be enforced by the code itself. Regardless, it is important that this API be clear and precise. Once you identify your public API, you communicate changes to it with specific increments to your version number. Consider a version format of X.Y.Z (Major.Minor.Patch). Bug fixes not affecting the API increment the patch version, backwards compatible API additions/changes increment the minor version, and backwards incompatible API changes increment the major version.
I call this system “Semantic Versioning.” Under this scheme, version numbers and the way they change convey meaning about the underlying code and what has been modified from one version to the next.
- software
- documentation
http://keepachangelog.com/en/0.3.0/
- all lower case
- short