derivepassphrase.git

Add links and anchors for version/upgrade information and changelog sections
Parent 47c8e07
Marco Ricci

Marco Ricci commited on 2025-01-23 10:53:54
Zeige 4 geänderte Dateien mit 135 Einfügungen und 28 Löschungen. 

Add separate documentation pages for Python version information and
`derivepassphrase` upgrade notes.  Apart from the informative aspect, it
also serves as an anchor which all code upgrade tasks and TODOs that
belong to the same upgrade step can link to, and which can then be
grepped for in the code.

Relatedly, give the changelog proper, systematic, non-auto-generated
anchor targets.
docs/changelog.md
Zeige Datei @ 5bb568d
... ... 
@@ -44,9 +44,9 @@
44 44
45 45 
 <!-- scriv changelog start -->
46 46
47 
-## 0.4.0 (2025-01-07)
47 
+## 0.4.0 (2025-01-07)  {#v0.4.0}
48 48
49 
-### Added
49 
+### Added  {#added-in-v0.4.0}
50 50
51 51 
   - Both `derivepassphrase vault` and `derivepassphrase export vault` now
52 52 
     support changing the amount of diagnostic output they emit via new
... ... 
@@ -96,7 +96,7 @@
96 96
97 97 
 [tomli]: https://pypi.org/project/tomli/
98 98
99 
-### Changed
99 
+### Changed  {#changed-in-v0.4.0}
100 100
101 101 
   - Calling
102 102 
     [`derivepassphrase_export`][derivepassphrase.cli.derivepassphrase_export],
... ... 
@@ -125,9 +125,9 @@
125 125 
 [MIT]: https://spdx.org/licenses/MIT.html
126 126 
 [zlib/libpng]: https://spdx.org/licenses/Zlib.html
127 127
128 
-## 0.3.3 (2024-11-28)
128 
+## 0.3.3 (2024-11-28)  {#v0.3.3}
129 129
130 
-### Added
130 
+### Added  {#added-in-v0.3.3}
131 131
132 132 
   - Checking whether an SSH key is suitable now also depends on the SSH
133 133 
     agent in use.
... ... 
@@ -137,33 +137,33 @@
137 137 
     If not given, then the old behavior is retained: SSH keys are suitable
138 138 
     if they are suitable under any (conforming) SSH agent.
139 139
140 
-### Fixed
140 
+### Fixed  {#fixed-in-v0.3.3}
141 141
142 142 
   - If the SSH agent supports deterministic DSA/ECDSA signatures (e.g.
143 143 
     [RFC 6979][]), then mark DSA and ECDSA SSH keys as suitable.
144 144
145 145 
 [RFC 6979]: https://www.rfc-editor.org/rfc/rfc6979
146 146
147 
-## 0.3.2 (2024-10-21)
147 
+## 0.3.2 (2024-10-21)  {#v0.3.2}
148 148
149 
-### Fixed
149 
+### Fixed  {#fixed-in-v0.3.2}
150 150
151 151 
   - _*Actually* actually_ remove the `derivepassphrase_export` program,
152 152 
     which was turned into a subcommand in v0.2.0 and supposed to have been
153 153 
     removed in v0.3.1 already.
154 154 
     Removed on disk is not the same as removed in version control.
155 155
156 
-## 0.3.1 (2024-10-21)
156 
+## 0.3.1 (2024-10-21)  {#v0.3.1}
157 157
158 
-### Fixed
158 
+### Fixed  {#fixed-in-v0.3.1}
159 159
160 160 
   - Fix PyPI classification: Python 3.9 is supported.
161 161 
   - *Actually* remove the `derivepassphrase_export` program, which was
162 162 
     turned into a subcommand in v0.2.0.
163 163
164 
-## 0.3.0 (2024-10-15)
164 
+## 0.3.0 (2024-10-15)  {#v0.3.0}
165 165
166 
-### Added
166 
+### Added  {#added-in-v0.3.0}
167 167
168 168 
   - Convert changelog management from towncrier to [scriv][].
169 169 
   - Add SSH agent spawning support to the test suite.
... ... 
@@ -190,7 +190,7 @@
190 190 
 [hypothesis]: https://pypi.org/project/hypothesis/
191 191 
 [scriv]: https://pypi.org/project/scriv
192 192
193 
-### Changed
193 
+### Changed  {#changed-in-v0.3.0}
194 194
195 195 
   - Change links to point to public project repositories, if possible.
196 196 
     For legal reasons.
