1<!--
2SPDX-FileCopyrightText: Amolith <amolith@secluded.site>
3
4SPDX-License-Identifier: CC0-1.0
5-->
6
7# Willow
8
9[![Go report card status][goreportcard-badge]][goreportcard]
10[![REUSE status][reuse-shield]][reuse]
11[![Donate with fosspay][fosspay-shield]][fosspay]
12
13_Forge-agnostic software release tracker_
14
15
16
17_This UI is Amolith's attempt at a balance between simple, pleasant, and
18functional. Amolith is not a UX professional and would **very** much welcome
19input from someone more knowledgeable!_
20
21## What is it?
22
23_If you'd rather watch a short video, Amolith gave a 5-minute [lightning talk on
24Willow] at the 2023 Ubuntu Summit._
25
26[lightning talk on Willow]: https://youtu.be/XIGxKyekvBQ?t=29900
27
28Willow helps developers, sysadmins, and homelabbers keep up with software
29releases across arbitrary forge platforms, including full-featured forges like
30GitHub, GitLab, or [Forgejo] as well as more minimal options like [cgit] or
31[stagit].
32
33[Forgejo]: https://forgejo.org/
34[cgit]: https://git.zx2c4.com/cgit/
35[stagit]: https://codemadness.org/stagit.html
36
37It exists because decentralisation, as wonderful as it is, does have some pain
38points. One piece of software is on GitHub, another piece is on GitLab, one on
39Bitbucket, a fourth on [SourceHut], a fifth on the developer's self-hosted
40Forgejo instance.
41
42[SourceHut]: https://sourcehut.org/
43
44The capabilities of each platform can also differ, further complicating the
45space. For example, Forgejo and GitHub have APIs and RSS release feeds,
46SourceHut has an API and RSS feeds that notify you of _all_ activity in the
47repo, GitLab only has an API, and there's no standard for discovering the
48capabilities of arbitrary git frontends like [legit].
49
50[legit]: https://github.com/icyphox/legit
51
52And _then_ you have different pieces of information in different places; some
53developers might publish release announcements on their personal blog and some
54projects might release security advisories on an external platform prior to
55publishing a release.
56
57All this important info is scattered all over the internet. Willow brings some
58order to that chaos by supporting both RSS and one of the _very_ few things all
59the forges and frontends have in common: their **V**ersion **C**ontrol
60**S**ystem. At the moment, [Git] is the _only_ supported VCS, but we're
61definitely interested in adding support for [Pijul], [Fossil], [Mercurial], and
62potentially others.
63
64[Git]: https://git-scm.com/
65[Pijul]: https://pijul.org/
66[Fossil]: https://www.fossil-scm.org/
67[Mercurial]: https://www.mercurial-scm.org/
68
69Amolith (the creator) has recorded some of his other ideas, thoughts, and plans
70in [his wiki].
71
72[his wiki]: https://wiki.secluded.site/hypha/willow
73
74## Installation and use
75
76**Disclaimers:**
771. Prebuilt binaries will be available with the [v0.0.1] release, greatly
78 simplifying installation.
792. We consider the project _alpha-quality_. There will be bugs.
803. Amolith has tried to make the web UI accessible, but is unsure of its current
81 usability.
824. The app is not localised yet and English is the only available language.
835. Help with any/all of the above is most welcome!
84
85[v0.0.1]: https://todo.sr.ht/~amolith/willow?search=status%3Aopen%20label%3A%22v0.0.1%22
86[communication platforms]: #contributing
87
88### Installation
89
90This assumes Willow will run on an always-on server, like a VPS.
91
92* Clone the repo with `git clone https://git.sr.ht/~amolith/willow`
93* Enter the repo's folder with `cd willow`
94* Build the binary with `CGO_ENABLED=0 go build -ldflags="-s -w" -o willow
95 ./cmd`
96* Transfer the binary to the server however you like
97* Execute the binary with `./willow`
98* Edit the config with `vim config.toml`
99* Daemonise Willow using systemd or OpenRC or whatever you prefer
100* Reverse-proxy the web UI (defaults to `localhost:1313`) with Caddy or NGINX or
101 whatever you prefer
102
103### Use
104
105* Create a user with `./willow -a <username>`
106* Open the web UI (defaults to `localhost:1313`, but [installation] had you put
107 a proxy in front)
108* Click `Track new project`
109* Fill out the form and press `Next`
110* Indicate which version you're currently on and press `Track releases`
111* You're now tracking that project's releases!
112
113[installation]: #installation
114
115If you no longer use that project, click the `Delete?` link to remove it, and,
116if applicable, Willow's copy of its repo.
117
118If you're no longer running the version Willow says you've selected, click the
119`Modify?` link to select a different version.
120
121If there are projects where your selected version does _not_ match what Willow
122thinks is latest, they'll show up at the top under the **Outdated projects**
123heading and have a link at the bottom of the card to `View release notes`.
124Clicking that link populates the right column with those release notes.
125
126If there are projects where your selected version _does_ match what Willow
127thinks is latest, they'll show up at the bottom under the **Up-to-date
128projects** heading.
129
130## Contributing
131
132Contributions are very much welcome! Please take a look at the [ticket
133tracker][todo] and see if there's anything you're interested in working on. If
134there's specific functionality you'd like to see implemented and it's not
135mentioned in the ticket tracker, please describe it through one of [the
136communication platforms](#communication) below so we can discuss its inclusion.
137If we don't feel like it fits with Willow's goals, you're encouraged to fork the
138project and make whatever changes you like!
139
140### Collaboration
141
142Some people dislike GitHub, some people dislike SourceHut, and some people
143dislike both. Collaboration happens on multiple platforms so anyone can
144contribute to Willow however they like. Any of the following are suitable, but
145they're listed in order of Amolith's preference:
146
147- [SourceHut]
148 - **Distributed:** contributions are either through [git send-email], which
149 requires you to have SMTP access to an email address, or through SourceHut's
150 web UI, which requires a SourceHut account.
151 - **Open source:** SourceHut components are licenced under AGPL, BSD, and
152 possibly others.
153- [Radicle]
154 - **Distributed:** contributions are through the [Heartwood protocol], which
155 requires you to at least set up a local Radicle node.
156 - **Open source:** Radicle components are licenced under Apache, MIT, GPL, and
157 possibly others.
158- [Codeberg]
159 - **Centralised:** contributions are through Codeberg pull requests and
160 require a Codeberg account.
161 - **Open source:** Codeberg is powered by Forgejo, which is licensed under MIT.
162- [GitHub]
163 - **Centralised:** contributions are through GitHub pull requests and require
164 a GitHub account.
165 - **Mixed:** _components_ of GitHub are open source, such as the syntax
166 highlighter, but everything that makes GitHub _useful_ is proprietary.
167
168[SourceHut]: https://sr.ht/~amolith/willow
169[git send-email]: https://git-send-email.io
170[Radicle]: https://app.radicle.xyz/nodes/radicle.secluded.site/rad:z34saeE8jnN5KbGRuLSggJ3eeLtew
171[Heartwood protocol]: https://radicle.xyz/guides/protocol
172[Codeberg]: https://codeberg.org/Amolith/willow
173[GitHub]: https://github.com/Amolith/willow
174
175### Communication
176
177Questions, comments, and patches can always go to the [mailing list][email], but
178there's also an [IRC channel][irc] and an [XMPP MUC][xmpp] for real-time
179interactions.
180
181- Email: [~amolith/willow@lists.sr.ht][email]
182- IRC: [irc.libera.chat/#willow][irc]
183- XMPP: [willow@muc.secluded.site][xmpp]
184
185[email]: mailto:~amolith/willow@lists.sr.ht
186[irc]: ircs://irc.libera.chat/#willow
187[xmpp]: xmpp:willow@muc.secluded.site?join
188[todo]: https://todo.sr.ht/~amolith/willow
189
190_If you haven't used mailing lists before, please take a look at [SourceHut's
191documentation](https://man.sr.ht/lists.sr.ht/), especially the etiquette
192section._
193
194### Configuring git...
195
196…for <code>git send-email</code>
197
198``` shell
199git config sendemail.to "~amolith/willow@lists.sr.ht"
200git config format.subjectPrefix "PATCH willow"
201git send-email [HASH]
202```
203
204…for signing the [DCO]
205
206``` shell
207git config format.signOff yes
208```
209
210[DCO]: https://developercertificate.org/
211
212### Required tools
213
214- [Go](https://go.dev/)
215- [gofumpt](https://github.com/mvdan/gofumpt)
216 - Stricter formatting rules than the default `go fmt`
217- [golangci-lint](https://golangci-lint.run/)
218 - Aggregates various preinstalled Go linters, runs them in parallel, and makes
219 heavy use of the Go build cache
220- [Staticcheck](https://staticcheck.dev/)
221 - Uses static analysis to find bugs and performance issues, offer
222 simplifications, and enforce style rules
223
224### Suggested tools
225
226- [just](https://github.com/casey/just)
227 - Command runner to simplify use of the required tools
228- [air](https://github.com/cosmtrek/air)
229 - Watches source files and rebuilds/executes the project when sources change
230
231[goreportcard-badge]: https://goreportcard.com/badge/git.sr.ht/~amolith/willow
232[goreportcard]: https://goreportcard.com/report/git.sr.ht/~amolith/willow
233[reuse]: https://api.reuse.software/info/git.sr.ht/~amolith/willow
234[reuse-shield]: https://shields.io/reuse/compliance/git.sr.ht/~amolith/willow
235[fosspay]: https://secluded.site/donate/
236[fosspay-shield]: https://shields.io/badge/donate-fosspay-yellow