New upstream version 2.9upstream/2.9

1 files changed, 42 insertions, 5 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 41287366..44865ba7 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -4,8 +4,39 @@ Contributions to the bash completion project are more than
 welcome. Fixes, clean-ups and improvements of existing code are much
 appreciated, as are completion functions for new commands.
 
-If you wish to contribute code, please bare the following coding
-guidelines in mind:
+However, before submitting a completion to us, first consider submitting it to
+the project that ships the commands your completion is for. Having the
+completion shipped along with the command opens up some liberties we don't have
+if the completion is included with bash-completion. For example, we generally
+do not want to hardcode lists of available command options and their
+completions, because they quite probably vary between versions of the completed
+command, and therefore resort to scraping --help output and the like. While we
+do fairly well there, depending on the command, this can be fragile or
+expensive, or just not possible. If the completion is shipped alongside the
+command, they can be kept in sync and use more hardcoding etc. They are also
+more likely to be maintained and/or watched by people intimately familiar with
+the completed commands. See instructions in README.md how to install completion
+files from other projects so they are automatically enabled and dynamically
+loaded by bash-completion.
+
+On the other hand, we do have a pretty nice test suite and a bunch of helper
+functions that you may find useful. And a whole slew of completions in one
+package. Our functions can be used from "external" completions as well, just
+make sure you test for their existence and/or fail gracefully if you intend
+your completion to be usable without having bash-completion installed.
+
+It's nowhere near clear cut always what is the best place for the completion,
+upstream project or us. Even if it would seem to be upstream, not all upstreams
+are interested in shipping completions, or their install systems might not
+easily support installing completion files properly. But give it some thought,
+and ask if unsure.
+
+If you wish to contribute code to us, volunteering for long term maintainership
+of your code within bash-completion is welcome. When exactly you will be asked
+to do that depends on the case; don't be disappointed if it does or doesn't
+happen instantly.
+
+Also, please bare the following coding guidelines in mind:
 
 - Do not use Perl, Ruby, Python etc. to do text processing unless the
   command for which you are writing the completion code implies the
@@ -55,7 +86,7 @@ guidelines in mind:
   As another example,
 
   ```shell
-  bar=$( echo $foo | sed -e 's/bar/baz/g' )
+  bar=$(echo $foo | command sed -e 's/bar/baz/g')
   ```
 
   can be replaced by:
@@ -137,9 +168,15 @@ guidelines in mind:
   test suite (in the test/ dir) that verify that the code does what it
   is intended to do, fixes issues it intends to fix, etc.
 
+- In addition to running the test suite, there are a few scripts in the test/
+  dir that catch some common issues, see and use for example runLint and
+  run-shellcheck.
+
 - File bugs, enhancement, and pull requests at GitHub,
-  https://github.com/scop/bash-completion
-  Sending them to the developers might work too, but is really
+  https://github.com/scop/bash-completion or send them to the email
+  gateway address bash-completion@fire.fundersclub.com which will pipe
+  them to GitHub issues (with your email address visible).
+  Sending them to the developers might work too, but is really strongly
   discouraged as bits are more likely to fall through the cracks that
   way compared to the tracker. Just use GitHub. If that's not an
   option for some reason and you want to use email to send patches,