... ... 
@@ -260,15 +260,15 @@
260 260 
 [#16]: https://github.com/the-13th-letter/derivepassphrase/issues/16
261 261 
 [#17]: https://github.com/the-13th-letter/derivepassphrase/issues/17
262 262
263 
-### Fixed
263 
+### Fixed  {#fixed-in-v0.3.0}
264 264
265 265 
   - Fixed the textual description of the return value for
266 266 
     [`SSHAgentClient.request`][derivepassphrase.ssh_agent.SSHAgentClient.request],
267 267 
     which didn't match the declared type annotation.
268 268
269 
-## 0.2.0 (2024-09-12)
269 
+## 0.2.0 (2024-09-12)  {#v0.2.0}
270 270
271 
-### Added
271 
+### Added  {#added-in-v0.2.0}
272 272
273 273 
   - Support configuration data export from `vault` in v0.2, v0.3 and
274 274 
     storeroom formats.
... ... 
@@ -279,7 +279,7 @@
279 279
280 280 
 [#1]: https://github.com/the-13th-letter/derivepassphrase/1
281 281
282 
-### Fixed
282 
+### Fixed  {#fixed-in-v0.2.0}
283 283
284 284 
   - Deploy versioned documentation with [mike][].
285 285 
     Set up a "latest" tag and the "0.<var>x</var>" version of the
... ... 
@@ -287,7 +287,7 @@
287 287
288 288 
 [mike]: https://pypi.org/project/mike
289 289
290 
-### Changed
290 
+### Changed  {#changed-in-v0.2.0}
291 291
292 292 
   - Changed `sequin` and `ssh_agent_client` to be submodules of
293 293 
     `derivepassphrase`.
... ... 
@@ -329,15 +329,15 @@
329 329 
 [#10]: https://github.com/the-13th-letter/derivepassphrase/10
330 330 
 [#11]: https://github.com/the-13th-letter/derivepassphrase/11
331 331
332 
-### Deprecated
332 
+### Deprecated  {#deprecated-in-v0.2.0}
333 333
334 
-  - Using the implied subcommand or the implied global configuration file is
334 
+  - Using the implied subcommand or the implied global settings file is
335 335 
     deprecated, and will be removed in v1.0.
336 336
337 337
338 
-## 0.1.3 (2024-07-28)
338 
+## 0.1.3 (2024-07-28)  {#v0.1.3}
339 339
340 
-### Fixed
340 
+### Fixed  {#fixed-in-v0.1.3}
341 341
342 342 
   - Do not crash upon selecting a key on the command-line if there already
343 343 
     is a key stored in the configuration.
... ... 
@@ -358,9 +358,9 @@
358 358 
 [#8]: https://github.com/the-13th-letter/derivepassphrase/8
359 359
360 360
361 
-## 0.1.2 (2024-07-22)
361 
+## 0.1.2 (2024-07-22)  {#v0.1.2}
362 362
363 
-### Fixed
363 
+### Fixed  {#fixed-in-v0.1.2}
364 364
365 365 
   - Include and exclude the correct files in the `sdist` and `wheel`
366 366 
     distributions.
... ... 
@@ -376,9 +376,9 @@
376 376 
     [towncrier](https://pypi.org/package/towncrier).
377 377
378 378
379 
-## 0.1.1 (2024-07-14)
379 
+## 0.1.1 (2024-07-14)  {#v0.1.1}
380 380
381 
-### Fixed
381 
+### Fixed  {#fixed-in-v0.1.1}
382 382
383 383 
   - Restore the `__version__` attribute in all top-level packages.
384 384 
   - Declare compatibility with Python 3.10 in project metadata, and include
... ... 
@@ -387,8 +387,8 @@
387 387 
     metadata and the Python package metadata.
388 388
389 389
390 
-## 0.1.0 (2024-07-14)
390 
+## 0.1.0 (2024-07-14)  {#v0.1.0}
391 391
392 
-### Added
392 
+### Added  {#added-in-v0.1.0}
393 393
394 394 
   - Initial release.
docs/pycompatibility.md
Zeige Datei @ 5bb568d
... ... 
@@ -0,0 +1,61 @@
1 
+# Compatibility of `derivepassphrase` with different Python versions
2 
+
3 
+## Python 3.14  {#py3.14}
4 
+
5 
+Not yet supported.
6 
+As of 2025-01, Python 3.14 is still in alpha stage.
7 
+
8 
+## Python 3.13  {#py3.13}
9 
+
10 
+Currently supported without any known issues.
11 
+
12 
+## Python 3.12  {#py3.12}
13 
+
14 
+Currently supported without any known issues.
15 
+
16 
+## Python 3.11  {#py3.11}
17 
+
18 
+Currently supported without any known issues.
19 
+
20 
+### After end-of-life {#after-eol-py3.11}
21 
+
22 
+After Python 3.11 reaches end-of-life, future `derivepassphrase` versions may make use of the following Python functionality:
23 
+
24 
+  * complex expressions in f-strings
25 
+  * type parameter syntax and the `type` statement
26 
+
27 
+## Python 3.10  {#py3.10}
28 
+
29 
+Currently supported without any known issues.
30 
+
31 
+Some functionality requires backported libraries (`tomllib`/`tomli`).
32 
+
33 
+### After end-of-life {#after-eol-py3.10}
34 
+
35 
+After Python 3.10 reaches end-of-life, future `derivepassphrase` versions may make use of the following Python functionality:
36 
+
37 
+  * exception groups
38 
+  * exception notes
39 
+  * [`contextlib.chdir`][]
40 
+
41 
+## Python 3.9  {#py3.9}
42 
+
43 
+Currently supported without any known issues.
44 
+
45 
+Some functionality requires backported libraries (`tomllib`/`tomli`).
46 
+
47 
+### After end-of-life {#after-eol-py3.9}
48 
+
49 
+After Python 3.9 reaches end-of-life, future `derivepassphrase` versions may make use of the following Python functionality:
50 
+
51 
+  * structural pattern matching (`match`/`case` blocks)
52 
+  * parenthesized `with` statements
53 
+
54 
+## Python 3.8 and below  {#py3.8-and-below}
55 
+
56 
+These versions were never explicitly supported, neither in CPython nor in PyPy.
57 
+The same versions as for [Python 3.9](#py3.9) may work, but this is untested.
58 
+
59 
+## PyPy
60 
+
61 
+As per the respective CPython version above.
docs/upgrade-notes.md
Zeige Datei @ 5bb568d
... ... 
@@ -0,0 +1,43 @@
1 
+# Upgrade notes for `derivepassphrase`
2 
+
3 
+(Oldest version first.)
4 
+
5 
+## Upgrading to 1.0 {#upgrading-to-v1.0}
6 
+
7 
+### Remove implicit subcommand calls {#v1.0-implied-subcommands}
8 
+
9 
+`derivepassphrase` will throw an error if the selected command or subcommand requires a subcommand of its own.
10 
+This affects `derivepassphrase` and `derivepassphrase export`.
11 
+
12 
+~~~~ shell-session
13 
+$ derivepassphrase -p service-name        # deprecated
14 
+$ derivepassphrase export -f v0.2 .vault  # deprecated
15 
+~~~~
16 
+
17 
+To avoid this, specify the subcommand explicitly.
18 
+The default subcommand in both cases is `vault`, so use `derivepassphrase vault ...` and `derivepassphrase export vault ...` instead.
19 
+
20 
+~~~~ shell-session
21 
+$ derivepassphrase vault -p service-name
22 
+$ derivepassphrase export vault -f v0.2 .vault
23 
+~~~~
24 
+
25 
+### Do not use the old `settings.json` config file {#v1.0-old-settings-file}
26 
+
27 
+`derivepassphrase` has multiple subcommands.
28 
+The old settings file `$DERIVEPASSPHRASE_PATH/settings.json` suggests that this is a global file for `derivepassphrase`, but in fact it is specific to the `vault` subcommand.
29 
+
30 
+Do not use this file; use the `vault` subcommand-specific configuration file `$DERIVEPASSPHRASE_PATH/vault.json` instead.
31 
+The file format is identical.
32 
+Existing `settings.json` files can be renamed to `vault.json` directly.
33 
+
34 
+`derivepassphrase` versions between 0.2.0 (inclusive) and 1.0 (exclusive) will attempt to migrate/rename the file automatically.
35 
+
36 
+### Do not use the `allow_derivepassphrase_extensions` vault config validator option {#v1.0-allow-derivepassphrase-extensions}
37 
+
38 
+The `allow_derivepassphrase_extensions` keyword argument to [`derivepassphrase._types.validate_vault_config`][] is without effect since `derivepassphrase` version 0.4.0.
39 
+No extensions are defined as of version 0.4.0.
40 
+
41 
+The only historic extension ever defined, which deals with storing Unicode normalization preferences, is a configuration option in the user configuration file in version 0.4.0 and higher:
42 
+`vault.SERVICE.unicode-normalization-form` (if set) for the service <var>SERVICE</var>, otherwise `vault.default-unicode-normalization-form`.
43 
+The latter defaults to `"NFC"`.
mkdocs.yml
Zeige Datei @ 5bb568d
... ... 
@@ -115,7 +115,10 @@ nav:
115 115 
   - Design & Background:
116 116 
     - explanation/index.md
117 117 
     - '"altered versions" license requirement': explanation/faq-altered-versions.md
118 
+  - Changelog:
118 119 
     - Changelog: changelog.md
120 
+    - Upgrade notes: upgrade-notes.md
121 
+    - Python compatibility: pycompatibility.md
119 122 
 exclude_docs: |
120 123 
   changelog.d
121 124 
 not_in_nav: |
122 125