mdebray/tvl-depot
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: Update CONTRIBUTING file to match depot structure

Browse source
This commit is contained in:
Vincent Ambo 2019-12-20 19:53:17 +00:00
parent 384ade5e39
commit c9c27e833c
1 changed files with 51 additions and 47 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

98
CONTRIBUTING.md
View file

@ -13,33 +13,29 @@ Contribution Guidelines
<!-- markdown-toc end --> <!-- markdown-toc end -->
This is a loose set of "guidelines" for contributing to journaldriver. This is a loose set of "guidelines" for contributing to my depot. Please note
Please note that we will not accept any pull requests that don't that I will not accept any patches that don't follow these guidelines.
follow these guidelines.
Also consider the [code of conduct](CODE_OF_CONDUCT.md). No really, Also consider the [code of conduct](CODE_OF_CONDUCT.md). No really, you should.
you should.
## Before making a change ## Before making a change
Before making a change, consider your motivation for making the Before making a change, consider your motivation for making the change.
change. Documentation updates, bug fixes and the like are *always* Documentation updates, bug fixes and the like are *always* welcome.
welcome.
When adding a feature you should consider whether it is only useful When adding a feature you should consider whether it is only useful for your
for your particular use-case or whether it is generally applicable for particular use-case or whether it is generally applicable for other users of the
other users of the project. 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 ## Commit messages
All commit messages should follow the style-guide used by the [Angular All commit messages should be structured like this:
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 type(scope): Subject line with at most a 68 character length
Body of the commit message with an empty line between subject and 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 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 * `test`: Added missing tests / fixed tests
* `chore`: Maintenance work * `chore`: Maintenance work
And `scope` should refer to some kind of logical grouping inside of And `scope` should refer to some kind of logical grouping inside of the project.
the project.
Please take a look at the existing commit log for examples. Please take a look at the existing commit log for examples.
## Commit content ## Commit content
Multiple changes should be divided into multiple git commits whenever Multiple changes should be divided into multiple git commits whenever possible.
possible. Common sense applies. Common sense applies.
The fix for a single-line whitespace issue is fine to include in a The fix for a single-line whitespace issue is fine to include in a different
different commit. Introducing a new feature and refactoring commit. Introducing a new feature and refactoring (unrelated) code in the same
(unrelated) code in the same commit is not fine. commit is not fine.
`git commit -a` is generally **taboo**. `git commit -a` is generally **taboo**.
In my experience making "sane" commits becomes *significantly* easier In my experience making "sane" commits becomes *significantly* easier as
as developer tooling is improved. The interface to `git` that I developer tooling is improved. The interface to `git` that I recommend is
recommend is [magit][]. Even if you are not yet an Emacs user, it [magit][]. Even if you are not yet an Emacs user, it makes sense to install
makes sense to install Emacs just to be able to use magit - it is Emacs just to be able to use magit - it is really that good.
really that good.
For staging sane chunks on the command line with only git, consider For staging sane chunks on the command line with only git, consider `git add
`git add -p`. -p`.
## Code quality ## Code quality
This one should go without saying - but please ensure that your code This one should go without saying - but please ensure that your code quality
quality does not fall below the rest of the project. This is of course does not fall below the rest of the project. This is of course very subjective,
very subjective, but as an example if you place code that throws away but as an example if you place code that throws away errors into a block in
errors into a block in which errors are handled properly your change which errors are handled properly your change will be rejected.
will be rejected.
In my experience there is a strong correlation between the visual In my experience there is a strong correlation between the visual appearance of
appearance of a code block and its quality. This is a simple way to a code block and its quality. This is a simple way to sanity-check your work
sanity-check your work while squinting and keeping some distance from while squinting and keeping some distance from your screen ;-)
your screen ;-)
## Builds & tests ## Builds & tests
Most of my projects are built using [Nix][] to avoid "build pollution" My projects are built using [Nix][] to avoid "build pollution" via the user's
via the user's environment. If you have Nix installed and are environment.
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 If you have Nix installed and are contributing to a project tracked in this
your change. 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/ [magit]: https://magit.vc/
[Nix]: https://nixos.org/nix/ [Nix]: https://nixos.org/nix/
[public group]: https://groups.google.com/a/tazj.in/forum/#!forum/reviews