Re: Review of debputy editor provided docs for packagers
Niels Thykier wrote:
> I suppose there would be no harm in having a paragraph explaining when to
> use which. Here is my draft for how to include it (full hover doc). It also
> includes an example with the component case as suggested by Justin below:
>
>> Remove the listed files from the tarball when repacking (commonly via `uscan`). This can be useful
Most of these field definitions say what the field does; this one
seems instead to be giving an instruction. Should it be something like
Lists files that should be removed from the tarball when [...]
>> when the listed files are non-free but not necessary for the Debian package. In this case, the
>> upstream version of the package should generally end with `~dfsg` or `+dfsg` (to mark the content
>> changed due to the Debian Free Software Guidelines). The exclusion can also be useful to remove
Should that be "to mark the content ⁁as changed"?
>> large files or directories that are not used by Debian or pre-built binaries. In this case, `~ds`
"To remove large files or directories that are not used by Debian or
pre-built binaries" would be less ambiguous (used by binaries?) if it
was repacked slightly as "to remove pre-built binaries, or large files
or directories that are not used by Debian".
>> or `+ds` should be added to the version instead of `~dfsg` or `+dfsg` for "Debian Source" to mark
The expansion for "ds" has slipped.
In this case, `~ds`
or `+ds` for "Debian Source" should be added to the version to mark it as altered by Debian
instead of `~dfsg` or `+dfsg`.
or maybe
In this case, instead of `~dfsg` or `+dfsg`, `~ds`
or `+ds` for "Debian Source" should be added to the version to mark it as altered by Debian.
>> it as altered by Debian. If both reasons are used, the `~dfsg` or `+dfsg` version is used as that
The word used is being overused here - "if both reasons apply,"
>> is the more important reason for the repacking.
So from the top:
Lists files that should be removed from the tarball when repacking (commonly via `uscan`). This
can be useful when the listed files are non-free but not necessary for the Debian package. In this
case, the upstream version of the package should generally end with `~dfsg` or `+dfsg` (to mark the
content as changed due to the Debian Free Software Guidelines). The exclusion can also be useful to
remove pre-built binaries, or large files or directories that are not used by Debian. In this case,
instead of `~dfsg` or `+dfsg`, `~ds` or `+ds` for "Debian Source" should be added to the version
to mark it as altered by Debian. If both reasons apply, the `~dfsg` or `+dfsg` version is used as
that is the more important reason for the repacking.
>> **Example**:
>> ```
>> Files-Excluded: exclude-this
>> exclude-dir
>> */exclude-dir
>> .*
>> */js/jquery.js
>> ```
>>
>> The `Files-Included` field can be used to "re-include" files matched by `Files-Excluded`.
>>
>> It is also possible to exclude files in specific "upstream components" for source packages
>> with multiple upstream tarballs. This is done by adding a field called
>> `Files-Excluded-<component>`. The `<component>` part should then match the component name
>> exactly (case sensitive).
>> **Example**:
>> ```
>> # This field applies to the `foo` component tarball (`${SOURCE}_${VERSION}.orig-foo.tar.*`)
>> # instead of the main orig tarball.
>> Files-Excluded-foo: exclude-this
>> exclude-dir
>> */exclude-dir
>> .*
>> */js/jquery.js
>> ```
>>
>> The field uses the same syntax as the `Files` fields from the `Files` stanzas.
>> Whether the package should use `~` (`~dfsg`) or `+` (`+dfsg`) in the version depends on
>> the situation with the `+` variants being the most commonly used. If in doubt, look for
>> an argument for why the `~` variants would be preferred in your case. In absence of any
>> clear rationale for using `~` variants, then use the `+` variants. Review
>> [section 5.6.12 of the Debian Policy] and its subsections for more information on the
>> versioning and the special rules regarding the sort order for `~`.
>>
>> Defined by: `mk-origtargz` (usually used via `uscan`)
>>
>> [section 5.6.12 of the Debian Policy]: https://www.debian.org/doc/debian-policy/ch-controlfields.html#special-version-conventions
> End draft.
This all looks okay.
> [...]
>
> I think it would be more ideal if there was a page I could link to that
> explained this case better. At that point, I could probably inline it in the
> first paragraph with a "Review X for details on when to use dfsg vs. ds and
> whether to use ~ or +". That page might exist, but I cannot find it if it
> does.
This sounds like the kind of developer experience you'd be more likely
to be able to survey at a DebConf than a wiki page.
>>>>> #. [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?
>
> Perhaps, "Test may at runtime decide to be skipped"?
That seems less pedantically accurate than the version where it
declares that it's "marked as" skipped, given that it is already
running (and therefore hasn't *literally* been skipped) when it
decides that. We might I suppose say:
msgid "Test may at runtime decide it should count as skipped"
I was hoping I'd find a way of doing it with some fancy synonym like
"abstain", but I doubt there's anything that would make it clearer.
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
Reply to: