Adding upstream version 1:2.11.upstream/1%2.11

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

1 files changed, 191 insertions, 0 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..9c8292c
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,191 @@
+# Contributing to bash-completion
+
+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.
+
+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
+  presence of one of those languages.
+
+  For example, if you were writing completion code for perldoc(1), the
+  use of Perl to achieve your goal would be acceptable. irb(1)
+  completion would similarly make the use of Ruby acceptable.
+
+  Even so, please consider alternatives to these large and slow to
+  start interpreters. Use lightweight programs such as grep(1), awk(1)
+  and sed(1).
+
+- Use the full power of bash >= 4.2. We no longer support earlier bash
+  versions, so you may as well use all the features of that version of
+  bash to optimise your code. However, be careful when using features
+  added since bash 4.2, since not everyone will be able to use them.
+
+  For example, extended globs often enable you to avoid the use of
+  external programs, which are expensive to fork and execute, so do
+  make full use of those:
+
+  `?(pattern-list)` - match zero or one occurrences of patterns
+  `*(pattern-list)` - match zero or more occurrences of patterns
+  `+(pattern-list)` - match one or more occurrences of patterns
+  `@(pattern-list)` - match exactly one of the given patterns
+  `!(pattern-list)` - match anything except one of the given patterns
+
+- Following on from the last point, be sparing with the use of
+  external processes whenever you can. Completion functions need to be
+  fast, so sacrificing some code legibility for speed is acceptable.
+
+  For example, judicious use of sed(1) can save you from having to
+  call grep(1) and pipe the output to cut(1), which saves a fork(2)
+  and exec(3).
+
+  Sometimes you don't even need sed(1) or other external programs at
+  all, though. Use of constructs such as `${parameter#word}`,
+  `${parameter%word}` and `${parameter/pattern/string}` can provide
+  you a lot of power without having to leave the shell.
+
+  For example, if `$foo` contains the path to an executable,
+  `${foo##*/}` will give you the basename of the program, without
+  having to call basename(1). Similarly, `${foo%/*}` will give you the
+  dirname, without having to call dirname(1).
+
+  As another example,
+
+  ```shell
+  bar=$(echo $foo | command sed -e 's/bar/baz/g')
+  ```
+
+  can be replaced by:
+
+  ```shell
+  bar=${foo//bar/baz}
+  ```
+
+  These forms of parameter substitutions can also be used on arrays,
+  which makes them very powerful (if a little slow).
+
+- We want our completions to work in `posix` and `nounset` modes.
+
+  Unfortunately due to a bash < 5.1 bug, toggling POSIX mode interferes
+  with keybindings and should not be done. This rules out use of
+  process substitution which causes syntax errors in POSIX mode.
+
+  Instead of toggling `nounset` mode, make sure to test whether
+  variables are set (e.g. with `[[ -v varname ]]`) or use default
+  expansion (e.g. `${varname-}`).
+
+- Prefer `compgen -W '...' -- $cur` over embedding `$cur` in external
+  command arguments (often e.g. sed, grep etc) unless there's a good
+  reason to embed it. Embedding user input in command lines can result
+  in syntax errors and other undesired behavior, or messy quoting
+  requirements when the input contains unusual characters. Good
+  reasons for embedding include functionality (if the thing does not
+  sanely work otherwise) or performance (if it makes a big difference
+  in speed), but all embedding cases should be documented with
+  rationale in comments in the code.
+
+- When completing available options, offer only the most descriptive
+  ones as completion results if there are multiple options that do the
+  same thing. Usually this means that long options should be preferred
+  over the corresponding short ones. This way the user is more likely
+  to find what she's looking for and there's not too much noise to
+  choose from, and there are less situations where user choice would
+  be needed in the first place. Note that this concerns only display
+  of available completions; argument processing/completion for options
+  that take an argument should be made to work with all known variants
+  for the functionality at hand. For example if `-s`, `-S`, and
+  `--something` do the same thing and require an argument, offer only
+  `--something` as a completion when completing option names starting
+  with a dash, but do implement required argument processing for all
+  `-s`, `-S`, and `--something`.  Note that GNU versions of various
+  standard commands tend to have long options while other userland
+  implementations of the same commands may not have them, and it would
+  be good to have the completions work for as many userlands as
+  possible so things aren't always that simple.
+
+- Do not write to the file-system under any circumstances. This can
+  create race conditions, is inefficient, violates the principle of
+  least surprise and lacks robustness.
+
+- Use printf(1) instead of echo(1) for portability reasons, and be
+  sure to invoke commands that are often found aliased (such as `ls`
+  or `grep` etc) using the `command` (or `builtin`) command as
+  appropriate.
+
+- Make small, incremental commits that do one thing. Don't cram
+  unrelated changes into a single commit.
+
+- If your code was written for a particular platform, try to make it
+  portable to other platforms, so that everyone may enjoy it. If your
+  code works only with the version of a binary on a particular
+  platform, ensure that it will not be loaded on other platforms that
+  have a command with the same name.
+
+  In particular, do not use GNU extensions to commands like sed and
+  awk if you can write your code another way. If you really, REALLY must
+  use them, do so if there's no other sane way to do what you're doing.
+  The "Shell and Utilities" volume of the POSIX specification is a good
+  starting reference for portable use of various utilities, see
+  <https://pubs.opengroup.org/onlinepubs/9699919799/>.
+
+- Use an editor that supports EditorConfig, see <https://editorconfig.org/>,
+  and format source code according to our settings.
+
+- Read the existing source code for examples of how to solve
+  particular problems. Read the bash man page for details of all the
+  programming tools available to you within the shell.
+
+- Please test your code thoroughly before sending it to us. We don't
+  have access to all the commands for which we are sent completion
+  functions, so we are unable to test them all personally. If your
+  code is accepted into the distribution, a lot of people will try it
+  out, so try to do a thorough job of eradicating all the bugs before
+  you send it to us. If at all practical, **add test cases** to our
+  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.
+
+- 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 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,
+  send them as attachments formatted by `git format-patch` or directly
+  with `git send-email`.