Migrate documentation from packaging-style-guide to docs/

docs/modules/ROOT/pages/cops_packaging.adoc

@@ -39,14 +39,48 @@ require "foo"
 | 0.1
 |===
 
-This cop flags the usage of `git ls-files` in gemspec
-and suggests to use a plain Ruby alternative, like `Dir`,
-`Dir.glob`, or `Rake::FileList` instead.
+Avoid using `git ls-files` to produce lists of files. Downstreams often need to build your
+package in an environment that does not have git (on purpose). Instead, use some
+pure Ruby alternatives, like `Dir` or `Dir.glob`.
 
-More information about the GemspecGit cop can be found here:
-https://packaging.rubystyle.guide/#gemspec-git
+=== Rationale [[gemspec-git-rationale]]
 
-=== Examples
+Packages in Debian are built in a clean environment (https://wiki.debian.org/sbuild[sbuild],
+https://wiki.debian.org/Schroot[schroot], et al) and whilst doing so, the build fails with: +
+`Invalid gemspec in [<gem_name>.gemspec]: No such file or directory - git`
+
+And adding `git` as a dependency for each of the Ruby packaging is something that is not right
+and definitely not recommended. Besides, the source package consists of released tarballs
+(usually downloaded from GitHub/GitLab releases page or converted from the `.gem` file,
+obtained using `gem fetch foo`), which is extracted during build. So even if we add `git` as
+a build dependency, it would still fail as the Debian package source tree is *not a git repo*.
+Even when the package is maintained in git, it is uploaded as tarballs to the archive without
+any version control information.
+
+Therefore, the only way forward here is to patch out the usage of `git` and use some plain Ruby
+alternatives like `Dir` or `Dir.glob` or even `Rake::FileList` whilst doing the Debian
+maintenance.
+
+There's not only Debian or other OS packaging situation/examples, but also a couple of others,
+for instance:
+
+* `ruby-core` as part of their CI system runs their test suite against an unpackaged Ruby
+  tarball which doesn't have a `.git` directory. That means they needed to overwrite the
+  bundler gemspec to not use git. +
+  Actually, not anymore, https://github.com/rubygems/bundler/pull/6985[since git has been removed from bundler's gemspec].
+
+* If you build your application on a bare docker image without git, and you are pointing to
+  a git sourced gem that uses git on its gemspec, you'll get:
+  `No such file or directory - git ls-files (Errno::ENOENT)` warnings all around. For
+  example, if you use this in your Gemfile: +
+  `gem "foo", git: "https://github.com/has-git-in-gemspec/foo"`
+
+Originally, `git ls-files` inside the default gemspec template was designed so that users
+publishing their first gem wouldn't unintentionally publish artifacts to it.
+Recent versions of bundler won't let you release if you have uncommitted files in your
+working directory, so that risk is lower.
+
+=== Examples [[gemspec-git-examples]]
 
 [source,ruby]
 ----
@@ -101,14 +135,28 @@ end
 | 0.3
 |===
 
-This cop flags the `require_relative` calls, from anywhere
-mapping to the "lib" directory, except originating from lib/ or
-the gemspec file, and suggests to use `require` instead.
+Avoid using `require_relative` with relative path to lib. Use `require` instead.
 
-More information about the RequireRelativeHardcodingLib cop can be found here:
-https://packaging.rubystyle.guide/#require-relative-hardcoding-lib
+=== Rationale [[require-relative-hardcoding-lib-rationale]]
 
-=== Examples
+Debian has a https://ci.debian.net/[testing infrastructure] that is designed to test packages
+in their installed form, i.e., closer to how an end-user would use it than to how a developer
+working against it. For this to work, the test-suite must load code that's installed
+system-wide, instead of the code in the source tree. Using `require_relative` from the tests
+into the `lib` directory makes that impossible, but it also makes the test look less like
+client-code that would use the code in your gem. Therefore, we recommend that test code uses
+the main library code without `require_relative`.
+
+Therefore, when one uses a relative path, we end up getting a `LoadError`, stating: +
+`cannot load such file -- /<<PKGBUILDDIR>>/foo`.
+
+We want to emphasize that *there is nothing wrong* with using `require_relative` inside `lib/`,
+it's just using it from your test code to the `lib` directory prevents the "test the library
+installed system-wide" use case.
+
+Therefore, it is still recommended to use `require_relative` with just this exception to it.
+
+=== Examples [[require-relative-hardcoding-lib-rationale]]
 
 [source,ruby]
 ----

lib/rubocop/cop/packaging/gemspec_git.rb

@@ -7,9 +7,6 @@ module Packaging # :nodoc:
       # and suggests to use a plain Ruby alternative, like `Dir`,
       # `Dir.glob`, or `Rake::FileList` instead.
       #
-      # More information about the GemspecGit cop can be found here:
-      # https://packaging.rubystyle.guide/#gemspec-git
-      #
       # @example
       #
       #   # bad

lib/rubocop/cop/packaging/require_relative_hardcoding_lib.rb

@@ -9,9 +9,6 @@ module Packaging # :nodoc:
       # mapping to the "lib" directory, except originating from lib/ or
       # the gemspec file, and suggests to use `require` instead.
       #
-      # More information about the RequireRelativeHardcodingLib cop can be found here:
-      # https://packaging.rubystyle.guide/#require-relative-hardcoding-lib
-      #
       # @example
       #
       #   # bad