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[goreportcard-badge]: https://goreportcard.com/badge/git.sr.ht/~amolith/willow
14[goreportcard]: https://goreportcard.com/report/git.sr.ht/~amolith/willow
15[reuse]: https://api.reuse.software/info/git.sr.ht/~amolith/willow
16[reuse-shield]: https://shields.io/reuse/compliance/git.sr.ht/~amolith/willow
17[fosspay]: https://secluded.site/donate/
18[fosspay-shield]: https://shields.io/badge/donate-fosspay-yellow
19
20_Forge-agnostic software release tracker_
21
22
23
24_This UI is Amolith's attempt at a balance between simple, pleasant, and
25functional. Amolith is not a UX professional and would **very** much welcome
26input from someone more knowledgeable!_
27
28## What is it?
29
30_If you'd rather watch a short video, Amolith gave a 5-minute [lightning talk on
31Willow] at the 2023 Ubuntu Summit._
32
33[lightning talk on Willow]: https://youtu.be/XIGxKyekvBQ?t=29900
34
35Willow helps developers, sysadmins, and homelabbers keep up with software
36releases across arbitrary forge platforms, including full-featured forges like
37GitHub, GitLab, or [Forgejo] as well as more minimal options like [cgit] or
38[stagit].
39
40[Forgejo]: https://forgejo.org/
41[cgit]: https://git.zx2c4.com/cgit/
42[stagit]: https://codemadness.org/stagit.html
43
44It exists because decentralisation, as wonderful as it is, does have some pain
45points. One piece of software is on GitHub, another piece is on GitLab, one on
46Bitbucket, a fourth on [SourceHut], a fifth on the developer's self-hosted
47Forgejo instance.
48
49[SourceHut]: https://sourcehut.org/
50
51The capabilities of each platform can also differ, further complicating the
52space. For example, Forgejo and GitHub have APIs and RSS release feeds,
53SourceHut has an API and RSS feeds that notify you of _all_ activity in the
54repo, GitLab only has an API, and there's no standard for discovering the
55capabilities of arbitrary git frontends like [legit].
56
57[legit]: https://github.com/icyphox/legit
58
59And _then_ you have different pieces of information in different places; some
60developers might publish release announcements on their personal blog and some
61projects might release security advisories on an external platform prior to
62publishing a release.
63
64All this important info is scattered all over the internet. Willow brings some
65order to that chaos by supporting both RSS and one of the _very_ few things all
66the forges and frontends have in common: their **V**ersion **C**ontrol
67**S**ystem. At the moment, [Git] is the _only_ supported VCS, but we're
68definitely interested in adding support for [Pijul], [Fossil], [Mercurial], and
69potentially others.
70
71[Git]: https://git-scm.com/
72[Pijul]: https://pijul.org/
73[Fossil]: https://www.fossil-scm.org/
74[Mercurial]: https://www.mercurial-scm.org/
75
76Amolith (the creator) has recorded some of his other ideas, thoughts, and plans
77in [his wiki].
78
79[his wiki]: https://wiki.secluded.site/hypha/willow
80
81## Installation and use
82
83**Disclaimers:**
84- Docker image coming soon™
85- We consider the project _alpha-quality_. There will be bugs.
86- Amolith has tried to make the web UI accessible, but is unsure of its current
87 usability.
88- The app is not localised yet and English is the only available language.
89- Help with any/all of the above is most welcome!
90
91### Installation
92
93This assumes Willow will run on an always-on server, like a VPS.
94
95- Obtain the binary appropriate for your system from one of the release pages
96 (they're all the same)
97 - [SourceHut](https://git.sr.ht/~amolith/willow/refs)
98 - [Codeberg](https://codeberg.org/Amolith/willow/releases)
99 - [GitHub](https://github.com/Amolith/willow/releases)
100- Make sure you're in the same folder as the binary when running the following
101 commands
102- Mark the binary as executable with `chmod +x willow`
103- Execute the binary with `./willow`
104- Edit the config with `nano config.toml`
105- Daemonise Willow using systemd, OpenRC, etc.
106- Reverse-proxy the web UI (defaults to `localhost:1313`) with Caddy, NGINX,
107 etc.
108
109### Use
110
111- Create a user with `./willow -a <username>`
112- Open the web UI (defaults to `localhost:1313`, but [installation] had you put
113 a proxy in front)
114- Click `Track new project`
115- Fill out the form and press `Next`
116- Indicate which version you're currently on and press `Track releases`
117- You're now tracking that project's releases!
118
119[installation]: #installation
120
121If you no longer use that project, click the `Delete?` link to remove it, and,
122if applicable, Willow's copy of its repo.
123
124If you're no longer running the version Willow says you've selected, click the
125`Modify?` link to select a different version.
126
127If there are projects where your selected version does _not_ match what Willow
128thinks is latest, they'll show up at the top under the **Outdated projects**
129heading and have a link at the bottom of the card to `View release notes`.
130Clicking that link populates the right column with those release notes.
131
132If there are projects where your selected version _does_ match what Willow
133thinks is latest, they'll show up at the bottom under the **Up-to-date
134projects** heading.
135
136### Contributing
137
138See [CONTRIBUTING.md](CONTRIBUTING.md).