docs: Update README, add contribution guidelines & CoC

... getting all the docs in order for publication ...

3 files changed, 145 insertions, 1 deletions

diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
new file mode 100644
index 0000000000..0e46bbedb0
--- /dev/null
+++ b/CODE_OF_CONDUCT.md
@@ -0,0 +1,29 @@
+A SERMON ON ETHICS AND LOVE
+===========================
+
+One day Mal-2 asked the messenger spirit Saint Gulik to approach the
+Goddess and request Her presence for some desperate advice. Shortly
+afterwards the radio came on by itself, and an ethereal female Voice
+said **YES?**
+
+"O! Eris! Blessed Mother of Man! Queen of Chaos! Daughter of Discord!
+Concubine of Confusion! O! Exquisite Lady, I beseech You to lift a
+heavy burden from my heart!"
+
+**WHAT BOTHERS YOU, MAL? YOU DON'T SOUND WELL.**
+
+"I am filled with fear and tormented with terrible visions of pain.
+Everywhere people are hurting one another, the planet is rampant with
+injustices, whole societies plunder groups of their own people,
+mothers imprison sons, children perish while brothers war. O, woe."
+
+**WHAT IS THE MATTER WITH THAT, IF IT IS WHAT YOU WANT TO DO?**
+
+"But nobody Wants it! Everybody hates it."
+
+**OH. WELL, THEN *STOP*.**
+
+At which moment She turned herself into an aspirin commercial and left
+The Polyfather stranded alone with his species.
+
+SINISTER DEXTER HAS A BROKEN SPIROMETER.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000000..b7d66d8ee3
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,113 @@
+Contribution Guidelines
+=======================
+
+<!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-refresh-toc -->
+**Table of Contents**
+
+- [Contribution Guidelines](#contribution-guidelines)
+    - [Before making a change](#before-making-a-change)
+    - [Commit messages](#commit-messages)
+    - [Commit content](#commit-content)
+    - [Code quality](#code-quality)
+    - [Builds & tests](#builds--tests)
+
+<!-- markdown-toc end -->
+
+This is a loose set of "guidelines" for contributing to my projects.
+Please note that I will not accept any pull requests that don't follow
+these guidelines.
+
+Also consider the [code of conduct](CODE_OF_CONDUCT.md). No really,
+you should.
+
+## Before making a change
+
+Before making a change, consider your motivation for making the
+change. Documentation updates, bug fixes and the like are *always*
+welcome.
+
+When adding a feature you should consider whether it is only useful
+for your particular use-case or whether it is generally applicable for
+other users of the project.
+
+When in doubt - just ask me!
+
+## Commit messages
+
+All commit messages should follow the style-guide used by the [Angular
+project][]. This means for the most part that your commit message
+should be structured like this:
+
+```
+type(scope): Subject line with at most 68 a character length
+
+Body of the commit message with an empty line between subject and
+body. This text should explain what the change does and why it has
+been made, *especially* if it introduces a new feature.
+
+Relevant issues should be mentioned if they exist.
+```
+
+Where `type` can be one of:
+
+* `feat`: A new feature has been introduced
+* `fix`: An issue of some kind has been fixed
+* `docs`: Documentation or comments have been updated
+* `style`: Formatting changes only
+* `refactor`: Hopefully self-explanatory!
+* `test`: Added missing tests / fixed tests
+* `chore`: Maintenance work
+
+And `scope` should refer to some kind of logical grouping inside of
+the project.
+
+Please take a look at the existing commit log for examples.
+
+## Commit content
+
+Multiple changes should be divided into multiple git commits whenever
+possible. Common sense applies.
+
+The fix for a single-line whitespace issue is fine to include in a
+different commit. Introducing a new feature and refactoring
+(unrelated) code in the same commit is not fine.
+
+`git commit -a` is generally **taboo**.
+
+In my experience making "sane" commits becomes *significantly* easier
+as developer tooling is improved. The interface to `git` that I
+recommend is [magit][]. Even if you are not yet an Emacs user, it
+makes sense to install Emacs just to be able to use magit - it is
+really that good.
+
+For staging sane chunks on the command line with only git, consider
+`git add -p`.
+
+## Code quality
+
+This one should go without saying - but please ensure that your code
+quality does not fall below the rest of the project. This is of course
+very subjective, but as an example if you place code that throws away
+errors into a block in which errors are handled properly your change
+will be rejected.
+
+In my experience there is a strong correlation between the visual
+appearance of a code block and its quality. This is a simple way to
+sanity-check your work while squinting and keeping some distance from
+your screen ;-)
+
+## Builds & tests
+
+Most of my projects are built using [Nix][] to avoid "build pollution"
+via the user's environment. If you have Nix installed and are
+contributing to a project that has a `default.nix`, consider using
+`nix-build` to verify that builds work correctly.
+
+If the project has tests, check that they still work before submitting
+your change.
+
+Both of these will usually be covered by Travis CI.
+
+[Angular project]: https://gist.github.com/stephenparish/9941e89d80e2bc58a153#format-of-the-commit-message
+[magit]: https://magit.vc/
+[Nix]: https://nixos.org/nix/
diff --git a/README.org b/README.md
index 73e3715124..b33b161eb8 100644
--- a/README.org
+++ b/README.md
@@ -4,6 +4,8 @@ crimp
 Crimp is an HTTP client interface on top of the [Rust bindings][] to
 cURL.
 
-Please see the module documentation for details on why this exists.
+The documentation for this crate is primarily in the [module
+documentation][]
 
 [Rust bindings]: https://docs.rs/curl
+[module documentation]: https://docs.rs/crimp