|
1 | 1 | # How to contribute |
2 | 2 |
|
3 | 3 | Everyone is welcome to contribute. There is no small contributions. Please take |
4 | | -the time to read this document before starting. |
| 4 | +the time to read this document before starting. We are using [git] on [GitHub]. |
| 5 | +Please ensure to get familiarized with both before starting to contribute. |
5 | 6 |
|
6 | | -## Table of Content |
7 | | - |
8 | | -- [Prerequisites](#prerequisites) |
9 | | -- [Setup](#setup) |
10 | | -- [How to find what to work on](#how-to-find-what-to-work-on) |
11 | | -- [Contribution workflow](#contribution-workflow) |
12 | | - - [Contributing language support](#contributing-language-support) |
13 | | -- [Commit hygiene](#commit-hygiene) |
14 | | - |
15 | | -## Prerequisites |
16 | | - |
17 | | -Before contributing, some prerequisites: |
18 | | - |
19 | | -- You must have [git] installed, as this project uses it as VCS. |
20 | | -- Rust is used to compile everything; you should have [rustup] installed. |
21 | | -- Especially, you want to have `rustc`, `cargo`, `clippy`, `rust-analyzer` and |
22 | | - `rustfmt` installed. |
23 | | -- This project accepts contributions via _git patches_. It is likely that you |
24 | | - are not used to this workflow. A mail client that can send emails in |
25 | | - plain-text mode is highly advised — for instance, [aerc]. More on that in |
26 | | - the [Guidelines](#guidelines) section. |
27 | | -- Not mandatory but highly recommended; you should have a GPG key hosted on a |
28 | | - third-party location — for instance, [keys.openpgp.org] — and sign your |
29 | | - emails with it. More on that in the the [Guidelines](#guidelines) section. |
30 | | - |
31 | | -## Setup |
32 | | - |
33 | | -Before starting up, you need to setup your tools. |
34 | | - |
35 | | -### git send-email |
36 | | - |
37 | | -You should follow [this link](https://git-send-email.io/) as a first source of |
38 | | -information on how to configure `git send-email`. Additionally, you want to |
39 | | -setup the per-project part. |
40 | | - |
41 | | -Contributions must be sent to <~hadronized/kak-tree-sitter-devel@lists.sr.ht>. |
42 | | -Instead of using the `--to` flag everytime you use `git send-email`, you should |
43 | | -edit the local configuration of your repository with: |
44 | | - |
45 | | -```sh |
46 | | -git config --local sendemail.to "~hadronized/kak-tree-sitter-devel@lists.sr.ht" |
47 | | -``` |
48 | | - |
49 | | -You also must set the prefix to `PATCH kak-tree-sitter` — that helps reviewing |
50 | | -and it is also mandatory for the CI to run: |
51 | | - |
52 | | -```sh |
53 | | -git config --local format.subjectprefix "PATCH kak-tree-sitter" |
54 | | -``` |
55 | | - |
56 | | -Once this is done, all you have to do is to use `git send-email` normally. |
57 | | - |
58 | | -> Note: if you would rather go your webmail instead, **ensure it does plain |
59 | | -> text**, and use `git format-patch` accordingly. |
60 | | -
|
61 | | -## How to find what to work on |
62 | | - |
63 | | -You can first check the list of [bugs] and [features] on the bug trackers. If |
64 | | -you cannot find your issue there, you should open one. You can use the UI, or |
65 | | -simply send an email to the appropriate tracker: |
66 | | - |
67 | | -- For bugs, send your email to <~hadronized/kak-tree-sitter-bugs@todo.sr.ht>. |
68 | | -- For features, send your email to <~hadronized/kak-tree-sitter-features@todo.sr.ht>. |
69 | | - |
70 | | -If you are not sure, you can still open a discussion on the |
71 | | -[discuss mailing list], by using the UI or sending an email to |
72 | | -<~hadronized/kak-tree-sitter-discuss@lists.sr.ht>. |
73 | | - |
74 | | -## Contribution workflow |
75 | | - |
76 | | -You have found something to work on and want to start contributing. Follow these |
77 | | -simple steps: |
78 | | - |
79 | | -1. Ensure you have followed the steps in the [Setup](#setup) section. |
80 | | -2. Clone the repository. |
81 | | -3. Create a branch; it will help when sending patches upstream. |
82 | | -4. Make your changes and make some commits! |
83 | | -5. Once ready to get your changes reviewed, send them with |
84 | | - `git send-email master`. |
85 | | -6. Wait for the review and check your inbox. |
86 | | - |
87 | | -If your change was accepted, you should have an email telling you it was |
88 | | -applied. If not, you should repeat the process. |
89 | | - |
90 | | -> Note: please use the `--annotate -v2` flag of `git send-enail` if pushing a |
91 | | -> new version. `-v3` for the next one, etc. etc. |
92 | | -
|
93 | | -### Contributing language support |
| 7 | +## Contributing language support |
94 | 8 |
|
95 | 9 | **An important guideline here**: [Helix](https://helix-editor.com/) is a well |
96 | 10 | appreciated editor and their queries are pretty excellent. You are highly |
@@ -118,23 +32,34 @@ Please refrain from creating gigantic commits. I reserve the right to refuse |
118 | 32 | your patch if it’s not atomic enough: I engage my spare-time to review and |
119 | 33 | understand your code so **please** keep that in mind. |
120 | 34 |
|
121 | | -There is no limit on the number of commits per patch, but keep in mind that |
| 35 | +There is no limit on the number of commits per PR, but keep in mind that |
122 | 36 | individual commits should still remain small enough to be easily reviewable. Try |
123 | | -to scope a patch down to a single ticket, or even subpart of a ticket if you |
124 | | -think it makes sense. |
| 37 | +to scope a PR down to a single issue, or even subpart of a issue if you think |
| 38 | +it makes sense. Remember that PRs are often reviewed commits by commits, so |
| 39 | +ensure a certain coherenc between what to put and what not to put in a commit. |
125 | 40 |
|
126 | | -Also, remember to include the ticket link in your commit, and to write concise |
127 | | -but acute commit messages. Those are used for writing changelog, so please keep |
128 | | -that in mind. Keep the line width to 80-char if possible. |
| 41 | +Also, remember to include the issue number at the end of your commit message |
| 42 | +with a leading dash — e.g. `#123` – and to write concise yet acute commit |
| 43 | +messages. Those are used for writing changelog, so please keep them short. |
129 | 44 |
|
130 | 45 | Finally, **merging `master` into your branch is not appreciated**, and will end |
131 | 46 | up with your patch refused. If you want to “synchronize” your work with the |
132 | | -recent changes, please use `git rebase origin/master`. |
| 47 | +recent changes, please use `git fetch origin && git rebase origin/master` in |
| 48 | +your branch. |
| 49 | + |
| 50 | +## Sign your work |
| 51 | + |
| 52 | +GPG signatures are used to sign our work. The value of signing a piece of code |
| 53 | +doesn’t imply _you_ write it, but it implies you _validated that code_, and in |
| 54 | +the end, we don’t really care whether you wrote the code or whether you |
| 55 | +generated with a fancy A.I. generator. It’s the code you bring and it’s the code |
| 56 | +you sign. |
| 57 | + |
| 58 | +If you plan on contributing more than just one-shot contributions, feel free |
| 59 | +to open a PR to modify the [MAINTAINERS.md] file by providing your name, email |
| 60 | +address and PGP fingerprint. |
133 | 61 |
|
134 | 62 | [git]: https://git-scm.com/ |
135 | | -[rustup]: https://rustup.rs/ |
136 | | -[aerc]: https://aerc-mail.org/ |
| 63 | +[GitHub]: https://github.com/hadronized/kak-tree-sitter |
137 | 64 | [keys.openpgp.org]: https://keys.openpgp.org/ |
138 | | -[bugs]: https://todo.sr.ht/~hadronized/kak-tree-sitter-bugs |
139 | | -[features]: https://todo.sr.ht/~hadronized/kak-tree-sitter-features |
140 | | -[discuss mailing list]: https://lists.sr.ht/~hadronized/kak-tree-sitter-discuss |
| 65 | +[MAINTAINERS.md]: MAINTAINERS.md |
0 commit comments