1  <!--
  2  SPDX-FileCopyrightText: Amolith <amolith@secluded.site>
  3  
  4  SPDX-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  
 11  Contributions are very much welcome! Please take a look at the [ticket
 12  tracker][todo] and see if there's anything you're interested in working on. If
 13  there's specific functionality you'd like to see implemented and it's not
 14  mentioned in the ticket tracker, please describe it through one of [the
 15  communication platforms](#communication) below so we can discuss its inclusion.
 16  If we don't feel like it fits with Willow's goals, you're encouraged to fork the
 17  project and make whatever changes you like!
 18  
 19  ### Collaboration
 20  
 21  Some people dislike GitHub, some people dislike SourceHut, and some people
 22  dislike both. Collaboration happens on multiple platforms so anyone can
 23  contribute to Willow however they like. Any of the following are suitable, but
 24  they'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:z2R511nZ7T9wNg4L148JALPEZY8dx
 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  
 64  Questions, comments, and patches can always go to the [mailing list][email], but
 65  there's also an [IRC channel][irc] and an [XMPP MUC][xmpp] for real-time
 66  interactions.
 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
 78  documentation](https://man.sr.ht/lists.sr.ht/), especially the etiquette
 79  section._
 80  
 81  ### Before committing anything...
 82  
 83  Please make sure you configure git to sign [the DCO] in each commit. We won't
 84  accept contributions without DCO signatures.
 85  
 86  ``` shell
 87  git 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  
113  Running `air` with no arguments from inside Willow's repo launches Air using our
114  supplied config. Willow runs on [localhost:1313](http://localhost:1313) directly
115  and Air proxies Willow at [localhost:8888](http://localhost:8888) to provide
116  live reloading. Air notices when you save source files, rebuilds and re-launches
117  the binary automatically, and reloads the page in your browser for you.