Re: Review of debputy editor provided docs for packagers
Richard Lewis wrote:
Thanks for the extra pair of eyes!
>>> #. completion (etc.)
>>> #: src/debputy/lsp/data/debian_control_reference_data.yaml
>>> msgctxt "Stanza:Package|Field:Description"
>>> msgid "Package synopsis and description"
>>> msgstr ""
>>>
>>> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
>>> #. hover docs (etc.)
>>> #: src/debputy/lsp/data/debian_control_reference_data.yaml
>>> #, python-brace-format
>>> msgctxt "Stanza:Package|Field:Description"
>>> msgid ""
>>> "A human-readable description of the package. This field consists of two related but distinct parts.\n"
>
> "related but distinct" seems unneccssary here
Oh, yes, I commented about the "several distinct but very important
rules" later but this line didn't catch my attention, possibly because
the relationship between the two parts of a package description really
is a bit subtle and might deserve some verbiage.
>>> "\n"
>>> "The first line immediately after the field is called the *Synopsis* and is a short \"noun-phrase\"\n"
>>> "intended to provide a one-line summary of the package. The lines after the *Synopsis* is known\n"
>>> "as the *Extended Description* and is intended as a longer summary of the package.\n"
>>> "\n"
>>> "**Example**:\n"
>>> "```\n"
>>> "Description: documentation generator for Python projects\n"
>>> " Sphinx is a tool for producing documentation for Python projects, using\n"
>>> " reStructuredText as markup language.\n"
>>> " .\n"
>>> " Sphinx features:\n"
>>> " * HTML, CHM, LaTeX output,\n"
>>> " * Cross-referencing source code,\n"
>>> " * Automatic indices,\n"
>>> " * Code highlighting, using Pygments,\n"
>>> " * Extensibility. Existing extensions:\n"
>>> " - automatic testing of code snippets,\n"
>>> " - including docstrings from Python modules.\n"
>>> " .\n"
>>> " Build-depend on sphinx if your package uses /usr/bin/sphinx-*\n"
>>> " executables. Build-depend on python3-sphinx if your package uses\n"
>>> " the Python API (for instance by calling python3 -m sphinx).\n"
>>> "```\n"
(Looking through the package lists again I see that python-sphinx and
libjs-sphinx do in fact have this text in full; but it's abbreviated
in sphinx-common and sphinx-doc, when I'd have thought a -doc package
should get a *longer* explanation if anything. Still, that isn't what
I'm meant to be critiquing just now.)
> You should add a link to Justin's style guide to help people write these better!
And I should give that style guide a proper overhaul.
>>> #. [Synopsis] One-line description for the value "yes" [Plaintext]. Shown with
>>> #. completion (etc.)
>>> #: src/debputy/lsp/data/debian_control_reference_data.yaml
>>> msgctxt "Stanza:Package|Field:Protected"
>>> msgid "Prevent trivial uninstallation of the package"
>>> msgstr ""
>
> why "trivial", is there a "non-trivial" installation ??
As in, uninstalling the package just on a whim expecting the results
to be trivial. Maybe the word ought to be "casual"?
>>> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
>>> #. hover docs (etc.)
>>> #: src/debputy/lsp/data/debian_control_reference_data.yaml
>>> #, python-brace-format
>>> msgctxt "Stanza:Package|Field:Homepage"
>>> msgid ""
>>> "Link to the upstream homepage for this binary package.\n"
>
> in the other message it used URL (mostly)
And since the field is called "homepage", the word homepage is a bit
redundant. The synopsis says "Upstream homepage URL for this binary
package" while the hover-docs have "Link to the upstream homepage for
this binary package"... Why not the other way round, a nice concise
"Upstream URL for this binary package" in the synopsis then "Link" (or
rather: it "Links") "to the upstream homepage URL for this binary
package" in the hover-docs.
>>> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
>>> #. completion (etc.)
>>> #: src/debputy/lsp/data/debian_copyright_reference_data.yaml
>>> msgctxt "Stanza:Header|Field:Format"
>>> msgid "Declare the file uses the DEP-5 specification and which version"
>>> msgstr ""
>>
>> msgid "Declares that the file uses the DEP-5 specification, and which version"
>
> Seems like an incomplete sentence to me, which version of what - the package or DEP-5?
If it had more room it could be "Declares that the file uses the DEP-5
specification, and if so, which DEP-5 version". In fact it would be
two characters shorter as
msgid "Declares that the file uses the DEP-5 spec (and which DEP-5 version)"
but I'm not keen on "spec".
>>> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
>>> #. hover docs (etc.)
>>> #: src/debputy/lsp/data/debian_copyright_reference_data.yaml
>>> #, python-brace-format
>>> msgctxt "Stanza:Header|Field:Format"
>>> msgid ""
>>> "URI of the format specification. The field that should be used for the current version of this\n"
>>> "document is:\n"
>>> "\n"
>>> "**Example**:\n"
>>> "```\n"
>>> "Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/\n";
>>> "```\n"
>>> "\n"
>>> "The original version of this specification used the non-https version of this URL as its URI, namely:\n"
>>> "\n"
>>> "```\n"
>>> "Format: http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/\n";
>
> Do we need to know the stuff about the old url?
Maybe: it's explaining that the outdated URL has been "grandfathered
in" as valid to avoid making old packages unnecessarily buggy.
>>> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
>>> #. completion (etc.)
>>> #: src/debputy/lsp/data/debian_copyright_reference_data.yaml
>>> msgctxt "Stanza:Header|Field:License"
>>> msgid "Provide license information for the package as a whole"
>
> why "as a whole"? does some other field provide it for part of a
> package? do you mean "source package"?
The system is, you can define an "overall" license, and then pick out
particular components as exceptions (since they might have different
contributors and copyright dates and so on).
>> "Using `Copyright` in the `Header` stanza is useful when it records a notable difference or simplification\n"
>> "of the other files' `Copyright` fields, but it is not useful when it merely aggregates those fields.\n"
>>
>>> "\n"
>>> "Any formatting is permitted. Simple cases often end up effectively being one copyright holder per\n"
>>> "line; see the examples below for some ideas for how to structure the field to make it easier to read.\n"
>>> "\n"
>>> "If a work has no copyright holder (i.e., it is in the public domain), that information should be recorded\n"
>
> is "i.e" correct - arnt there other ways it could have no copyright holder, eg being old enough?
It is at least closer to "i.e." than "e.g." - if it's old enough for
copyright to have expired then it becomes public domain. It's
possible for things to not be covered by copyright because they're too
trivial to count as creative works, but then again it's normal to call
those "public domain" too.
>>> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
>>> #. hover docs (etc.)
>>> #: src/debputy/lsp/data/debian_copyright_reference_data.yaml
>>> #, python-brace-format
>>> msgctxt "Stanza:Header|Field:Files-Excluded"
>>> msgid ""
>>> "Remove the listed files from the tarball when repacking (commonly via `uscan`). This can be useful\n"
>>> "when the listed files are non-free but not necessary for the Debian package. In this case, the\n"
>>> "upstream version of the package should generally end with `~dfsg` or `+dfsg` (to mark the content\n"
>
> can you pick one of ~dfsg or +dfsg to recommend?
They have different effects, so the circumstances where you'd use them
get several paragraphs of explanation in Debian Policy 5.6.12.2.
>>> "**Example**:\n"
>>> "```\n"
>>> "Files-Excluded: exclude-this\n"
>>> " exclude-dir\n"
>>> " */exclude-dir\n"
>>> " .*\n"
>>> " */js/jquery.js\n"
>>> "```\n"
>>> "\n"
>>> "The `Files-Included` field can be used to \"re-include\" files matched by `Files-Excluded`.\n"
>>> "\n"
>>> "It is also possible to exclude files in specific \"upstream components\" for source packages\n"
>>> "with multiple upstream tarballs. This is done by adding a field called\n"
>>> "`Files-Excluded-<component>`. The `<component>` part should then match the component name\n"
>>> "exactly (case sensitive).\n"
>
> This doesnt really work in isolation, what is a <componant>?
Maybe if it just gave an example in passing it would be clear enough,
but I can't find any examples.
>>> #. [Synopsis] One-line description for the value "allow-stderr" [Plaintext].
>>> #. Shown with completion (etc.)
>>> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
>>> msgctxt "Stanza:Tests|Field:Restrictions"
>>> msgid "Output on standard error should not trigger a test failure"
> ^^^^^^
> "will not", surely
The flag indicates that this test may routinely log to stderr, and
that the testing frameword should allow this. It's odd that we call
this a "restriction", but probably it's best not to think about it
too hard.
>>> #. [Hover Doc] Extended description for the value "breaks-testbed" [Markdown].
>>> #. Shown in hover docs (etc.)
>>> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
>>> #, python-brace-format
>>> msgctxt "Stanza:Tests|Field:Restrictions"
[...]
>>> "When this restriction is present the test will usually be skipped\n"
>>> "unless the testbed's virtualisation arrangements are sufficiently\n"
Wait, did I miss that en_GB -isation? I think so.
>>> "powerful, or alternatively if the user explicitly requests.\n"
>>> msgstr ""
>
> It would be really helpful to say what sbuild does here, eg i think it
> mostly skips such tests unless you use lxc?
(No idea)
>>> #. [Hover Doc] Extended description for the value "flaky" [Markdown]. Shown in
>>> #. hover docs (etc.)
>>> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
>>> #, python-brace-format
>>> msgctxt "Stanza:Tests|Field:Restrictions"
>>> msgid ""
>>> "The test is expected to fail intermittently, and is not suitable for\n"
>>> "gating continuous integration. This indicates a bug in either the\n"
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> what on earth does this mean?
A piece of continually grating jargonisation, but basically
https://devops.stackexchange.com/questions/10600/what-is-a-gating-continuous-integration-ci-system#10632
a test that must be passed before the new version is allowed in.
>>> #. [Synopsis] One-line description for the value "isolation-container"
>>> #. [Plaintext]. Shown with completion (etc.)
>>> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
>>> msgctxt "Stanza:Tests|Field:Restrictions"
>>> msgid "Container level isolation required"
>>> msgstr ""
>
> Can you say what this needs - chroot? schroot? lxc? docker? quemu? it's
> really hard to understand from other docs so this would be a great
> benefit to users
(Can't help here either)
>>> "Tests must not assume that a specific init system is in use: a\n"
>>> "dependency such as `systemd-sysv` or `sysvinit-core` does not work\n"
>>> "in practice, because switching the init system often cannot be done\n"
>>> "automatically.
>
> interesting! given systemd is the "default" is it not assumable in
> practice?
(Do all these containerisation mechanisms even use an init system?)
>>> #. [Synopsis] One-line description for the value "skippable" [Plaintext].
>>> #. Shown with completion (etc.)
>>> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
>>> msgctxt "Stanza:Tests|Field:Restrictions"
>>> msgid "Test may at runtime decide to be marked as skipped"
>
> "marked as"?? seems unneccessary
A "skippable" test is apparently one that can decide at runtime
whether it's in a position to work as a test or not (maybe it never
works on the sabbath); if not, it declares that it doesn't count as
having been tried - that is, it's marked down as skipped.
Is there a short way of conveying that?
>>> msgstr ""
>>>
>>> #. [Hover Doc] Extended description for the value "skippable" [Markdown].
>>> #. Shown in hover docs (etc.)
>>> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
>>> #, python-brace-format
>>> msgctxt "Stanza:Tests|Field:Restrictions"
>>> msgid ""
>>> "The test might need to be skipped for reasons that cannot be\n"
>>> "described by an existing restriction such as isolation-machine or\n"
>>> "breaks-testbed, but must instead be detected at runtime. If the\n"
>>> "test exits with status 77 (a convention borrowed from Automake), it\n"
>>> "will be treated as though it had been skipped. If it exits with any\n"
>>> "other status, its success or failure will be derived from the exit\n"
>>> "status and stderr as usual. Test authors must be careful to ensure\n"
>>> "that `skippable` tests never exit with status 77 for reasons that\n"
>>> "should be treated as a failure.\n"
>>> msgstr ""
>
> Pretty confusing tbh - why is this needed if we can mark tests as skippable?
This *is* marking them as skippable - the CI system doesn't roll dice
to decide which ones to run, it just lets "skippable" tests return an
extra value that doesn't mean "succeeded" or "failed". It seems an
odd way to do it, but I haven't tried implementing a test framework.
>>> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
>>> #. completion (etc.)
>>> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
>>> msgctxt "Stanza:Tests|Field:Depends"
>>> msgid "Dependencies for running the tests"
>>> msgstr ""
>>>
>>> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
>>> #. hover docs (etc.)
>>> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
>>> #, python-brace-format
>>> msgctxt "Stanza:Tests|Field:Depends"
>>> msgid ""
>>> "Declares that the specified packages must be installed for the test\n"
>>> "to go ahead. This supports all features of dpkg dependencies, including\n"
>>> "the architecture qualifiers (see\n"
>>> "<https://www.debian.org/doc/debian-policy/ch-relationships.html>),\n"
>>> "plus the following extensions:\n"
>>> "\n"
>>> "`@` stands for the package(s) generated by the source package\n"
>>> "containing the tests; each dependency (strictly, or-clause, which\n"
> ?????????
>>> "may contain `|`s but not commas) containing `@` is replicated\n"
>>> "once for each such binary package, with the binary package name\n"
>>> "substituted for each `@` (but normally `@` should occur only\n"
>>> "once and without a version restriction).\n"
>
> I dont understand this, the last time i used @ it tried to install *all*
> binary packages at once, which didnt work
I've never tried, so I can't help with any of this!
>>> "`@recommends@` stands for all the packages listed in the\n"
>>> "`Recommends:` fields of all the binary packages mentioned in the\n"
>>> "`debian/control` file. Please note that variables are stripped,\n"
>>> "so if some required test dependencies aren't explicitly mentioned,\n"
>>> "they may not be installed.\n"
>
> dont understand "stripped" in this para
>
>>> "\n"
>>> "If no Depends field is present, `Depends: @` is assumed. Note that\n"
>>> "the source tree's Build-Dependencies are *not* necessarily\n"
>>> "installed, and if you specify any Depends, no binary packages from\n"
>>> "the source are installed unless explicitly requested.\n"
>
> or requested via @?
>
>>> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
>>> #. completion (etc.)
>>> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
>>> msgctxt "Stanza:Tests|Field:Comment"
>>> msgid "Name and email of the maintainer or the maintenance team"
>>> msgstr ""
>>>
>>> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
>>> #. hover docs (etc.)
>>> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
>>> #, python-brace-format
>>> msgctxt "Stanza:Tests|Field:Comment"
>>> msgid ""
>>> "Comment field to optionally provide additional information. For example, it might quote an e-mail from\n"
>>> "upstream justifying why the combined license is acceptable to the `main` archive, or an explanation of\n"
>>> "how this version of the package has been forked from a version known to be [DFSG]-free, even though the\n"
>>> "current upstream version is not.\n"
>
> Didnt we already have this field before? and this seems to be about licenses not tests?
There are
msgctxt "Stanza:Header|Field:Comment"
and
msgctxt "Stanza:License|Field:Comment"
and
msgctxt "Stanza:Tests|Field:Comment"
but I can't say I follow what this one's about. Maybe all the
examples are appropriate for the License-stanza version, and we ought
to have different ones for Comment fields in other stanzas?
>>> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
>>> #. hover docs (etc.)
>>> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
>>> #, python-brace-format
>>> msgctxt "Stanza:Tests|Field:Tests"
>>> msgid ""
>>> "This field names the tests which are defined by this stanza, and map\n"
>>> "to executables/scripts in the test directory.
>
> why the / ? are you trying to say that scripts dont need to be +x (i
> dont think that is correct)?
In theory I suppose they might be dotted-in bash scripts, but I really
hope not. I suspect the idea is "executables (whether or not they're
compiled binaries)", but since the point is that it doesn't matter
(and I don't know whether compiled binaries are even likely here) it
should probably just say "executables".
>>> "This allows tests to live outside the `debian/` metadata area, so that\n"
>>> "they can more palatably be shared with non-Debian distributions.\n"
>>> msgstr ""
>>>
>>> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
>>> #. completion (etc.)
>>> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
>>> msgctxt "Stanza:Tests|Field:Copyright"
>>> msgid "Provide copyright statements for the package as a whole"
>>> msgstr ""
>>
>> Provides
>
> But why is it Stanza:Tests - is this duplication?
Some of the same fields appear in multiple stanzas, so duplication
isn't necessarily bad. I don't see why this kind of information would
be in this stanza, though...
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
Reply to: