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:**
77- Docker image coming soon™
78- We consider the project _alpha-quality_. There will be bugs.
79- Amolith has tried to make the web UI accessible, but is unsure of its current
80 usability.
81- The app is not localised yet and English is the only available language.
82- Help with any/all of the above is most welcome!
83
84### Installation
85
86This assumes Willow will run on an always-on server, like a VPS.
87
88- Obtain the binary appropriate for your system from one of the release pages
89 (they're all the same)
90 - [SourceHut](https://git.sr.ht/~amolith/willow/refs)
91 - [Codeberg](https://codeberg.org/Amolith/willow/releases)
92 - [GitHub](https://github.com/Amolith/willow/releases)
93- Make sure you're in the same folder as the binary when running the following
94 commands
95- Mark the binary as executable with `chmod +x willow`
96- Execute the binary with `./willow`
97- Edit the config with `nano config.toml`
98- Daemonise Willow using systemd, OpenRC, etc.
99- Reverse-proxy the web UI (defaults to `localhost:1313`) with Caddy, NGINX,
100 etc.
101
102### Use
103
104- Create a user with `./willow -a <username>`
105- Open the web UI (defaults to `localhost:1313`, but [installation] had you put
106 a proxy in front)
107- Click `Track new project`
108- Fill out the form and press `Next`
109- Indicate which version you're currently on and press `Track releases`
110- You're now tracking that project's releases!
111
112[installation]: #installation
113
114If you no longer use that project, click the `Delete?` link to remove it, and,
115if applicable, Willow's copy of its repo.
116
117If you're no longer running the version Willow says you've selected, click the
118`Modify?` link to select a different version.
119
120If there are projects where your selected version does _not_ match what Willow
121thinks is latest, they'll show up at the top under the **Outdated projects**
122heading and have a link at the bottom of the card to `View release notes`.
123Clicking that link populates the right column with those release notes.
124
125If there are projects where your selected version _does_ match what Willow
126thinks is latest, they'll show up at the bottom under the **Up-to-date
127projects** heading.
128
129### Contributing
130
131See [CONTRIBUTING.md](CONTRIBUTING.md).