willow/README.md

5.6 KiB

Willow

Go report card status REUSE status Donate with fosspay

Forge-agnostic software release tracker

screenshot of willow's current web UI

This UI is Amolith's attempt at something simple and functional, yet still friendly and pleasant. Amolith is not a UX professional and would very much welcome input from one!

What is it?

If you'd rather watch a short video, Amolith gave a 5-minute lightning talk on Willow at the 2023 Ubuntu Summit.

Willow helps developers, sysadmins, and homelabbers keep up with software releases across arbitrary forge platforms, including full-featured forges like GitHub, GitLab, or Forgejo as well as more minimal options like cgit or stagit.

It exists because decentralisation, as wonderful as it is, does have some pain points. One piece of software is on GitHub, another piece is on GitLab, one on Bitbucket, a fourth on SourceHut, a fifth on the developer's self-hosted Forgejo instance. The capabilities of each platform can differ as well, making the problem even more difficult to solve. Forgejo and GitHub have RSS feeds that notify you of releases as well as APIs. SourceHut has both an API and firehose RSS feeds that notify you of all activity in the repo. GitLab only has an API. Some release announcements might be on the developer's personal blog. Sometimes there's a CVE announcement prior to a release and those get published on a different platform entirely. It's a mess to keep up with.

Willow brings some order to that mess by supporting both RSS and one of the very few things all the forges have in common: their Version Control System. At the moment, Git is the only supported VCS, but we're definitely interested in adding support for Pijul, Fossil, Mercurial, and potentially others.

Amolith has recorded some of his other ideas, thoughts, and plans in his wiki.

Installation and use

Note: prebuilt binaries will be available after we release v0.0.1

  • Clone the repo
  • Build the binary with CGO_ENABLED=0 go build -ldflags="-s -w" -o willow ./cmd
  • Upload it to a remote server
  • Execute the binary
  • Edit the config.toml
  • Create a user with ./willow -a <username>
  • Execute the binary again
  • Reverse proxy http://localhost:1313
  • Open the web UI
  • Click Track new project
  • Fill out the form
  • Indicate which version you're currently on
  • That's it!

Note that we still consider the project to be in alpha state. There will be bugs; please help fix them!

Contributing

Contributions are very much welcome! Please take a look at the ticket tracker 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 send a description to the mailing list 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!

Questions, comments, and patches can always go to the mailing list, but there's also an IRC channel and an XMPP MUC for real-time interactions.

If you haven't used mailing lists before, please take a look at SourceHut's documentation, especially the etiquette section.

Configuring git...

…for git send-email

git config sendemail.to "~amolith/willow@lists.sr.ht"
git config format.subjectPrefix "PATCH willow"
git send-email [HASH]

…for signing the DCO

git config format.signOff yes

Required tools

  • Go
  • gofumpt
    • Stricter formatting rules than the default go fmt
  • golangci-lint
    • Aggregates various preinstalled Go linters, runs them in parallel, and makes heavy use of the Go build cache
  • Staticcheck
    • Uses static analysis to find bugs and performance issues, offer simplifications, and enforce style rules

Suggested tools

  • just
    • Command runner to simplify use of the required tools
  • air
    • Watches source files and rebuilds/executes the project when sources change