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