From 198fe2bffa69c8baccb38ba2412faf24681ee29c Mon Sep 17 00:00:00 2001 From: Vincent Ambo Date: Tue, 26 Feb 2019 17:28:51 +0100 Subject: [PATCH] docs: Update README, add contribution guidelines & CoC ... getting all the docs in order for publication ... --- CODE_OF_CONDUCT.md | 29 +++++++++++ CONTRIBUTING.md | 113 ++++++++++++++++++++++++++++++++++++++++ README.org => README.md | 4 +- 3 files changed, 145 insertions(+), 1 deletion(-) create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md rename README.org => README.md (50%) diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 000000000..0e46bbedb --- /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 000000000..b7d66d8ee --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,113 @@ +Contribution Guidelines +======================= + + +**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) + + + +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 similarity index 50% rename from README.org rename to README.md index 73e371512..b33b161eb 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