doc: add a CONTRIBUTING.md file

1 files changed, 81 insertions, 0 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..68be15d
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,81 @@
+We would love for you to contribute to the Subplot project, in any way
+or form that is good for you. Here are some suggestions to make it as
+easy as possible for us to incorporate your contribution. However, you
+contributing is more important than you following the guidelines
+below.
+
+**Reporting issues, or raising topics for discussion:** Please use the
+GitLab issue tracker. If there's an existing issue for what you want
+to talk about, please use that, but if not, it's preferable to open a
+new issue, as it's easier for the Subplot maintainers to merge issues
+than split them. Add tags if you feel they're relevant, but it's OK to
+not use tags as well. Issue tags exist primarily to help the
+maintainers keep a handle on long lists of issues, and the primary
+responsibility is on the maintainers to add the tags that help them.
+
+**Asking for help:** Please use the GitLab issue tracker for this as
+well.
+
+**Updating documentation, tests, or code:** Please submit a merge
+request via GitLab, or open an issue with a link to a git repository
+and branch we can pull from.
+
+**Running the test suite:** For any and all changes that are meant to
+change the git repository, the full Subplot test suite must pass. To
+run it, use the following command:
+
+~~~sh
+$ ./check -v
+~~~
+
+If you only touch documentation, and don't want to install all the
+build dependencies, you can skip running the tests yourself.
+
+**Code formatting:** Rust code must be formatted as if by the
+`rustfmt` tool. The test suite checks that.
+
+**Rust version:** We aim for Subplot to be buildable on the stable
+version of Debian and the Rust version packaged therein. At this time,
+that's Rust version 1.34.
+
+**Python version:** We require Python code to work on Python 3.7 and
+later, the version in the current stable version of Debian.
+
+**Portability:** We want Subplot and the test programs it generates to
+be portable, but haven't yet defined a list of environments we
+explicitly target, apart from Debian 10 (buster) on 64-bit Intel
+architecture systems ("amd64" in Debian terminology). We try to avoid
+breaking compatibility with other environments (other versions of
+Debian, other Linux distributions, other Unix variants, other
+operating systems) and architecture, but do not currently have the
+ability to test that. (Help would be welcome.)
+
+**Keep commits in a merge request small, related, and integral:** It's
+easier for us to review a small change than a large one, unless the
+changes are highly mechanical. For example, if you rename a function, a
+commit that does that and nothing else can be quite large, but is easy
+to review. If the same commit does other things as well, such as
+adding a new argument to the function, it becomes harder to review.
+Such a change should be split into different commits: one renames the
+function, the other adds the new argument.
+
+Please also keep different commits in the same merge request related
+to each other. If you are adding a new feature to do foo and notice a
+bug in old feature bar, submit foo and the bug fix as separate merge
+requests. This allows us to consider the bug fix independently.
+
+* Try to keep individual commits at 200 lines or less of unified diff
+  patch, unless each "hunk" of the patch is basically identical.
+
+* Each commit should be a cohesive, integral change, and not a mix of
+  unrelated changes.
+
+* Each merge request should consists of related changes, arranged in a
+  way that make the change easy to follow: they "tell a story" of how
+  you would make the set of changes the second time, knowing
+  everything you know after doing them the first time. 
+  
+  The goal is not to show the path you originally took, but show how
+  to get there in the best possible way. You should tell the story of
+  flying by plane, not how Columbus accidentally found a new continent
+  while looking for India.