Reformat changelog preamble, and mention exceptions to the public API
Marco Ricci commited on 2025-01-19 22:53:14
Zeige 1 geänderte Dateien mit 29 Einfügungen und 15 Löschungen.
Reformat the changelog preamble into admonitions, instead of a small-print disclaimer-like paragraph. The text largely stays the same, but for the public API, add (module, class) attributes and mention that there are documented implementation details not considered to be part of the public API.
- docs/changelog.md 3f9930b..6b777cb
| ... | ... |
@@ -8,22 +8,36 @@ |
| 8 | 8 |
[KEEP_A_CHANGELOG]: https://keepachangelog.com/en/1.1.0/ 'Keeping a changelog' |
| 9 | 9 |
[SEMANTIC_VERSIONING]: https://semver.org/ 'Using Semantic Versioning' |
| 10 | 10 |
|
| 11 |
+??? info "Definition: the <q>public API</q> of `derivepassphrase`" |
|
| 12 |
+ |
|
| 13 |
+ The <dfn>public API</dfn>, as defined by Semantic Versioning, is |
|
| 14 |
+ outlined in the [Reference section][REFERENCE]: the set of documented |
|
| 15 |
+ modules, classes, attributes, methods, functions and function |
|
| 16 |
+ parameters, and the documented behavior, options and arguments of the |
|
| 17 |
+ command-line tools. |
|
| 18 |
+ |
|
| 19 |
+ Certain **exceptions to this rule** are explicitly and prominently |
|
| 20 |
+ marked as implementation details/not part of the public API. |
|
| 21 |
+ |
|
| 22 |
+??? info "Interpretation of the version number" |
|
| 23 |
+ |
|
| 24 |
+ The terminology <b>major</b>, <b>minor</b> and <b>patch</b> follows the |
|
| 25 |
+ Semantic Versioning and Keep a Changelog definitions. |
|
| 26 |
+ |
|
| 27 |
+ * For version numbers with major version zero, *any* new release may |
|
| 28 |
+ effectively constitute a new <b>major</b> release. |
|
| 29 |
+ * For version numbers with major version one or higher, |
|
| 30 |
+ * <b>Fixed</b> entries justify a <b>patch</b> release; |
|
| 31 |
+ * <b>Added</b> and <b>Deprecated</b> entries justify |
|
| 32 |
+ a <b>minor</b> release; |
|
| 33 |
+ * <b>Changed</b> and <b>Removed</b> entries justify a <b>major</b> |
|
| 34 |
+ release. |
|
| 35 |
+ * <b>Security</b> can justify any type of release; if <b>major</b> |
|
| 36 |
+ or <b>minor</b>, these are accompanied by corresponding entries |
|
| 37 |
+ of the respective types above. |
|
| 38 |
+ |
|
| 11 | 39 |
<aside markdown><small> |
| 12 |
-(All entries are from the perspective of a user, not a developer. |
|
| 13 |
-The <q>public API</q>, as defined by Semantic Versioning, is outlined in the |
|
| 14 |
-[Reference section][REFERENCE]: the set of documented modules, classes, |
|
| 15 |
-methods and functions, and the documented behavior, options and arguments of |
|
| 16 |
-the command-line tools. |
|
| 17 |
-As per the Semantic Versioning and the Keep a Changelog terminology, |
|
| 18 |
-<q>Fixed</q> entries justify a <q>patch</q> release, |
|
| 19 |
-<q>Added</q> and <q>Deprecated</q> entries a <q>minor</q> release, |
|
| 20 |
-and <q>Changed</q> and <q>Removed</q> entries a <q>major</q> release. |
|
| 21 |
-<q>Security</q> can justify any type of release; |
|
| 22 |
-if <q>major</q> or <q>minor</q>, these are accompanied by corresponding |
|
| 23 |
-entries of the respective types above. |
|
| 24 |
-Again as per Semantic Versioning, at major version zero, the above |
|
| 25 |
-justification is not yet binding, and <em>any</em> new release may |
|
| 26 |
-effectively constitute a new <q>major</q> release.) |
|
| 40 |
+(All entries are from the perspective of a user, not a developer.) |
|
| 27 | 41 |
</small></aside> |
| 28 | 42 |
|
| 29 | 43 |
[REFERENCE]: reference/index.md |
| 30 | 44 |