derivepassphrase.git

@@ -42,6 +42,24 @@

       - [scheme-specific-cli-and-config][]{: .fixed }

       - [test-suite-isolated-ssh-agent][]{: .fixed }

+??? note "About this wishlist"

+

+    This is the list of bugs and wishes for `derivepassphrase`.

+    It uses the same terminology and style as [PuTTY's wishlist][PUTTY_WISHLIST].

+    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]

+    The entries are named, not numbered, and the summaries are written by hand.

+

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

+    To submit entries or commentary, contact the authors directly; see the website imprint and the embedded author info in version control.

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

+

+    See also the [entry format specification][ENTRY_SPEC].

+

+[^bug-tracking-concerns]:

+    See also the essay [Separation of concerns in a bug tracker][BUG_TRACKING_CONCERNS] by PuTTY's principal author, Simon Tatham.

+    Like PuTTY, `derivepassphrase` is a "more serious free-software hobby project" developed by one principal author who also cannot definitively commit to any specific time plan.

+    As such, `derivepassphrase` also does not have a formal plans table (beyond the very coarse <b>Priority</b> field).

+

   [allow-all-unicode-passphrases]: allow-all-unicode-passphrases.md

   [amend-vault-config]: amend-vault-config.md

   [better-error-messages]: better-error-messages.md

@@ -68,3 +86,8 @@

   [test-filesystem-isolation]: test-filesystem-isolation.md

   [test-suite-isolated-ssh-agent]: test-suite-isolated-ssh-agent.md

   [windows-ssh-agent-support]: windows-ssh-agent-support.md

+

+  [ENTRY_SPEC]: spec.md

+

+  [PUTTY_WISHLIST]: https://www.chiark.greenend.org.uk/~sgtatham/putty/wishlist/ "PuTTY Known Bugs and Wish List"

+  [BUG_TRACKING_CONCERNS]: https://www.chiark.greenend.org.uk/~sgtatham/quasiblog/bugtracker-separate/ 'Simon Tatham: "Separation of concerns in a bug tracker"'

@@ -0,0 +1,92 @@

+# bug and wish entry specification

+

+All bug and wish entries consist of a <dfn>header</dfn>, describing the properties of this entry, and a <dfn>summary</dfn> below.

+

+The system is mostly compatible with PuTTY's wishlist; differences are marked below.

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

+(The Markdown+HTML files are still very regular, and thus should still be reasonably parsable.)

+

+## The header

+

+The header is a table with fixed keys.

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

+In the order of appearance:

+

+Summary

+:   A brief description of the bug, in plain text.

+    Comparable to subject lines in e-mail.

+

+Class

+:   What kind of entry is this?[^distinguishing-between-bugs-and-wishes]

+

+    | value  | interpretation                                   |

+    | ------ | ------------------------------------------------ |

+    | `bug`  | This is clearly an actual problem we want fixed. |

+    | `wish` | This is a request for an enhancement.            |

+

+    (We do not differentiate `semi-bug`, `vulnerability` and `bug` at the class level.)

+

+Priority

+:   How urgent is this entry?

+    An anchored ordinal scale with subjective interpretation.

+

+    | value                              | interpretation                                                                |

+    | ---------------------------------- | ----------------------------------------------------------------------------- |

+    | `high`                             | This should be fixed in the next release.                                     |

+    | `medium`                           | This should be fixed one day.                                                 |

+    | `low`                              | We aren't sure whether to fix this or not.                                    |

+    | `historic` (bug), `dormant` (wish) | This issue is old and we don't think it still has value on the main wishlist. |

+    | `never`                            | We don't ever intend to fix this.                                             |

+

+Difficulty

+:   How difficult is this entry to fix/implement?

+    An anchored ordinal scale with subjective interpretation.

+

+    | value    | interpretation                                             |

+    | -------- | ---------------------------------------------------------- |

+    | `fun`    | Just needs tuits, and not many of them.                    |

+    | `tricky` | Needs many tuits.                                          |

+    | `taxing` | Needs external things we don't have (standards, users etc) |

+    | `mayhem` | Probably impossible                                        |

+

+Present-in:

+:   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.

+    Dates are formatted as ISO 8601 `YYYY-MM-DD` dates, version numbers and commit IDs in their natural format without additional adornments.

+

+    (PuTTY also factually uses <b>Present-in</b> for wishes.)

+

+Absent-in:

+:   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.

+    Same formatting as for <b>Present-in</b>.

+

+Requested-in:

+:   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.

+

+    (PuTTY uses <b>Present-in</b> for this purpose.)

+

+Fixed-in:

+:   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.

+    Same formatting as for <b>Present-in</b>.

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

+

+Depends:

+:   A space-separated list of other bug/wish entry names that must be fixed/implemented first.

+

+Blocks:

+:   A space-separated list of other bug/wish entry names that are waiting for this entry to be fixed/implemented.

+

+    (Not documented in PuTTY's wishlist entry specification, but in use across that wishlist.)

+

+[^distinguishing-bugs-and-wishes]:

+    A bug is specifically an entry describing an aspect of `derivepassphrase` that, if not fixed, impedes or prohibits the user from accomplishing their goal within `derivepassphrase`.

+    Every other entry is a wish.

+

+## The summary

+

+The summary is a free-form prose summary of the bug or wish.

+It is intended to be easily scannable, like a good commit message, and likely benefits from many of the same writing conventions.

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

+

+Specific to this system, the summary always contains a paragraph beginning with <b>Therefore</b> that describes the action to take for this entry.

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

+Except for optional historical context that may follow this paragraph and may be interactively hidden, the <b>Therefore</b> paragraph is the *last* paragraph of the summary.