fakesshagent.git

Initial import of the wishlist spec and index page
Marco Ricci

Marco Ricci commited on 2026-08-31 12:25:51
Zeige 2 geänderte Dateien mit 135 Einfügungen und 0 Löschungen. 

The index page and the specification are taken from commit
7d58f514bb48f92e10365719d73a2217e89fdc9d of `derivepassphrase`, shortly
after the release of version 0.6.1.
index.md
Zeige Datei @ 892cce5
... ... 
@@ -0,0 +1,43 @@
1 
+# Bugs & wishlist items
2 
+
3 
+<small>(… a.k.a. "things to fix" and "things to add".)</small>
4 
+
5 
+!!! abstract inline end "Legend: Formatting"
6 
+      - [scheduled for next release](index.md){: .scheduled-next }
7 
+      - [scheduled for some future release](index.md){: .scheduled }
8 
+      - [yet to be scheduled](index.md){: .unscheduled }
9 
+
10 
+???+ bug "things to fix"
11 
+    <i>no entries</i>
12 
+
13 
+???+ wish "things to add"
14 
+    <i>no entries</i>
15 
+
16 
+??? bug-success "things fixed"
17 
+    <i>no entries</i>
18 
+
19 
+??? wish-success "things added"
20 
+    <i>no entries</i>
21 
+
22 
+??? note "About this wishlist"
23 
+
24 
+    This is the list of bugs and wishes for `fakesshagent`.
25 
+    It uses the same terminology and style as [PuTTY's wishlist][PUTTY_WISHLIST].
26 
+    By design, the list distinguishes solely between bugs and wishes, and focuses strongly on the facts, not on the plans for implementation.[^bug-tracking-concerns]
27 
+    The entries are named, not numbered, and the summaries are written by hand.
28 
+
29 
+    The list is built statically; there is no interactive way to submit entries or commentary on an entry, or to run search queries against the entry database.
30 
+    To submit entries or commentary, contact the authors directly; see the website imprint and the embedded author info in version control.
31 
+    To run search queries or other automated queries against the entry database, check out the `wishlist` branch from version control and parse the entry files directly.
32 
+
33 
+    See also the [entry format specification][ENTRY_SPEC].
34 
+
35 
+[^bug-tracking-concerns]:
36 
+    See also the essay [Separation of concerns in a bug tracker][BUG_TRACKING_CONCERNS] by PuTTY's principal author, Simon Tatham.
37 
+    Like PuTTY, `fakesshagent` is a "more serious free-software hobby project" developed by one principal author who also cannot definitively commit to any specific time plan.
38 
+    As such, `fakesshagent` also does not have a formal plans table (beyond the very coarse <b>Priority</b> field).
39 
+
40 
+  [ENTRY_SPEC]: spec.md
41 
+
42 
+  [PUTTY_WISHLIST]: https://www.chiark.greenend.org.uk/~sgtatham/putty/wishlist/ "PuTTY Known Bugs and Wish List"
43 
+  [BUG_TRACKING_CONCERNS]: https://www.chiark.greenend.org.uk/~sgtatham/quasiblog/bugtracker-separate/ 'Simon Tatham: "Separation of concerns in a bug tracker"'
spec.md
Zeige Datei @ 892cce5
... ... 
@@ -0,0 +1,92 @@
1 
+# bug and wish entry specification
2 
+
3 
+All bug and wish entries consist of a <dfn>header</dfn>, describing the properties of this entry, and a <dfn>summary</dfn> below.
4 
+
5 
+The system is mostly compatible with PuTTY's wishlist; differences are marked below.
6 
+Unlike PuTTY, the entry files are not RFC822-like plain text, but rather Markdown files (with some raw HTML parts), to cleanly integrate with the rest of the documentation.
7 
+(The Markdown+HTML files are still very regular, and thus should still be reasonably parsable.)
8 
+
9 
+## The header
10 
+
11 
+The header is a table with fixed keys.
12 
+For some of the keys, if they have only a fixed amount of values they can take on, then they have a specific interpretation text that accompanies them.
13 
+In the order of appearance:
14 
+
15 
+Summary
16 
+:   A brief description of the bug, in plain text.
17 
+    Comparable to subject lines in e-mail.
18 
+
19 
+Class
20 
+:   What kind of entry is this?[^distinguishing-between-bugs-and-wishes]
21 
+
22 
+    | value  | interpretation                                   |
23 
+    | ------ | ------------------------------------------------ |
24 
+    | `bug`  | This is clearly an actual problem we want fixed. |
25 
+    | `wish` | This is a request for an enhancement.            |
26 
+
27 
+    (Unlike PuTTY, we do not further differentiate between `semi-bug`, `vulnerability` and `bug` at the class level.)
28 
+
29 
+Priority
30 
+:   How urgent is this entry?
31 
+    An anchored ordinal scale with subjective interpretation.
32 
+
33 
+    | value                              | interpretation                                                                |
34 
+    | ---------------------------------- | ----------------------------------------------------------------------------- |
35 
+    | `high`                             | This should be fixed in the next release.                                     |
36 
+    | `medium`                           | This should be fixed one day.                                                 |
37 
+    | `low`                              | We aren't sure whether to fix this or not.                                    |
38 
+    | `historic` (bug), `dormant` (wish) | This issue is old and we don't think it still has value on the main wishlist. |
39 
+    | `never`                            | We don't ever intend to fix this.                                             |
40 
+
41 
+Difficulty
42 
+:   How difficult is this entry to fix/implement?
43 
+    An anchored ordinal scale with subjective interpretation.
44 
+
45 
+    | value    | interpretation                                             |
46 
+    | -------- | ---------------------------------------------------------- |
47 
+    | `fun`    | Just needs tuits, and not many of them.                    |
48 
+    | `tricky` | Needs many tuits.                                          |
49 
+    | `taxing` | Needs external things we don't have (standards, users etc) |
50 
+    | `mayhem` | Probably impossible                                        |
51 
+
52 
+Present-in:
53 
+:   For bugs only: A space-separated list of version numbers (for releases), dates or version control commit IDs (for snapshots) that the bug has been observed in.
54 
+    Dates are formatted as ISO 8601 `YYYY-MM-DD` dates, version numbers and commit IDs in their natural format without additional adornments.
55 
+
56 
+    (PuTTY also factually uses <b>Present-in</b> for wishes.)
57 
+
58 
+Absent-in:
59 
+:   For bugs only: A space-separated list of version numbers (for releases), dates or version control commit IDs (for snapshots) that the bug has been observed *not* in.
60 
+    Same formatting as for <b>Present-in</b>.
61 
+
62 
+Requested-in:
63 
+:   For wishes only: A space-separated list of version numbers (for releases) or version control commit IDs (for snapshots), or a single date that the wish was requested in/on.
64 
+
65 
+    (PuTTY uses <b>Present-in</b> for this purpose.)
66 
+
67 
+Fixed-in:
68 
+:   A space-separated list of version numbers (for releases), dates or version control commit IDs (for snapshots) that the bug was fixed in or the wish was implemented in.
69 
+    Same formatting as for <b>Present-in</b>.
70 
+    Version control commit IDs may be prefixed with `~` to indicate that the bug/wish was confirmed fixed/implemented in this commit <i>or an ancestor commit</i>.
71 
+
72 
+Depends:
73 
+:   A space-separated list of other bug/wish entry names that must be fixed/implemented first.
74 
+
75 
+Blocks:
76 
+:   A space-separated list of other bug/wish entry names that are waiting for this entry to be fixed/implemented.
77 
+
78 
+    (Not documented in PuTTY's wishlist entry specification, but in use across that wishlist.)
79 
+
80 
+[^distinguishing-between-bugs-and-wishes]:
81 
+    A bug is specifically an entry describing an aspect of this software that, if not fixed, impedes or prohibits the user from accomplishing their goal with or within this software.
82 
+    Every other entry is a wish.
83 
+
84 
+## The summary
85 
+
86 
+The summary is a free-form prose summary of the bug or wish.
87 
+It is intended to be easily scannable, like a good commit message, and likely benefits from many of the same writing conventions.
88 
+In particular, the summary *should not* be a chronological listing of events or messages related to this bug or wish, but rather a proper summarization of those events, messages, and related facts and opinions.
89 
+
90 
+Specific to this system, the summary always contains a paragraph beginning with <b>Therefore</b> that describes the action to take for this entry.
91 
+If applicable, a sentence beginning with <b>Until then</b> within that paragraph contains workarounds or partial solutions that will be applied or have already been applied.
92 
+Except for optional historical context that may follow this paragraph and is then hidden by default, the <b>Therefore</b> paragraph is the *last* paragraph of the summary.
0 93