Reformat changelog preamble, and mention exceptions to the public API
Marco Ricci

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.
... ...
@@ -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