chore(release): Flathub submission for the Linux Flatpak #229

New issue

Open

opened 2026-06-21 18:23:10 +00:00 by james · 0 comments

james commented

2026-06-21 18:23:10 +00:00

Owner

Context

#188 (PR #222) ships a Linux Flatpak attached to each Forgejo release. Users install with flatpak install carol-vX.Y.Z.flatpak — fine for self-hosters who know the project but a friction wall for anyone discovering Carol via Flathub search.

Flathub submission was explicitly out of scope on #188's first cut because it requires:

A real designer-produced icon set (the C-on-blue placeholder won't pass).
A sustained release cadence so Flathub's "recently updated" doesn't flag the app stale.
A complete metainfo.xml with screenshots, release notes, and content rating.

Once the placeholder icon is replaced (#227 — file alongside this one if not yet) and the release cadence settles, Flathub becomes worth pursuing.

Source

Follow-up flagged in #222.

Scope

Replace the placeholder icon with the real Carol mark (separate ticket — link / depends-on).
Polish flatpak/tech.wynning.carol.metainfo.xml:
- Add <screenshots> referencing publicly hosted screenshots of the Notes / Profile / Skills / Experience screens.
- Add <releases> populated from the same git-cliff output the API release uses.
- Add <content_rating> (OARS — likely "Mild" across the board since Carol holds personal data but not external content).
- Confirm the <categories> match what Flathub expects.
Submit the manifest to flathub/flathub following the documented submission process. The submission lives in a separate repo (flathub/tech.wynning.Carol); this ticket tracks Carol-side prep + the PR over there.
Document in apps/client/README.md the install command both for direct .flatpak download (current) and once accepted from Flathub (flatpak install flathub tech.wynning.Carol).

Acceptance criteria

Real icon set in place (depends on the icon-replacement ticket).
metainfo.xml carries screenshots, releases, content_rating, categories.
appstreamcli validate passes with no warnings (currently passes but minimally populated).
Flathub submission PR is open and tracked here.
Carol's release cadence has been ≥1 release per month for at least 3 months at the point of submission (Flathub's stale-app threshold).

Out of scope

Snap, AppImage, AUR — separate distribution channels.
macOS / Windows Tauri builds.
Multi-arch (ARM Linux) builds — separate when there's actual demand.

Composes with

#188 — Linux Flatpak.
The icon-replacement ticket (filed alongside this one).
ADR-0014 — release cadence.

Part of

#176

## Context [#188](https://forge.wynning.tech/james/carol/issues/188) (PR [#222](https://forge.wynning.tech/james/carol/pulls/222)) ships a Linux Flatpak attached to each Forgejo release. Users install with `flatpak install carol-vX.Y.Z.flatpak` — fine for self-hosters who know the project but a friction wall for anyone discovering Carol via Flathub search. Flathub submission was explicitly out of scope on #188's first cut because it requires: - A real designer-produced icon set (the C-on-blue placeholder won't pass). - A sustained release cadence so Flathub's "recently updated" doesn't flag the app stale. - A complete `metainfo.xml` with screenshots, release notes, and content rating. Once the placeholder icon is replaced ([#227](https://forge.wynning.tech/james/carol/issues/227) — file alongside this one if not yet) and the release cadence settles, Flathub becomes worth pursuing. ## Source Follow-up flagged in [#222](https://forge.wynning.tech/james/carol/pulls/222). ## Scope - Replace the placeholder icon with the real Carol mark (separate ticket — link / depends-on). - Polish `flatpak/tech.wynning.carol.metainfo.xml`: - Add `<screenshots>` referencing publicly hosted screenshots of the Notes / Profile / Skills / Experience screens. - Add `<releases>` populated from the same `git-cliff` output the API release uses. - Add `<content_rating>` (OARS — likely "Mild" across the board since Carol holds personal data but not external content). - Confirm the `<categories>` match what Flathub expects. - Submit the manifest to [`flathub/flathub`](https://github.com/flathub/flathub) following the documented submission process. The submission lives in a separate repo (`flathub/tech.wynning.Carol`); this ticket tracks Carol-side prep + the PR over there. - Document in `apps/client/README.md` the install command both for direct `.flatpak` download (current) and once accepted from Flathub (`flatpak install flathub tech.wynning.Carol`). ## Acceptance criteria - [ ] Real icon set in place (depends on the icon-replacement ticket). - [ ] `metainfo.xml` carries screenshots, releases, content_rating, categories. - [ ] `appstreamcli validate` passes with no warnings (currently passes but minimally populated). - [ ] Flathub submission PR is open and tracked here. - [ ] Carol's release cadence has been ≥1 release per month for at least 3 months at the point of submission (Flathub's stale-app threshold). ## Out of scope - Snap, AppImage, AUR — separate distribution channels. - macOS / Windows Tauri builds. - Multi-arch (ARM Linux) builds — separate when there's actual demand. ## Composes with - [#188](https://forge.wynning.tech/james/carol/issues/188) — Linux Flatpak. - The icon-replacement ticket (filed alongside this one). - [ADR-0014](docs/adr/0014-release-pipeline.md) — release cadence. ## Part of [#176](https://forge.wynning.tech/james/carol/issues/176)

james referenced this issue

2026-06-21 18:23:11 +00:00

chore(brand): real Carol icon mark across PWA, Tauri/Flatpak, and Android assets #230