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 something simple and functional, yet still
18friendly and pleasant. Amolith is not a UX professional and would **very** much
19welcome input from one!_
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. The capabilities of each platform can differ as well, making
41the problem even more difficult to solve. Forgejo and GitHub have RSS feeds that
42notify you of releases as well as APIs. SourceHut has both an API and firehose
43RSS feeds that notify you of _all_ activity in the repo. GitLab only has an API.
44Some release announcements might be on the developer's personal blog. Sometimes
45there's a CVE announcement prior to a release and those get published on a
46different platform entirely. It's a mess to keep up with.
47
48[SourceHut]: https://sourcehut.org/
49
50Willow brings some order to that mess by supporting both RSS and one of the
51_very_ few things all the forges have in common: their **V**ersion **C**ontrol
52**S**ystem. At the moment, [Git] is the _only_ supported VCS, but we're
53definitely interested in adding support for [Pijul], [Fossil], [Mercurial], and
54potentially others.
55
56[Git]: https://git-scm.com/
57[Pijul]: https://pijul.org/
58[Fossil]: https://www.fossil-scm.org/
59[Mercurial]: https://www.mercurial-scm.org/
60
61Amolith has recorded some of his other ideas, thoughts, and plans in [his wiki].
62
63[his wiki]: https://wiki.secluded.site/hypha/willow
64
65## Installation and use
66
67_**Note:** prebuilt binaries will be available after we release [v0.0.1]_
68
69[v0.0.1]: https://todo.sr.ht/~amolith/willow?search=status%3Aopen%20label%3A%22v0.0.1%22
70
71* Clone the repo
72* Build the binary with `CGO_ENABLED=0 go build -ldflags="-s -w" -o willow ./cmd`
73* Upload it to a remote server
74* Execute the binary
75* Edit the `config.toml`
76* Create a user with `./willow -a <username>`
77* Execute the binary again
78* Reverse proxy `http://localhost:1313`
79* Open the web UI
80* Click `Track new project`
81* Fill out the form
82* Indicate which version you're currently on
83* That's it!
84
85Note that we still consider the project to be in _alpha_ state. There _will_ be
86bugs; please help fix them!
87
88## Contributing
89
90Contributions are very much welcome! Please take a look at the [ticket
91tracker][todo] and see if there's anything you're interested in working on. If
92there's specific functionality you'd like to see implemented and it's not
93mentioned in the ticket tracker, please describe it through one of the platforms
94below so we can discuss its inclusion. If we don't feel like it fits with
95Willow's goals, you're encouraged to fork the project and make whatever changes
96you like!
97
98Questions, comments, and patches can always go to the [mailing list][email], but
99there's also an [IRC channel][irc] and an [XMPP MUC][xmpp] for real-time
100interactions.
101
102- Email: [~amolith/willow@lists.sr.ht][email]
103- IRC: [irc.libera.chat/#willow][irc]
104- XMPP: [willow@muc.secluded.site][xmpp]
105
106[email]: mailto:~amolith/willow@lists.sr.ht
107[irc]: ircs://irc.libera.chat/#willow
108[xmpp]: xmpp:willow@muc.secluded.site?join
109[todo]: https://todo.sr.ht/~amolith/willow
110
111_If you haven't used mailing lists before, please take a look at [SourceHut's
112documentation](https://man.sr.ht/lists.sr.ht/), especially the etiquette
113section._
114
115### Configuring git...
116
117…for <code>git send-email</code>
118
119``` shell
120git config sendemail.to "~amolith/willow@lists.sr.ht"
121git config format.subjectPrefix "PATCH willow"
122git send-email [HASH]
123```
124
125…for signing the [DCO]
126
127``` shell
128git config format.signOff yes
129```
130
131[DCO]: https://developercertificate.org/
132
133### Required tools
134
135- [Go](https://go.dev/)
136- [gofumpt](https://github.com/mvdan/gofumpt)
137 - Stricter formatting rules than the default `go fmt`
138- [golangci-lint](https://golangci-lint.run/)
139 - Aggregates various preinstalled Go linters, runs them in parallel, and makes
140 heavy use of the Go build cache
141- [Staticcheck](https://staticcheck.dev/)
142 - Uses static analysis to find bugs and performance issues, offer
143 simplifications, and enforce style rules
144
145### Suggested tools
146
147- [just](https://github.com/casey/just)
148 - Command runner to simplify use of the required tools
149- [air](https://github.com/cosmtrek/air)
150 - Watches source files and rebuilds/executes the project when sources change
151
152[goreportcard-badge]: https://goreportcard.com/badge/git.sr.ht/~amolith/willow
153[goreportcard]: https://goreportcard.com/report/git.sr.ht/~amolith/willow
154[reuse]: https://api.reuse.software/info/git.sr.ht/~amolith/willow
155[reuse-shield]: https://shields.io/reuse/compliance/git.sr.ht/~amolith/willow
156[fosspay]: https://secluded.site/donate/
157[fosspay-shield]: https://shields.io/badge/donate-fosspay-yellow