docs: Add contributing
Signed-off-by: Tim Hårek Andreassen <tim@harek.no>
This commit is contained in:
Tim Hårek Andreassen
parent
5fb146f602
commit
eda33958a8
2 changed files with 102 additions and 1 deletions
83
CONTRIBUTING.md
Normal file
83
CONTRIBUTING.md
Normal file
|
|
@ -0,0 +1,83 @@
|
||||||
|
# Contribution Guidelines
|
||||||
|
|
||||||
|
This document contains guidelines for contributing code to `yr`. It has to be
|
||||||
|
followed in order for your patch to be approved and applied.
|
||||||
|
|
||||||
|
## Contribution Channels
|
||||||
|
|
||||||
|
Anyone can contribute to `yr`. First you need to clone the repository and build
|
||||||
|
the project:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git clone https://git.sr.ht/~timharek/yr
|
||||||
|
cd yr
|
||||||
|
```
|
||||||
|
|
||||||
|
Patch the code. Write some tests. Ensure that your code is properly formatted
|
||||||
|
with `just fmt`. Ensure that everything builds and works as expected. Ensure
|
||||||
|
that you did not break anything.
|
||||||
|
|
||||||
|
- If applicable, update unit tests.
|
||||||
|
- If adding a new feature, please consider adding new tests.
|
||||||
|
- Do not forget to update the docs.
|
||||||
|
|
||||||
|
Once you are happy with your work, you can create a commit (or several
|
||||||
|
commits). Follow these general rules:
|
||||||
|
|
||||||
|
- Limit the first line (title) of the commit message to 60 characters.
|
||||||
|
- Use a short prefix for the commit title for readability with `git log --oneline`.
|
||||||
|
- Use the body of the commit message to actually explain what your patch does
|
||||||
|
and why it is useful. Even if your patch is a one line fix, the description
|
||||||
|
is not limited in length and may span over multiple paragraphs. Use proper
|
||||||
|
English syntax, grammar and punctuation.
|
||||||
|
- Address only one issue/topic per commit.
|
||||||
|
- Describe your changes in imperative mood, e.g. _"make xyzzy do frotz"_
|
||||||
|
instead of _"[This patch] makes xyzzy do frotz"_ or _"[I] changed xyzzy to do
|
||||||
|
frotz"_, as if you are giving orders to the codebase to change its behaviour.
|
||||||
|
- If you are fixing a ticket, use appropriate
|
||||||
|
[commit trailers](https://man.sr.ht/git.sr.ht/#referencing-tickets-in-git-commit-messages).
|
||||||
|
- If you are fixing a regression introduced by another commit, add a `Fixes:`
|
||||||
|
trailer with the commit id and its title.
|
||||||
|
- When in doubt, follow the format and layout of the recent existing commits.
|
||||||
|
|
||||||
|
There is a great reference for commit messages in the
|
||||||
|
[Linux kernel documentation](https://www.kernel.org/doc/html/latest/process/submitting-patches.html#describe-your-changes).
|
||||||
|
|
||||||
|
Before sending the patch, you should configure your local clone with sane
|
||||||
|
defaults using `deno task setup:srht`:
|
||||||
|
|
||||||
|
And send the patch to the mailing list ([step-by-step
|
||||||
|
instructions][git-send-email-tutorial]):
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git send-email --annotate -1
|
||||||
|
```
|
||||||
|
|
||||||
|
Before your patch can be applied, it needs to be reviewed and approved by
|
||||||
|
others. They will indicate their approval by replying to your patch with
|
||||||
|
a [Tested-by, Reviewed-by or Acked-by][linux-review] (see also: [the git
|
||||||
|
wiki][git-trailers]) trailer. For example:
|
||||||
|
|
||||||
|
You can follow the review process via email and on the [web ui][web-ui].
|
||||||
|
|
||||||
|
Wait for feedback. Address comments and amend changes to your original commit.
|
||||||
|
Then you should send a v2 (and maybe a v3, v4, etc.):
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git send-email --annotate v2 -1
|
||||||
|
```
|
||||||
|
|
||||||
|
Be polite, patient and address _all_ of the reviewers' remarks. If you disagree
|
||||||
|
with something, feel free to discuss it.
|
||||||
|
|
||||||
|
Once your patch has been reviewed and approved (and if the maintainer is OK
|
||||||
|
with it), it will be applied and pushed.
|
||||||
|
|
||||||
|
IMPORTANT: Do NOT use `--in-reply-to` when sending followup versions of a patch
|
||||||
|
set. It causes multiple versions of the same patch to be merged under v1 in the
|
||||||
|
[web ui][web-ui]
|
||||||
|
|
||||||
|
[web-ui]: https://lists.sr.ht/~timharek/yr/patches
|
||||||
|
[git-send-email-tutorial]: https://git-send-email.io/
|
||||||
|
[git-trailers]: https://git.wiki.kernel.org/index.php/CommitMessageConventions
|
||||||
|
[linux-review]: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#using-reported-by-tested-by-reviewed-by-suggested-by-and-fixes
|
||||||
20
README.md
20
README.md
|
|
@ -1,7 +1,10 @@
|
||||||
# yr
|
# [yr]
|
||||||
|
|
||||||
Get the weather delivered to your command-line.
|
Get the weather delivered to your command-line.
|
||||||
|
|
||||||
|
The project uses [Meteorologisk institutt]'s public API, [`LocationForecast`],
|
||||||
|
and [OpenStreetMap]'s [Nominatim] API.
|
||||||
|
|
||||||
## Usage
|
## Usage
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
|
|
@ -26,3 +29,18 @@ yr forecast "new york" --web
|
||||||
# Open now in your web browser
|
# Open now in your web browser
|
||||||
yr now "new york" --web
|
yr now "new york" --web
|
||||||
```
|
```
|
||||||
|
|
||||||
|
## Contributing
|
||||||
|
|
||||||
|
Anyone can contribute to [yr]. Please refer to the [contribution guidelines].
|
||||||
|
|
||||||
|
Send patches to the [mailing list], report bugs on the [issue tracker].
|
||||||
|
|
||||||
|
[yr]: https://sr.ht/~timharek/yr/
|
||||||
|
[Meteorologisk institutt]: https://www.met.no/
|
||||||
|
[`LocationForecast`]: https://api.met.no/weatherapi/locationforecast/2.0/documentation
|
||||||
|
[OpenStreetMap]: https://www.openstreetmap.org/
|
||||||
|
[Nominatim]: https://nominatim.org/
|
||||||
|
[mailing list]: https://lists.sr.ht/~timharek/yr
|
||||||
|
[issue tracker]: https://todo.sr.ht/~timharek/yr
|
||||||
|
[contribution guidelines]: ./CONTRIBUTING.md
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue