Merge branch 'en/flesh-out-docs' into master

The prerequisites and installation docs were not quite detailed enough,
and no code of conduct or contribution guidelines were included.  Flesh
out the docs to cover these issues.

Signed-off-by: Elijah Newren <newren@gmail.com>

Documentation/Contributing.md

@@ -0,0 +1,66 @@
+Welcome to the community!
+
+There are a few filter-repo specific guidelines to keep in mind:
+
+  * Please test line coverage if you add or modify code
+
+    * `make test` will run the testsuite under
+      [coverage3](https://pypi.org/project/coverage/) (which you will
+      need to install), and report on line coverage.  Line coverage of
+      git-filter-repo needs to remain at 100%.
+
+  * Please do not be intimidated by detailed feedback:
+
+    * In the git community, I have been contributing for years and
+      have had hundreds of patches accepted but I still find that even
+      when I try to make patches perfect I am not surprised when I
+      have to spend as much or more time fixing up patches after
+      submitting them than I did figuring out the patches in the first
+      place.  git folks tend to do thorough reviews, which has taught
+      me a lot, and I try to do the same for filter-repo.
+
+Other than those specific notes, contributions to filter-repo should
+generally follow the same [guidelines for contribution to
+git.git](https://git.kernel.org/pub/scm/git/git.git/tree/Documentation/SubmittingPatches).  Exceptions:
+
+  * While I
+    [hate](https://public-inbox.org/git/CABPp-BG2SkH0GrRYpHLfp2Wey91ThwQoTgf9UmPa9f5Szn+v3Q@mail.gmail.com/)
+    [GitHub](https://public-inbox.org/git/CABPp-BEcpasV4vBTm0uxQ4Vzm88MQAX-ArDG4e9QU8tEoNsZWw@mail.gmail.com/)
+    [PRs](https://public-inbox.org/git/CABPp-BEHy8c3raHwf9aFXvXN0smf_WwCcNiYxQBwh7W6An60qQ@mail.gmail.com/),
+    git-format-patch and git-send-email can be a beast and I have not
+    yet found time to modify Dscho's excellent
+    [GitGitGadget](https://github.com/gitgitgadget/gitgitgadget) to
+    work with git-filter-repo.  As such:
+      * For very short single-commit changes, feel free to open GitHub PRs.
+      * For more involved changes, if format-patch or send-email give you
+        too much trouble, go ahead and open a GitHub PR and just mention
+        that email didn't work out.
+  * When emailing the git list:
+    * Include "filter-repo" at the start of the subject,
+      e.g. "[filter-repo PATCH] Add packaging scripts for uploading to PyPI"
+      instead of just "[PATCH] Add packaging scripts for uploading to PyPI"
+    * CC me instead of the git maintainer
+  * Git's [CodingGuidlines for python
+    code](https://github.com/git/git/blob/v2.24.0/Documentation/CodingGuidelines#L482-L494)
+    are only partially applicable:
+    * python3 is a hard requirement; python2 is/was EOL at the end of
+      2019 and should not be used.  (Commit 4d0264ab723c
+      ("filter-repo: workaround python<2.7.9 exec bug", 2019-04-30)
+      was the last version of filter-repo that worked with python2).
+    * You can depend on anything in python 3.5 or earlier.  I may bump
+      this minimum version over time, but do want to generally work
+      with the python3 version found in current enterprise Linux
+      distributions.
+    * In filter-repo, it's not just OK to use bytestrings, you are
+      expected to use them a lot.  Using unicode strings result in
+      lots of ugly errors since input comes from filesystem names,
+      commit messages, file contents, etc., none of which are
+      guaranteed to be unicode.  (Plus unicode strings require lots of
+      effort to verify, encode, and decode -- slowing the filtering
+      process down).  I tried to work with unicode strings more
+      broadly in the code base multiple times; but it's just a bad
+      idea to use an abstraction that doesn't fit the data.
+    * I generally like [PEP
+      8](https://www.python.org/dev/peps/pep-0008/), but have used
+      two-space indents for years anyway -- and expect contributions
+      to do the same.

INSTALL

@@ -5,6 +5,11 @@ filter-repo only consists of a few files that need to be installed:
     This can be installed in the directory pointed to by `git --exec-path`,
     or placed anywhere in $PATH.  This is the only thing needed for basic use.
 
+    If your python3 executable is named "python" instead of "python3"
+    (this particularly appears to affect a number of Windows users),
+    then you'll also need to modify the first line of git-filter-repo
+    to replace "python3" with "python".
+
   * git_filter_repo.py
 
     If you want to make use of one of the scripts in contrib/filter-repo-demos/,
@@ -28,3 +33,7 @@ that prefer it.  However, usage of the Makefile really requires overridding
 at least a couple of the directories with sane values, e.g.
 
     $ make prefix=/usr pythondir=/usr/lib64/python3.8/site-packages install
+
+Also, the Makefile will not edit the shebang line (the first line) of
+git-filter-repo if your python executable is not named "python3";
+you'll still need to do that yourself.

README.md

@@ -14,16 +14,10 @@ contains a library for creating history rewriting tools.  As such, users
 with specialized needs can leverage it to quickly create [entirely new
 history rewriting tools](contrib/filter-repo-demos).
 
-filter-repo requires a fairly [recent version of
-git](#upstream-improvements) (git >= 2.22.0 at a minimum, newer versions
-are needed for some features).
-
-filter-repo is a single-file python script, depending only on the python
-standard library (and execution of git commands), all of which is designed
-to make build/installation trivial: just copy it into your $PATH.
-
 # Table of Contents
 
+  * [Prerequisites](#prerequisites)
+  * [How do I install it?](#how-do-i-install-it)
   * [How do I use it?](#how-do-i-use-it)
   * [Why filter-repo instead of other alternatives?](#why-filter-repo-instead-of-other-alternatives)
     * [filter-branch](#filter-branch)
@@ -32,8 +26,32 @@ to make build/installation trivial: just copy it into your $PATH.
     * [Solving this with filter-repo](#solving-this-with-filter-repo)
     * [Solving this with other filtering tools](#solving-this-with-other-filtering-tools)
   * [Design rationale behind filter-repo](#design-rationale-behind-filter-repo)
+  * [How do I contribute?](#how-do-i-contribute)
+  * [Is there a Code of Conduct?](#is-there-a-code-of-conduct)
   * [Upstream Improvements](#upstream-improvements)
 
+# Prerequisites
+
+filter-repo requires:
+
+  * a fairly [recent version of git](#upstream-improvements) (git >=
+    2.22.0 at a minimum, newer versions are needed for some features)
+  * python3 (python >= 3.5)
+
+# How do I install it?
+
+git-filter-repo is a single-file python script, which was done to make
+installation for basic use trivial: just copy it into your $PATH.
+
+See [INSTALL](INSTALL) for things beyond basic usage or special cases.
+The more involved instructions are needed if you
+
+  * are working with a python3 executable named something other than "python3"
+  * want to install documentation
+  * want to run some of the [contrib](contrib/filter-repo-demos/) examples
+  * want to create your own python filtering scripts using filter-repo as a
+    module/library
+
 # How do I use it?
 
 See the [user
@@ -316,6 +334,17 @@ one of the last four traits as well:
 
   1. [Speed] Filtering should be reasonably fast
 
+# How do I contribute?
+
+See the [contributing guidelines](Documentation/Contributing.md).
+
+# Is there a Code of Conduct?
+
+Participants in the filter-repo community are expected to adhere to
+the same standards as for the git project, so the [git Code of
+Conduct](https://git.kernel.org/pub/scm/git/git.git/tree/CODE_OF_CONDUCT.md)
+applies.
+
 # Upstream Improvements
 
 Work on filter-repo and [its

git-filter-repo

@@ -1584,6 +1584,8 @@ class GitUtils(object):
       contents = f.read()
     # If people replaced @@LOCALEDIR@@ string to point at their local
     # directory, undo it so we can get original source version.
+    contents = re.sub(br'^#\!/usr/bin/env python.*',
+                      br'#!/usr/bin/env python3', contents)
     contents = re.sub(br'(\("GIT_TEXTDOMAINDIR"\) or ").*"',
                       br'\1@@LOCALEDIR@@"', contents)
 

t/run_coverage

@@ -24,8 +24,8 @@ export PRETEND_UNICODE_ARGS=1
 ls t939*.sh | xargs -n 1 bash
 
 cd $tmpdir
-python3-coverage combine
-python3-coverage html -d $orig_dir/report
-python3-coverage report -m
+coverage3 combine
+coverage3 html -d $orig_dir/report
+coverage3 report -m
 cd $orig_dir
 rm -rf $tmpdir