about summary refs log tree commit diff
path: root/CONTRIBUTING.md
diff options
context:
space:
mode:
authorVincent Ambo <tazjin@google.com>2019-12-20T19·53+0000
committerVincent Ambo <tazjin@google.com>2019-12-20T19·53+0000
commitc9c27e833cdae4c08cffb64de0c6af2532785d38 (patch)
tree1ce1afa3a9f5c9a54c6451e3ab5df4530020e669 /CONTRIBUTING.md
parent384ade5e3903f92c28aad81e12c6d00180df5982 (diff)
docs: Update CONTRIBUTING file to match depot structure r/234
Diffstat (limited to 'CONTRIBUTING.md')
-rw-r--r--CONTRIBUTING.md98
1 files changed, 51 insertions, 47 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index a001f977765e..8037e1bf7fd6 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -13,33 +13,29 @@ Contribution Guidelines
 
 <!-- markdown-toc end -->
 
-This is a loose set of "guidelines" for contributing to journaldriver.
-Please note that we will not accept any pull requests that don't
-follow these guidelines.
+This is a loose set of "guidelines" for contributing to my depot. Please note
+that I will not accept any patches that don't follow these guidelines.
 
-Also consider the [code of conduct](CODE_OF_CONDUCT.md). No really,
-you should.
+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.
+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 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!
+When in doubt - just ask! You can reach out to me via
+[mail](mailto:mail@tazj.in) or on Twitter / IRC / etc.
 
 ## 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:
+All commit messages should be structured like this:
 
 ```
-type(scope): Subject line with at most 68 a character length
+type(scope): Subject line with at most a 68 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
@@ -58,57 +54,65 @@ Where `type` can be one of:
 * `test`: Added missing tests / fixed tests
 * `chore`: Maintenance work
 
-And `scope` should refer to some kind of logical grouping inside of
-the project.
+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.
+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.
+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.
+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`.
+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.
+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 ;-)
+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.
+My projects are built using [Nix][] to avoid "build pollution" via the user's
+environment.
 
-If the project has tests, check that they still work before submitting
-your change.
+If you have Nix installed and are contributing to a project tracked in this
+repository, you can usually build the project by calling `nix-build -A
+path.to.project`.
 
-Both of these will usually be covered by Travis CI.
+For example, to build a project located at `tools/foo` you would call `nix-build
+-A tools.foo`
 
+If the project has tests, check that they still work before submitting your
+change.
+
+## Submitting patches
+
+When making a change, please create an appropriate commit locally and send it to
+me using either `git send-email` or `git format-patch`. The email address to use
+for depot reviews is `reviews@tazj.in`, which is a [public group][].
+
+I recognise that most people are used to a GitHub-style workflow. If you run
+into issues with the above but would still like to contribute, feel free to
+reach out to me.
 
-[Angular project]: https://gist.github.com/stephenparish/9941e89d80e2bc58a153#format-of-the-commit-message
 [magit]: https://magit.vc/
 [Nix]: https://nixos.org/nix/
+[public group]: https://groups.google.com/a/tazj.in/forum/#!forum/reviews