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
 42    GPLv3.
 43- [GitHub]
 44  - **Centralised:** contributions are through GitHub pull requests and require
 45    a GitHub account.
 46  - **Mixed:** _components_ of GitHub are open source, such as the syntax
 47    highlighter, but everything that makes GitHub _useful_ is proprietary.
 48
 49[SourceHut]: https://sr.ht/~amolith/willow
 50[git send-email]: https://git-send-email.io
 51[Radicle]: https://radicle.secluded.site/nodes/seed.secluded.site/rad:z34saeE8jnN5KbGRuLSggJ3eeLtew
 52[Heartwood protocol]: https://radicle.xyz/guides/protocol
 53[Codeberg]: https://codeberg.org/Amolith/willow
 54[GitHub]: https://github.com/Amolith/willow
 55
 56### Communication
 57
 58Questions, comments, and patches can always go to the [mailing list][email], but
 59there's also an [IRC channel][irc] and an [XMPP MUC][xmpp] for real-time
 60interactions.
 61
 62- Email: [~amolith/willow@lists.sr.ht][email]
 63- IRC: [irc.libera.chat/#willow][irc]
 64- XMPP: [willow@muc.secluded.site][xmpp]
 65
 66[email]: mailto:~amolith/willow@lists.sr.ht
 67[irc]: ircs://irc.libera.chat/#willow
 68[xmpp]: xmpp:willow@muc.secluded.site?join
 69[todo]: https://todo.sr.ht/~amolith/willow
 70
 71_If you haven't used mailing lists before, please take a look at [SourceHut's
 72documentation](https://man.sr.ht/lists.sr.ht/), especially the etiquette
 73section._
 74
 75### Before committing anything...
 76
 77Please make sure you configure git to sign [the DCO] in each commit. We won't
 78accept contributions without DCO signatures.
 79
 80``` shell
 81git config format.signOff yes
 82```
 83
 84[the DCO]: https://developercertificate.org/
 85
 86### Required tools
 87
 88- [Go](https://go.dev/)
 89- [gofumpt](https://github.com/mvdan/gofumpt)
 90  - Stricter formatting rules than the default `go fmt`
 91- [golangci-lint](https://golangci-lint.run/)
 92  - Aggregates various preinstalled Go linters, runs them in parallel, and makes
 93    heavy use of the Go build cache
 94- [Staticcheck](https://staticcheck.dev/)
 95  - Uses static analysis to find bugs and performance issues, offer
 96    simplifications, and enforce style rules
 97
 98### Suggested tools
 99
100- [just](https://github.com/casey/just)
101  - Command runner to simplify use of the required tools
102- [air](https://github.com/cosmtrek/air)
103  - Watches source files and rebuilds/executes the project when sources change
104
105#### Using Air
106
107Running `air` with no arguments from inside Willow's repo launches Air using our
108supplied config. Willow runs on [localhost:1313](http://localhost:1313) directly
109and Air proxies Willow at [localhost:8888](http://localhost:8888) to provide
110live reloading. Air notices when you save source files, rebuilds and re-launches
111the binary automatically, and reloads the page in your browser for you.