CONTRIBUTING.md

Contributing to Willow

Let us know if anything's missing from here and we'll expand it!

Contributions are very much welcome! Please take a look at the ticket tracker and see if there's anything you're interested in working on. If there's specific functionality you'd like to see implemented and it's not mentioned in the ticket tracker, please describe it through one of the communication platforms below so we can discuss its inclusion. If we don't feel like it fits with Willow's goals, you're encouraged to fork the project and make whatever changes you like!

Collaboration

Some people dislike GitHub, some people dislike SourceHut, and some people dislike both. Collaboration happens on multiple platforms so anyone can contribute to Willow however they like. Any of the following are suitable, but they're listed in order of Amolith's preference:

  • SourceHut
    • Distributed: contributions are either through git send-email, which requires you to have SMTP access to an email address, or through SourceHut's web UI, which requires a SourceHut account.
    • Open source: SourceHut components are licenced under AGPL, BSD, and possibly others.
    • Configuring git for git send-email (click to expand) git-send-email.io is a great resource for getting started. Please run the following commands before submitting patches to Willow. 
      git config sendemail.to "~amolith/willow@lists.sr.ht"
git config format.subjectPrefix "PATCH willow"
  • Radicle
    • Distributed: contributions are through the Heartwood protocol, which requires you to at least set up a local Radicle node.
    • Open source: Radicle components are licenced under Apache, MIT, GPL, and possibly others.
  • Codeberg
    • Centralised: contributions are through Codeberg pull requests and require a Codeberg account.
    • Open source: Codeberg is powered by Forgejo, which is licensed under MIT.
  • GitHub
    • Centralised: contributions are through GitHub pull requests and require a GitHub account.
    • Mixed: components of GitHub are open source, such as the syntax highlighter, but everything that makes GitHub useful is proprietary.

Communication

Questions, comments, and patches can always go to the mailing list, but there's also an IRC channel and an XMPP MUC for real-time interactions.

If you haven't used mailing lists before, please take a look at SourceHut's documentation, especially the etiquette section.

Before committing anything...

Please make sure you configure git to sign the DCO in each commit. We won't accept contributions without DCO signatures.

git config format.signOff yes

Required tools

  • Go
  • gofumpt
    • Stricter formatting rules than the default go fmt
  • golangci-lint
    • Aggregates various preinstalled Go linters, runs them in parallel, and makes heavy use of the Go build cache
  • Staticcheck
    • Uses static analysis to find bugs and performance issues, offer simplifications, and enforce style rules

Suggested tools

  • just
    • Command runner to simplify use of the required tools
  • air
    • Watches source files and rebuilds/executes the project when sources change

Using Air

Running air with no arguments from inside Willow's repo launches Air using our supplied config. Willow runs on localhost:1313 directly and Air proxies Willow at localhost:8888 to provide live reloading. Air notices when you save source files, rebuilds and re-launches the binary automatically, and reloads the page in your browser for you.