diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000000000000000000000000000000000..d465d013d6431d5c01b2cdc5d51ec4101073996d --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,117 @@ +# 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][todo] 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](#communication) 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. + +[SourceHut]: https://sr.ht/~amolith/willow +[git send-email]: https://git-send-email.io +[Radicle]: https://radicle.secluded.site/nodes/seed.secluded.site/rad:z34saeE8jnN5KbGRuLSggJ3eeLtew +[Heartwood protocol]: https://radicle.xyz/guides/protocol +[Codeberg]: https://codeberg.org/Amolith/willow +[GitHub]: https://github.com/Amolith/willow + +### Communication + +Questions, comments, and patches can always go to the [mailing list][email], but +there's also an [IRC channel][irc] and an [XMPP MUC][xmpp] for real-time +interactions. + +- Email: [~amolith/willow@lists.sr.ht][email] +- IRC: [irc.libera.chat/#willow][irc] +- XMPP: [willow@muc.secluded.site][xmpp] + +[email]: mailto:~amolith/willow@lists.sr.ht +[irc]: ircs://irc.libera.chat/#willow +[xmpp]: xmpp:willow@muc.secluded.site?join +[todo]: https://todo.sr.ht/~amolith/willow + +_If you haven't used mailing lists before, please take a look at [SourceHut's +documentation](https://man.sr.ht/lists.sr.ht/), 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. + +``` shell +git config format.signOff yes +``` + +[the DCO]: https://developercertificate.org/ + +### Required tools + +- [Go](https://go.dev/) +- [gofumpt](https://github.com/mvdan/gofumpt) + - Stricter formatting rules than the default `go fmt` +- [golangci-lint](https://golangci-lint.run/) + - Aggregates various preinstalled Go linters, runs them in parallel, and makes + heavy use of the Go build cache +- [Staticcheck](https://staticcheck.dev/) + - Uses static analysis to find bugs and performance issues, offer + simplifications, and enforce style rules + +### Suggested tools + +- [just](https://github.com/casey/just) + - Command runner to simplify use of the required tools +- [air](https://github.com/cosmtrek/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](http://localhost:1313) directly +and Air proxies Willow at [localhost:8888](http://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. + +[goreportcard-badge]: https://goreportcard.com/badge/git.sr.ht/~amolith/willow +[goreportcard]: https://goreportcard.com/report/git.sr.ht/~amolith/willow +[reuse]: https://api.reuse.software/info/git.sr.ht/~amolith/willow +[reuse-shield]: https://shields.io/reuse/compliance/git.sr.ht/~amolith/willow +[fosspay]: https://secluded.site/donate/ +[fosspay-shield]: https://shields.io/badge/donate-fosspay-yellow diff --git a/README.md b/README.md index 44b12757dcc034f94adcb7127b673a8cd265c5fb..e8a6fcfe81aa49b879c61a4d618bc36444acaf21 100644 --- a/README.md +++ b/README.md @@ -126,116 +126,6 @@ If there are projects where your selected version _does_ match what Willow thinks is latest, they'll show up at the bottom under the **Up-to-date projects** heading. -## Contributing - -Contributions are very much welcome! Please take a look at the [ticket -tracker][todo] 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](#communication) 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. - -[SourceHut]: https://sr.ht/~amolith/willow -[git send-email]: https://git-send-email.io -[Radicle]: https://radicle.secluded.site/nodes/seed.secluded.site/rad:z34saeE8jnN5KbGRuLSggJ3eeLtew -[Heartwood protocol]: https://radicle.xyz/guides/protocol -[Codeberg]: https://codeberg.org/Amolith/willow -[GitHub]: https://github.com/Amolith/willow - -### Communication - -Questions, comments, and patches can always go to the [mailing list][email], but -there's also an [IRC channel][irc] and an [XMPP MUC][xmpp] for real-time -interactions. - -- Email: [~amolith/willow@lists.sr.ht][email] -- IRC: [irc.libera.chat/#willow][irc] -- XMPP: [willow@muc.secluded.site][xmpp] - -[email]: mailto:~amolith/willow@lists.sr.ht -[irc]: ircs://irc.libera.chat/#willow -[xmpp]: xmpp:willow@muc.secluded.site?join -[todo]: https://todo.sr.ht/~amolith/willow - -_If you haven't used mailing lists before, please take a look at [SourceHut's -documentation](https://man.sr.ht/lists.sr.ht/), 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. - -``` shell -git config format.signOff yes -``` - -[the DCO]: https://developercertificate.org/ - -### Required tools - -- [Go](https://go.dev/) -- [gofumpt](https://github.com/mvdan/gofumpt) - - Stricter formatting rules than the default `go fmt` -- [golangci-lint](https://golangci-lint.run/) - - Aggregates various preinstalled Go linters, runs them in parallel, and makes - heavy use of the Go build cache -- [Staticcheck](https://staticcheck.dev/) - - Uses static analysis to find bugs and performance issues, offer - simplifications, and enforce style rules - -### Suggested tools - -- [just](https://github.com/casey/just) - - Command runner to simplify use of the required tools -- [air](https://github.com/cosmtrek/air) - - Watches source files and rebuilds/executes the project when sources change - -#### Using Air - -Running Air using Willow's supplied Air configuration: `air -c air.toml` launches Willow on [localhost:1313](http://localhost:1313). - -If you're working on HTML or CSS then use Air's proxy port instead [localhost:8888](http://localhost:8888) to get live reloading in the browser on every source change. - -[goreportcard-badge]: https://goreportcard.com/badge/git.sr.ht/~amolith/willow -[goreportcard]: https://goreportcard.com/report/git.sr.ht/~amolith/willow -[reuse]: https://api.reuse.software/info/git.sr.ht/~amolith/willow -[reuse-shield]: https://shields.io/reuse/compliance/git.sr.ht/~amolith/willow -[fosspay]: https://secluded.site/donate/ -[fosspay-shield]: https://shields.io/badge/donate-fosspay-yellow +### Contributing + +See [CONTRIBUTING.md](CONTRIBUTING.md).