Hi, The new compat 14 in debhelper has already had about 50 packages,which has opted in as very early adopters and provided valuable feedback so far including several fixes. Since August, compat 14 has been stable, which I believe is a good sign.
This email is aimed at maintainers of packages that provide debhelper-like tools. There are separate sections for `Dh_Lib`-based tools vs. tools not using `Dh_Lib` (such as `dh-python`). Please review the relevant section for your tool.
If you are a maintainer wanting to migrate to compat 14, then there will be a separate mail on the later. That mail will also cover migration support tooling. This includes if you want to migrate one of your packages to compat 14 to test the changes to the dh-like tool that you maintain.
# What is expected from you as a `Dh_Lib`-based tool maintainer:
* The `pkgfile` function from `Dh_Lib.pm` has changed its default and
accept new parameters. If your tool never needs `--name` nor
architecture specific files, then no changes should needed for
this item other than perhaps a few tweaks of examples (see next item)
Note that `--name` is still a common option. It is accepted but
ignored for commands like `dh_install` (etc.). It still has it
place with commands like `dh_installsystemd`.
Rule of thumb: If you always install into path name based on
`${package}`, the command should not react to `--name`. If the tool
does not install the file, then `--name` should be ignored as well.
* Per compat 14, the package prefix in `debian/pkg.foo` files are
*mandatory* for multi-binary packages or when `--name` is involved.
Use of `debian/foo` only works with single binary packages (and when
`--name` is not used).
- If the tool use `pkgfile`, then beyond the previous item, you
"only" need to review your docs and examples.
- If your tool uses a custom/hand written implementation of
`pkgfile` for some reason, please consider to match `debhelper`'s
new restrictions. The `dh_assistant active-compat-level` command
can be used to tell the active compat level.
Note: This change only applies to files that are generally package
specific. Tools that react to static files, such as `dh_autoreconf`
and its `debian/autoreconf` file that acts per source package are
not covered by this change.
If the tool support package specific variants but generally have
been using the same file for all binaries (like similar to
`debian/copyright` or `debian/changelog`), please file a bug against
debhelper. There is an internal feature for this case that would have
to made part of the public API. Additionally, the migration tooling
will need an exception for this case.
* Compat 14 will automatically apply relationship substitution
variables (such as `${foo:Depends}`). If the tool sets such
substitution variables, please review if there are any accuracy
related changes or toggles you want to have released for your
users.
* Please mark all configuration files that the tool reacts to via
introspectable comments such as [`PROMISE: DH NOOP`] or the new
[`INTROSPECTABLE: CONFIG-FILES`] comment. These are important for
tooling support. Files covered by `PROMISE: DH NOOP` need **not**
be repeated in `INTROSPECTABLE: CONFIG-FILES`.
If the command does not react to any configuration files at all,
please add `# INTROSPECTABLE: CONFIG-FILES NONE`. Otherwise users
will see warnings about the command when they use the migration
tooling.
The `dh_assistant list-guessed-dh-config-files` command on a package
using the tool can be used to validate what the hints have been
picked up.
Example: #1115825 +
https://salsa.debian.org/python-team/tools/dh-python/-/merge_requests/63
* The `dh` sequence has changed. Notably, `dh_fixperms` is now run /before/ `dh_strip_nondeterminism` and `dh_compress`. If the tool is now run after `dh_fixperms`, be sure to double check that it sets permissions correctly on any file it touches. Additionally, `dh_dwz` will no longer be run by default.There are additional changes. Please see https://manpages.debian.org/unstable/debhelper/debhelper-compat-upgrade-checklist.7.en.html#v14 for
the full list.
* If the tool provides a build system, then ensure that the `install`
target runs:
$this->ensure_minimal_permissions($destdir) if not compat(13);
After the build system installed anything into `$destdir`. If nothing
was installed into `$destdir` the line should be skipped.
Note: This can be skipped if the upstream build system is known
to always without exception provide sane permissions on files
(such as the install target being `unzip -d $destdir code.zip`)
# What is expected from you as a tool maintainer of a custom stack:
Examples include tools written in python (such as dh-python) or shell
(historically javatools, do not remember if they fully migrated by now
to `Dh_Lib`).
* `debian/compat` has been replaced by `X-DH-Compat`. Use
`dh_assistant active-compat-level` if the tool needs to know the
compat level.
* Per compat 14, there substantial changes to how debhelper finds
config files in `debian/`.
- The package prefix in `debian/pkg.foo` files are now mandatory
with the exception of single binary packages where `--name` and
architecture restrictions are not involved. In compat 14, there
is a fallback with a warning. In compat 15, this becomes an error.
- The `--name` feature has been disabled for most of these files
in `debhelper` itself. If your tool uses `--name` or architecture
restrictions, consider if it is truly necessary or relevant.
Note that `--name` is still a common option. It is accepted but
ignored for commands like `dh_install` (etc.). It still has it
place with commands like `dh_installsystemd`.
Rule of thumb: If you always install into path name based on
`${package}`, the command should not react to `--name`. If the
tool does not install the file, then `--name` should be ignored as
well.
The tool can use `dh_assistant active-compat-level` command to tell
what is the active compat level, so that it can introduce this
behavioural change conditionally.
Note: This change only applies to files that are generally package
specific. Tools that react to static files, such as `dh_autoreconf`
and its `debian/autoreconf` file that acts per source package are
not covered by this change.
If the tool support package specific variants but generally have
been using the same file for all binaries (like similar to
`debian/copyright` or `debian/changelog`), then it can keep doing
that. Please file a bug against debhelper about the case, since it
will require an exception to avoid triggering the migration tooling.
* Compat 14 will automatically apply relationship substitution
variables (such as `${foo:Depends}`). If the tool sets such
substitution variables, please review if there are any accuracy
related changes or toggles you want to have released for your
users.
* Please mark all configuration files that the tool reacts to via
introspectable comments such as [`PROMISE: DH NOOP`] or the new
[`INTROSPECTABLE: CONFIG-FILES`] comment. These are important for
tooling support. Files covered by `PROMISE: DH NOOP` need **not**
be repeated in `INTROSPECTABLE: CONFIG-FILES`.
If the command does not react to any configuration files at all,
please add `# INTROSPECTABLE: CONFIG-FILES NONE`. Otherwise users
will see warnings about the command when they use the migration
tooling.
The `dh_assistant list-guessed-dh-config-files` command on a package
using the tool can be used to validate what the hints have been
picked up.
Example: #1115825 +
https://salsa.debian.org/python-team/tools/dh-python/-/merge_requests/63
* The `dh` sequence has changed. Notably, `dh_fixperms` is now run /before/ `dh_strip_nondeterminism` and `dh_compress`. If the tool is now run after `dh_fixperms`, be sure to double check that it sets permissions correctly on any file it touches. Additionally, `dh_dwz` will no longer be run by default.There are additional changes. Please see https://manpages.debian.org/unstable/debhelper/debhelper-compat-upgrade-checklist.7.en.html#v14 for
the full list. * If the tool provides a build system, then ensure that the `install` target runs `chmod -R u+rwX` on the staging dir (`--dest-dir`) after installing the upstream files into it. Note: This can be skipped if the upstream build system is known to always without exception provide sane permissions on files (such as the install target being `unzip -d <DESTDIR> code.zip`) # Examples for introspection hints: Some examples for introspection hints include: * dh-python: #1115825 - using the `pkgfile` type hint https://salsa.debian.org/python-team/tools/dh-python/-/merge_requests/63 * dh-autoreconf: #1111948 - using the new `path` type hint. (includes link to MR in the bug)As mentioned, running `dh_assistant list-guessed-dh-config-files` (add `--with <addon>` if necessary) on a package that uses a sequence add on with your tool in it, can be used to test the hints. Keep in mind that `dh_assistant` checks only commands that are in the `dh` sequence and only for commands in PATH for these hints. So the hint must be in that file (that is, remember to install your patched version and keep in mind that imports are not scanned for hints). If the package uses a hook target to command, you will have to `--with addon` to perform the test. On a related note, if your command is not in a `dh` sequence add-on, consider creating one.
# Closing Thanks for your time.I plan to send out a separate mail asking for beta testers for compat 14. If they use the tool you maintain, they may also start filing bugs for some of the above things with a link to this email.
If you run into issues where you feel debhelper could assist your tool better (especially for custom tools that cannot easily use `Dh_Lib`) please consider filing a wishlist bug with the problem you have.
Best regards, Niels Links/References:[`PROMISE: DH NOOP`]: https://salsa.debian.org/debian/debhelper/-/blob/main/doc/PROGRAMMING.md?ref_type=heads#optimization-techniques
[`INTROSPECTABLE: CONFIG-FILES`]: https://salsa.debian.org/debian/debhelper/-/blob/main/doc/PROGRAMMING.md?ref_type=heads#introspection-techniques---config-files
OpenPGP_signature.asc
Description: OpenPGP digital signature
