1<!--
  2SPDX-FileCopyrightText: Amolith <amolith@secluded.site>
  3
  4SPDX-License-Identifier: CC0-1.0
  5-->
  6
  7# Contributing to Willow
  8
  9_Let us know if anything's missing from here and we'll expand it!_
 10
 11Contributions are very much welcome! Please take a look at the [ticket
 12tracker][todo] and see if there's anything you're interested in working on. If
 13there's specific functionality you'd like to see implemented and it's not
 14mentioned in the ticket tracker, please describe it through one of [the
 15communication platforms](#communication) below so we can discuss its inclusion.
 16If we don't feel like it fits with Willow's goals, you're encouraged to fork the
 17project and make whatever changes you like!
 18
 19### Collaboration
 20
 21Some people dislike GitHub, some people dislike SourceHut, and some people
 22dislike both. Collaboration happens on multiple platforms so anyone can
 23contribute to Willow however they like. Any of the following are suitable, but
 24they're listed in order of Amolith's preference:
 25
 26- [SourceHut]
 27  - **Distributed:** contributions are either through [git send-email], which
 28    requires you to have SMTP access to an email address, or through SourceHut's
 29    web UI, which requires a SourceHut account.
 30  - **Open source:** SourceHut components are licenced under AGPL, BSD, and
 31    possibly others.
 32  - <details><summary>Configuring git for <code>git send-email</code> (click to expand)</summary>
 33    <a href="https://git-send-email.io">git-send-email.io</a> is a great resource for getting started. Please run the following commands before submitting patches to Willow.
 34    <pre>
 35    git config sendemail.to "~amolith/willow@lists.sr.ht"
 36    git config format.subjectPrefix "PATCH willow"
 37    </pre>
 38    </details>
 39- [Radicle]
 40  - **Distributed:** contributions are through the [Heartwood protocol], which
 41    requires you to at least set up a local Radicle node.
 42  - **Open source:** Radicle components are licenced under Apache, MIT, GPL, and
 43    possibly others.
 44- [Codeberg]
 45  - **Centralised:** contributions are through Codeberg pull requests and
 46    require a Codeberg account.
 47  - **Open source:** Codeberg is powered by Forgejo, which is licensed under
 48    GPLv3.
 49- [GitHub]
 50  - **Centralised:** contributions are through GitHub pull requests and require
 51    a GitHub account.
 52  - **Mixed:** _components_ of GitHub are open source, such as the syntax
 53    highlighter, but everything that makes GitHub _useful_ is proprietary.
 54
 55[SourceHut]: https://sr.ht/~amolith/willow
 56[git send-email]: https://git-send-email.io
 57[Radicle]: https://radicle.secluded.site/nodes/seed.secluded.site/rad:z34saeE8jnN5KbGRuLSggJ3eeLtew
 58[Heartwood protocol]: https://radicle.xyz/guides/protocol
 59[Codeberg]: https://codeberg.org/Amolith/willow
 60[GitHub]: https://github.com/Amolith/willow
 61
 62### Communication
 63
 64Questions, comments, and patches can always go to the [mailing list][email], but
 65there's also an [IRC channel][irc] and an [XMPP MUC][xmpp] for real-time
 66interactions.
 67
 68- Email: [~amolith/willow@lists.sr.ht][email]
 69- IRC: [irc.libera.chat/#willow][irc]
 70- XMPP: [willow@muc.secluded.site][xmpp]
 71
 72[email]: mailto:~amolith/willow@lists.sr.ht
 73[irc]: ircs://irc.libera.chat/#willow
 74[xmpp]: xmpp:willow@muc.secluded.site?join
 75[todo]: https://todo.sr.ht/~amolith/willow
 76
 77_If you haven't used mailing lists before, please take a look at [SourceHut's
 78documentation](https://man.sr.ht/lists.sr.ht/), especially the etiquette
 79section._
 80
 81### Before committing anything...
 82
 83Please make sure you configure git to sign [the DCO] in each commit. We won't
 84accept contributions without DCO signatures.
 85
 86``` shell
 87git config format.signOff yes
 88```
 89
 90[the DCO]: https://developercertificate.org/
 91
 92### Required tools
 93
 94- [Go](https://go.dev/)
 95- [gofumpt](https://github.com/mvdan/gofumpt)
 96  - Stricter formatting rules than the default `go fmt`
 97- [golangci-lint](https://golangci-lint.run/)
 98  - Aggregates various preinstalled Go linters, runs them in parallel, and makes
 99    heavy use of the Go build cache
100- [Staticcheck](https://staticcheck.dev/)
101  - Uses static analysis to find bugs and performance issues, offer
102    simplifications, and enforce style rules
103
104### Suggested tools
105
106- [just](https://github.com/casey/just)
107  - Command runner to simplify use of the required tools
108- [air](https://github.com/cosmtrek/air)
109  - Watches source files and rebuilds/executes the project when sources change
110
111#### Using Air
112
113Running `air` with no arguments from inside Willow's repo launches Air using our
114supplied config. Willow runs on [localhost:1313](http://localhost:1313) directly
115and Air proxies Willow at [localhost:8888](http://localhost:8888) to provide
116live reloading. Air notices when you save source files, rebuilds and re-launches
117the binary automatically, and reloads the page in your browser for you.