summaryrefslogtreecommitdiffstats
path: root/debputy.pod
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-14 19:54:34 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-14 19:58:39 +0000
commit129a1fb4dbc375be0fa926964aa1be46a0cdbbef (patch)
tree04c0088df47415b24a5be1325d3656b8c3881c04 /debputy.pod
parentInitial commit. (diff)
downloaddebputy-129a1fb4dbc375be0fa926964aa1be46a0cdbbef.tar.xz
debputy-129a1fb4dbc375be0fa926964aa1be46a0cdbbef.zip
Adding upstream version 0.1.21.upstream/0.1.21
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'debputy.pod')
-rw-r--r--debputy.pod633
1 files changed, 633 insertions, 0 deletions
diff --git a/debputy.pod b/debputy.pod
new file mode 100644
index 0000000..593f02d
--- /dev/null
+++ b/debputy.pod
@@ -0,0 +1,633 @@
+=encoding UTF-8
+
+=head1 NAME
+
+debputy - Manifest style Debian-based package builder
+
+=head1 SYNOPSIS
+
+B<debputy> [S<I<< general options >> >] B<command ...> [S< I<< command options >> >]
+
+B<debputy> B<migrate-from-dh> [B<--apply-changes>] [B<--acceptable-migration-issues=>I<issue>[,I<issue>,...]]
+
+B<debputy> B<check-manifest> [B<--debputy-manifest=>I<path/to/debputy.manifest>]
+
+B<debputy> B<annotate-packaging-files>
+
+B<debputy> B<lint>
+
+B<debputy> B<lsp> B<editor-config> B<NAME>
+
+B<debputy> B<lsp> B<server> [B<--tcp|--ws> [B<--host> I<BIND-ADDRESS>] [B<--port> I<PORT>]]
+
+=head1 DESCRIPTION
+
+The B<debputy> program is a manifest style Debian-based package builder. This manpage documents some of the
+user facing commands.
+
+If you are using B<debputy> with a screen reader, consider setting the environment variable
+B<OPTIMIZE_FOR_SCREEN_READER> to 1. This will make many B<debputy> commands remove a lot of
+irrelevant visual rendering. Especially ASCII art style rendering that will just be annoying
+to listen to. Additionally, some output will be described with text to replace the visual
+rendering.
+
+=head2 Commands
+
+=over 4
+
+=item check-manifest
+
+The B<check-manifest> command will cause B<debputy> to parse the manifest and examine it for obvious mistakes.
+
+Note that the command will I<not> catch all mistakes as some problems can only be detected during a build. As
+an example, B<check-manifest> can detect mistyped manifest variables but not typos in path names for
+installation rules.
+
+=item migrate-from-dh
+
+The B<migrate-from-dh> command will attempt to migrate the current package to B<debputy>.
+
+For this command to be successful, it must be run from the root of an unpacked Debian source package and the
+package should be using the B<dh> sequencer.
+
+The migration can rerun with newer version of B<debputy> that might provide more features since the previous
+one even inside the same level of adoption. As an example, B<debputy/0.1.21> added support for automatic
+relationship substvars. Re-running the migrator for an already migrated package can be used to detect any
+unnecessary explicit relationship substvars as unnecessary.
+
+The default migration target is based on existing features in the packaging where present. As an example,
+a build-dependency on B<dh-sequence-zz-debputy-rrr> will make the migration tool only run migrators relevant
+for B<dh-sequence-zz-debputy-rrr>. If the migration cannot identify any target markers, it has a built-in
+default target. The default target will change over time as B<debputy> and the migrator mature. The
+B<--migration-target> option can be used to overrule this automatic detection. This can be useful both to
+expand on the migration level without performing any changes or to choose a more conservative initial
+migration level.
+
+Generally, the migration tool can take you from "less adoption" towards "more adoption" of B<debputy> but
+not the inverse. As an example, migrating from B<dh-sequence-zz-debputy-rrr> towards B<dh-sequence-zz-debputy>
+is supposed, but the reverse is not.
+
+If any migrations involve creating a new or changing an existing F<debian/debputy.manifest>, the migration
+tool will first write a draft to F<debian/debputy.manifest.new>. From there, it may be renamed to
+F<debian/debputy.manifest> automatically depending on B<--apply-changes> or B<--no-apply-changes>.
+
+It supports the following options:
+
+=over 4
+
+=item B<--migration-target> I<TARGET-NAME>
+
+Explicitly define how far the migration should go. This will override the detected or built-in default as
+the desired migration target.
+
+See L</INTEGRATION LEVELS> for details about the concrete levels of integration that can be used.
+
+=item B<--acceptable-migration-issues> I<NAME[,...,NAME]>, B<--acceptable-migration-issues=ALL>
+
+The migration may detect unsupported features in the package. Some, but not all, of these can be reduced to
+a warning by passing B<--acceptable-migration-issues> with the name of the issue as provided in the error
+message. The special value B<ALL> in all upper case will cause all issues that can be reduced to a warning
+to be reduced to a warning.
+
+This is only useful to reduce issues to warnings if you are reasonable sure that you can remove the feature
+or convert it to something that B<debputy> supports.
+
+=item B<--apply-changes>, B<--no-act>, B<--no-apply-changes>
+
+These options decide whether the migration tool should perform destructive actions such as overwriting the
+existing B<debian/debputy.manifest> and deleting packaging files that have successfully migrated.
+
+The default is currently to not perform destructive actions as the migration tool does not detect version
+control systems. If support for detecting version control systems is added, this default may change.
+
+Note that the migration may replace B<debian/debputy.manifest.new> regardless of this option as that is its
+output for the updated draft manifest.
+
+The B<--no-act> is an alias of B<--no-apply-changes> to match the name that B<debhelper> command use.
+
+=back
+
+=item lint
+
+I<< Note: This subcommand needs optional dependencies to work from B<Recommends> or B<Suggests> >>
+
+Run the linting tooling for Debian packaging files. This will run a linter to check the Debian packaging
+files. This command is useful for CI or for when you cannot use the language server feature. It provides
+the same diagnostics as B<debputy lsp server> would but without requiring an LSP capable editor as intermediate.
+The output is only intended for human consumption. Machine readable is not a goal at this time.
+
+Note that at the time of writing, the B<debputy.manifest> file is only B<partially> supported. If you
+have F<debian/debputy.manifest>, please also run B<debputy check-manifest> to get more thorough checks
+for that file for now. The B<lint> command will inform you about this issue in the output if a
+F<debian/debputy.manifest> file is detected.
+
+Some relevant options for this subcommand include:
+
+=over 4
+
+=item B<--auto-fix>
+
+If B<debputy> is aware of one "obvious" solution to the issue, just apply it. This will apply the
+changes directly to the file. Use of version control for the Debian packaging is recommended when
+using this option in case you want to undo the result.
+
+=item B<--spellcheck>
+
+Include spellchecking in the linting results. These are by default omitted, since they are slower
+and there are often false-positives.
+
+I<Caveat>: Currently, B<--auto-fix> with B<--spellcheck> will auto-correct all spelling mistakes
+with a single correction available. This can be suboptimal behaviour in some cases and therefore
+combing these options are not always recommended.
+
+=item B<--linter-exit-code>, B<--no-linter-exit-code>
+
+There is a convention among linter tools to return a non-zero exit code for "severe issues". The
+B<--linter-exit-code> will enforce this behaviour while the B<--no-linter-exit-code> will disable
+it.
+
+The B<debputy> program will use exit code B<2> for "severe issue" as a "linter exit code" when
+linting based exit codes are active.
+
+Not having a linter based exit code can be useful if you want to run the tool programmatically
+to display the results and you only want the exit code to tell whether there was a problem
+providing the results.
+
+If you rely on the exit code, you are recommended to explicitly pass the relevant variant of the
+flag even if the current default matches your wishes.
+
+=back
+
+A short comparison of B<debputy lint> vs. other tools:
+
+=over 4
+
+=item B<debputy lsp server>
+
+The language server feature from B<debputy lsp server> provides an interactive and online version of the linting
+from B<debputy lint> directly in any LSP capable editor (with the proper glue configuration). The LSP
+feature gives you instant gratification, some additional editor-only features and interactive choices of
+available quickfixes.
+
+The "downside" of the B<debputy lsp server> feature is that it requires a LSP capable editor and each editor has
+their own glue configuration. Since the B<debputy> language server is new, almost no editor has built-in
+glue configuration meaning it has a steeper "learning curve" to get started. Additionally, some times
+you want the checks for CI checks or the current state of the package (without having to open each
+file in an editor). Here B<debputy lint> covers the same issues without the need for anything else.
+
+=item B<lintian>
+
+The primary difference between the B<debputy> linter and B<lintian> is that B<lintian> works on "binary"
+artifacts. Even the source checks of B<lintian> checks the packaged version of the source rather than
+the files you are directly working. This means that you have to do a package "build" for lintian to spot
+any changes, which causes slow feedback loops. Additionally, B<debputy lint> can provide feedback regardless
+of whether your package can currently build. Accordingly, you can get help and hints even for problems
+that would prevent a package build. By nature of how B<lintian> works, you can only get hints from lintian
+on matters that does not break the package build.
+
+On the flip side, because B<lintian> is checking the assembled artifacts, it can check for issues that
+are only visible after a package build. Additionally, B<lintian> also checks for issues in the upstream
+sources to some extent. Checking upstream artifacts and the resulting Debian packages are not in scope for
+B<debputy lint> as the B<debputy lint> is intended to be a mirror of the language server diagnostics.
+
+In summary: Use B<debputy lint> (or B<debputy lsp server>) for short feedback loops. Use B<lintian> for
+slower but more thorough checks on resulting packages.
+
+=item B<lintian-brush>
+
+The B<lintian-brush> has a broader scope than B<debputy lint>. If you are a happy B<lintian-brush> user,
+odds are that B<debputy lint> will not do a lot for you. Though, B<debputy lsp server> might still be relevant
+as the language server provides additional editor related features.
+
+=back
+
+=item lsp server
+
+I<< Note: This subcommand needs optional dependencies to work from B<Recommends> or B<Suggests> >>
+
+Start the B<debputy> language server (per B<Language Server Protocol> specification).
+
+Many modern editors can delegate language support to a B<Language Server> or indirectly via other
+features like supporting B<youcompleteme> (which in turn can delegate to a language server). The
+B<debputy> tool provides one for many common packaging formats via the B<lsp server> subcommand for file
+formats such as B<debian/control>, B<debian/changelog> and B<debian/copyright>.
+
+You will often need some editor specific glue configuration to link a given file format or name
+to the language server. The B<debputy lsp editor-config> might provide an example glue snippet for
+your editor. In that glue configuration, you will need to provide a command. Often,
+B<debputy lsp server> will suffice (using the stdio transport). See B<debputy lsp server --help>
+for other integration options such as TCP (B<--tcp>) or websocket (B<--ws>) plus related supporting
+options.
+
+If you need to debug an issue with the language server, the TCP integration (B<--tcp>) can be
+quite helpful. In this mode, you run B<debputy lsp server --tcp> in a terminal before starting your
+editor. This means you have direct and unfiltered access to the B<debputy> command and its output.
+Remember to update your editor to use TCP integration rather than stdio integration (and remember
+to swap back when you are done). Check the B<debputy lsp server --help> if you need a different
+bind address for the language server.
+
+If you can choose the language ID for a given file, you are recommended to use the file name
+relative to the source root (such as B<debian/control>). The service does account for some
+known variations such as B<debian-control> (as used by B<eglot> from B<emacs>) and
+B<debcontrol> (as used by B<vim>). See B<debputy lsp features> for a list of known language IDs
+along with their aliases.
+
+When properly set up, the language server will offer a variety of features such as:
+
+=over 4
+
+=item -
+
+Completion suggestion such as field names or values in deb822 based files.
+
+=item -
+
+Hover documentation for fields in deb822-based files.
+
+=item -
+
+Diagnostics ("linting"). In many cases, B<debputy> will also provide quickfixes for the issues.
+
+This feature is also (partly) available via the B<debputy lint> command. The primary limitation
+in B<debputy lint> is that you cannot interactively choose which quickfix to apply.
+
+=item -
+
+On save actions (currently only "prune trailing whitespace").
+
+=back
+
+=item lsp editor-config B<EDITOR>
+
+Provide an example configuration glue for using the B<debputy lsp server> with the given editor
+if known.
+
+The snippets are maintained on a basis effort basis for editors without built-in config glue
+for the B<debputy lsp server>. Please file an issue (or a merge request) at
+L<https://salsa.debian.org/debian/debputy> if a snippet needs to be updated, added or removed.
+
+=item lsp features
+
+List in a human readable format details about what language IDs are handled by the
+B<debputy lsp server> along with what features are provided for each file format/language ID.
+
+=item tool-support
+
+These commands are intended for other tools to consume the output. Output is generally JSON by default or
+supported via B<--output-format=json>.
+
+=over 4
+
+=item export-reference-data [DATASET]
+
+The B<export-reference-data> command export reference data. If provided, only the named dataset will be exported.
+Otherwise, all datasets will be exported.
+
+The reference data includes descriptions of the keywords used in the data set, which is helpful to understand the
+data.
+
+=item supports-tool-command <COMMAND>
+
+Tests whether B<debputy> knows about the named command. Returns successfully if known and unsuccessfully if not
+known.
+
+=item annotate-debian-directory
+
+The B<annotate-debian-directory> command will make B<debputy> scan the F<debian/> directory for known
+packaging files and annotate them with information.
+
+Identifying known packaging files is done on a best effort basis and B<debputy> has the following
+sources of information:
+
+=over 4
+
+=item Data from plugins
+
+Any installed B<debputy> plugin can provide data about known packaging files. Most of B<debputy>'s "built-in"
+rules are stored in the B<debputy-documentation> or the B<debhelper-documentation> plugin. These are installed
+in F</usr/share/debputy/debputy/plugins/> by default. If any of the data in there is wrong,
+please file a bug or a bug against the package providing the data (often B<debputy> or B<debhelper>).
+
+If the plugin provides the relevant data, B<debputy> will expose B<install-pattern> and B<install-path>, which
+are best-effort guesses for the file is installed (or where files listed in it will be installed). Please check
+the B<config-features> and B<file-categories> for the file to see when these field are applicable (and which
+case it is).
+
+Note that some files can be matched multiple times. As an example F<debian/changelog> and F<debian/copyright>
+will generally appear once per package, because they are installed in each package.
+
+=item Dynamic data from L<debhelper(7)> (via L<dh_assistant(1)>>)
+
+Additionally, B<debputy> will ask B<dh_assistant> to resolve all relevant helper commands and their relevant
+config snippets. This data will be cross referenced with the plugin provided data where possible. This will
+detect files that B<debputy> (and its plugins) does not know about, but it cannot provide any additional
+information.
+
+This part requires B<debhelper (>= 13.12~)> to work fully. With older versions, the output will include am
+B<issues> denoting that B<dh_assistant> returned non-zero.
+
+When B<dh_assistant list-guessed-dh-config-files> is missing a file, it is typically because the command
+that uses that config file is not introspectable. Typically, that can be fixed by patching the command
+to include a command line a la:
+
+ # INTROSPECTABLE: CONFIG-FILES pkgfile(foo)
+
+Assuming the command uses B<pkgfile($package, "foo")> from L<Debian::Debhelper::Dh_Lib> to look up the
+config file.
+
+Notable case that will never work is F<debian/foo.service> where there is no B<foo> package in
+F<debian/control> but F<debian/rules> calls B<dh_installsystemd --name foo>. This holds equally for
+all debhelper config files and related commands.
+
+=back
+
+=back
+
+=item plugin list [I<TOPIC>]
+
+=item plugin show B<TOPIC> B<identifier>
+
+These commands provides access to features that are provided by plugins (Note: many B<debputy> features are
+plugin provided, so these commands also covers a lot of "built-in" features).
+
+These commands will access features of all plugins B<available> even if the current package will not activate
+all of these plugins. Unless otherwise stated, all output is intended to be human readable rather than machine
+readable. Formatting may change between any version.
+
+Many of the B<list> subcommands also provide a csv format. Note this output is B<not> intended for scripting
+as the output is subject to change - both in form of format availability and content. The csv output is
+intended as an aid to users of screen readers for which csv files are easier to deal with than visually
+rendered tables. If you need a stable format of some particular output, please file a feature request
+at L<https://salsa.debian.org/debian/debputy/-/issues> or via B<reportbug debputy>.
+
+You can use B<debputy plugin list --help> and B<debputy plugin show --help> to see which topics are applicable
+for each subcommand.
+
+Noteworthy topics include:
+
+=over 4
+
+=item plugins
+
+This topic provides a listing of all plugins that B<debputy> is aware of.
+
+This topic can only used with B<plugin list> and not with B<plugin show>.
+
+=item plugable-manifest-rules (aliases: pmr, p-m-r)
+
+The B<debputy> manifest provides a number of places where the packager can provide a number of different rules
+such as B<install> vs. B<install-doc> vs. B<install-examples> under B<installations:>. These are called
+plugable manifest rules and this topic provides insights to which rules are available where.
+
+When used with B<list>, B<debputy> will list all plugable manifest rules available. When used with B<show>,
+a rule name must be provided and B<debputy> will then provide details about the rule. These details include
+attributes available (where applicable) and any reference documentation provided by the plugin.
+
+As an example, here is how you get the details about the install rule:
+
+ debputy plugin show plugable-manifest-rules install
+
+When a rule name is ambiguous, B<debputy> will ask that you use B<rule-type::rule-name> instead of just B<rule-name>.
+As an example:
+
+ debputy plugin show plugable-manifest-rules TransformationRule::remove
+ debputy plugin show plugable-manifest-rules DpkgMaintscriptHelperCommand::remove
+
+Note the type names (such as B<TransformationRule>) are currently an implementation detail and may change in the
+future.
+
+=item packager-provided-files (aliases: ppf, p-p-f)
+
+This topic provides details about all "packager provided files". Packager provided files can be put into F<debian>
+from where B<debputy> will pick them up and install them somewhere in the package. While this command shows all
+possible variants (by their stems), the B<used-packager-provided-files> topic will B<list> real files matched.
+
+When used with B<list>, B<debputy> will list all the packager provided files that B<debputy> knows about. When
+used with B<show>, some additional details will be given.
+
+In a few cases, the packager provided file will be processed first (as an example F<debian/symbols> will be passed
+to B<dpkg-gensymbols> and the processed version will then be installed instead).
+
+=item used-packager-provided-files (aliases: uppf, u-p-p-f)
+
+This topic provides a list of all packager provided files used in this source package. This topic differs from
+B<packager-provided-files> in that it only shows files in actual use whereas the other topic lists all known
+stems.
+
+The listing will potentially include files that B<debputy> could have picked up, but will not do so during a
+package build because the relevant plugin is not explicitly requested (typically via a Build-Depends). These
+cases are placed in a separate table and will be clearly marked.
+
+This topic can only used with B<plugin list> and not with B<plugin show>.
+
+This topic only works when the command is run from the root of an unpacked Debian source package (as
+B<debputy> needs to read F<debian/control> and scan the F<debian/> directory).
+
+=item metadata-detectors
+
+This topic provides a listing of all "metadata detectors". These are plugin provided code snippets that scan the
+final form of the package and add substvars (for B<dpkg-gencontrol>), generate maintscript snippets, or/and
+declare triggers.
+
+This topic can only used with B<plugin list> and not with B<plugin show>.
+
+=item manifest-variables
+
+This topic covers B<plugin provided> manifest variables. The listing will list the common manifest variables by
+default along with their values in source context (if possible). Some of the special case manifest variables are
+hidden by default (use B<debputy plugin list manifest-variables --help> to see the filter options).
+
+When used with B<show VARIABLE>, B<debputy> will list the reference documentation (if provided by the plugin)
+related to the value along with a few other details.
+
+As implied above, this will only show B<plugin provided> variables. Any manifest variables provided directly
+in the manifest is B<not> covered by these commands.
+
+=item automatic-discard-rules
+
+This topic covers automatic discard rules, which are rules that automatically filters out (discards) sources
+from installation rules by default. The listing will list all the available automatic discard rules. The
+B<show RULE> command will show reference documentation and an example of what the rule reacts to (if these
+have been provided by the plugin).
+
+As an example:
+
+ debputy plugin show automatic-discard-rules la-files
+
+=item type-mappings
+
+This topic cover type mappings that explains how some non-trivial types are interpreted. These covers
+types like B<FileSystemMatchRule> and B<FileSystemMode>, which are used by other features such as
+plugable manifest rules.
+
+When used with B<show NAME>, any plugin provided documentation and example inputs will be displayed
+for that rule.
+
+=back
+
+=item autopkgtest-test-runner
+
+The B<autopkgtest-test-runner> command is intended to be used by B<autodep8> or from autopkgtests to run the
+tests of plugins in installed mode.
+
+=item internal-command
+
+This is for internal-only usage only. Any subcommand under B<internal-command> may disappear or change options
+between any release without any warning.
+
+=back
+
+=head1 GENERAL OPTIONS
+
+The following options general options or root level options are available.
+
+=over 4
+
+=item B<-h>, B<--help>
+
+Print usage information and exits.
+
+The information printed depends on which subcommands appear prior to this option.
+
+=item B<--version>
+
+Prints version information and exists.
+
+Cannot be used with subcommands.
+
+=item B<-d>, B<--debug>
+
+Enable debug logging and raw stack traces on errors.
+
+Some warnings become errors as a consequence.
+
+=item B<--no-pager>
+
+Some subcommands will in their default output format pipe it to a pager to give you a more pleasant
+experience if standard out is a terminal. Examples include many of the B<plugin list> commands. This
+option will disable the pager feature.
+
+Most option formats via B<--output-format> will imply B<--no-pager> as well for subcommands that
+support that option.
+
+Note: Assuming the environment has no pager configuration at all, B<debputy> will use L<less(1)>
+with the B<LESS> environment variable set to B<-FRMQSX>. Notable, the B<-F> option will cause B<less> to
+immediately terminate if the output fits on the screen.
+
+=item B<--plugin> I<REQUIRED_PLUGIN>
+
+This option causes I<REQUIRED_PLUGIN> to be loaded as a part of the commands execution if the command needs
+to load plugin data. For commands that load all plugins by default, this option causes the command to fail
+if I<REQUIRED_PLUGIN> cannot be loaded. For commands that are restrictive about which plugins are loaded,
+subcommand will load I<REQUIRED_PLUGIN> in addition other plugins that would normally be loaded.
+
+The I<REQUIRED_PLUGIN> can either be a plugin name or a filename. The B<debputy> program considers parameter
+with a forward slash as a filename. Otherwise, the parameter is interpreted as a plugin name. When given a
+plugin name, B<debputy> will search for the plugin in its plugin search path and load it from there. When
+given a file name, B<debputy> will read that file as a plugin and use the basename minus any B<.json> or
+B<.json.in> extension as the plugin name.
+
+For packages that need a plugin that they provide themselves during their build process, this option can
+be useful to tell B<debputy> about it. For the build itself, usually you want to use
+B<dh_debputy --plugin path/to/plugin.json>. But this option can still be useful for B<debputy check-manifest>
+etc.
+
+The other use-case is to load a plugin not installed into the plugin search directories. Notably, you can
+use this to shadow an existing plugin, which can be useful for debugging and developing your plugin changes.
+
+This option cannot be used with bundled plugins. As an example, both B<--plugin debputy> and
+B<--plugin path/to/a/debputy.json> will result in an error.
+
+=item B<--debputy-manifest> F<FILE>
+
+If the command needs to parse a manifest, have it read F<FILE> instead of B<debian/debputy.manifest>.
+
+Note this is mostly for testing as other features might not work correctly if the manifest is not aligned
+with the current working directory.
+
+=back
+
+=head1 FILES
+
+=over 4
+
+=item F<debian/debputy.manifest>
+
+Please see F</usr/share/doc/dh-debputy/MANIFEST-FORMAT.md.gz> for details on the format.
+
+If you are converting your first package, you may want to read
+F</usr/share/doc/dh-debputy/GETTING-STARTED-WITH-dh-debputy.md.gz> first.
+
+Unlike most debhelper like tools, this file is per source package rather than
+per binary package. Therefore, you I<cannot> use F<< debian/I<package>.debputy.manifest >>
+to provide a specialized manifest for I<package>. Instead, all the needed parts
+should be written into the manifest itself.
+
+The B<--debputy-manifest> option can be used to have B<debputy> process manifest other
+than F<debian/debputy.manifest>, which may be useful for testing or running
+B<debputy check-manifest> but not much else.
+
+=back
+
+=head1 INTEGRATION LEVELS
+
+The B<debputy> has multiple levels of integrations, which defines how much of the packaging
+that B<debputy> is handling relative to the default B<dh> sequence. The following integrations
+levels are available:
+
+=over 4
+
+=item dh-sequence-zz-debputy-rrr
+
+This integration level replaces the minimal number of commands necessary to provide B<Rules-Requires-Root: no>
+support for B<any> package (even those needing static ownership). The sequence is often compatible with
+other B<debhelper> sequences. To use this B<debputy> integration level, any custom file ownership and
+mode I<should> be migrated to the B<debian/debputy.manifest>. Custom binary package version (B<-v> to
+B<dpkg-gencontrol>) is supported via the manifest. In this integration level, the B<installations>
+keyword and all B<install rules> cannot be used. Installing files into the package is still done via
+helpers such as B<dh_install>.
+
+This migration level corresponds to a B<Build-Depends> on B<dh-sequence-zz-debputy-rrr>.
+
+The following debhelper commands are removed:
+
+=over 4
+
+=item -
+
+dh_fixperms
+
+=item -
+
+dh_gencontrol
+
+=item -
+
+dh_md5sums
+
+=item -
+
+dh_builddeb
+
+=back
+
+=item dh-sequence-zz-debputy
+
+With this integration level, B<debputy> will take over all installation of files into the packages.
+This will replace basically all commands after the B<dh_auto_install> command in the standard B<dh> sequence.
+This also makes the integration level incompatible with many debhelper add-ons, since they expect to run after
+B<dh_auto_install> and assume contents will be materialized into F<< debian/I<package> >>.
+
+This migration level corresponds to a B<Build-Depends> on B<dh-sequence-debputy> or B<dh-sequence-zz-debputy>.
+
+=back
+
+=head1 SEE ALSO
+
+L<dh_debputy(1)>
+
+=head1 AUTHOR
+
+Niels Thykier <niels@thykier.net>
+
+=cut