Adding upstream version 0.1.22.upstream/0.1.22

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 54 insertions, 22 deletions

diff --git a/debputy.pod b/debputy.pod
index 593f02d..e01f5a5 100644
--- a/debputy.pod
+++ b/debputy.pod
@@ -50,6 +50,10 @@ The B<migrate-from-dh> command will attempt to migrate the current package to B<
 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.
 
+If you are looking to migrate to B<debputy> from B<dh>, you may want to have a look at the
+B<GETTING-STARTED-WITH-dh-debputy.md> file (in the source root or in F</usr/share/doc/>). That document
+is a how-to guide that as extended advice on migration from B<dh>.
+
 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
@@ -57,15 +61,16 @@ 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.
+for B<dh-sequence-zz-debputy-rrr> (assuming no other markers are present). 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 non default 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.
+is supposed, but the reverse is not. Use of version control is recommended for undoing transition if
+necessary.
 
 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
@@ -92,6 +97,11 @@ 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.
 
+In some cases, it might be helpful to comment out the offending feature and re-run the migration rather
+than using B<--acceptable.migration-issues>. As an example, if a single line of F<debian/install> file
+is problematic, commenting it out will have B<debputy> migrate the rest of the file for you leaving you
+only to manually migrate a single line.
+
 =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
@@ -103,7 +113,7 @@ control systems. If support for detecting version control systems is added, this
 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.
+The B<--no-act> is an alias of B<--no-apply-changes> to match the name that B<debhelper> commands use.
 
 =back
 
@@ -165,15 +175,15 @@ A short comparison of B<debputy lint> vs. other tools:
 =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
+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.
+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>
 
@@ -210,7 +220,7 @@ Start the B<debputy> language server (per B<Language Server Protocol> specificat
 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>.
+formats such as B<debian/control>, B<debian/changelog> and B<debian/copyright> (DEP-5).
 
 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
@@ -255,8 +265,15 @@ in B<debputy lint> is that you cannot interactively choose which quickfix to app
 
 On save actions (currently only "prune trailing whitespace").
 
+=item -
+
+Folding ranges (multi-line comments).
+
 =back
 
+Note these features are subject to the editor supporting them, correct language IDs being
+passed to B<debputy>, etc.
+
 =item lsp editor-config B<EDITOR>
 
 Provide an example configuration glue for using the B<debputy lsp server> with the given editor
@@ -373,25 +390,25 @@ 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)
+=item pluggable-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.
+pluggable 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>,
+When used with B<list>, B<debputy> will list all pluggable 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
+    debputy plugin show pluggable-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
+    debputy plugin show pluggable-manifest-rules TransformationRule::remove
+    debputy plugin show pluggable-manifest-rules DpkgMaintscriptHelperCommand::remove
 
 Note the type names (such as B<TransformationRule>) are currently an implementation detail and may change in the
 future.
@@ -458,7 +475,7 @@ As an example:
 
 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.
+pluggable manifest rules.
 
 When used with B<show NAME>, any plugin provided documentation and example inputs will be displayed
 for that rule.
@@ -583,9 +600,7 @@ This integration level replaces the minimal number of commands necessary to prov
 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>.
+B<dpkg-gencontrol>) is supported via the manifest.
 
 This migration level corresponds to a B<Build-Depends> on B<dh-sequence-zz-debputy-rrr>.
 
@@ -611,6 +626,23 @@ dh_builddeb
 
 =back
 
+Note the following B<debputy> features are disabled in this integration mode:
+
+=over 4
+
+=item -
+
+Installation rule (the B<installations> keyword in the manifest). Any installation of content
+that should go resulting B<.deb> or B<.udeb> should happen via B<debhelper>'s mechanisms such
+as B<dh_install>.
+
+=item -
+
+Metadata detectors from plugins. Instead, substvars, maintscripts and triggers are handled and generated
+per B<debhelper> conventions.
+
+=back
+
 =item dh-sequence-zz-debputy
 
 With this integration level, B<debputy> will take over all installation of files into the packages.