Re: Review of debputy editor provided docs for packagers
>> #. 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
>> "\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"
You should add a link to Justin's style guide to help people write these better!
>> #. [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 ??
>> #. [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)
>> #. [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?
>
>> #. [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?
>> #. [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"?
> "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?
>> #. [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?
>> "**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>?
>> #. [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
>> #. [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"
>> msgid ""
...
>> "\n"
>> "When this restriction is present the test will usually be skipped\n"
>> "unless the testbed's virtualisation arrangements are sufficiently\n"
>> "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?
>> #. [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?
>> #. [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
>> "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?
>> #. [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
>> 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?
>> #. [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
>> "`@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?
>> #. [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)?
>> "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?
Reply to: