From 8622fd3d69f220c121b45be7ddee299ae9c58964 Mon Sep 17 00:00:00 2001 From: Salman Faris Date: Wed, 4 Nov 2026 12:25:18 +0530 Subject: [PATCH] docs: document releases, publishing and updating feed apps in the README - Releasing explains that one vYY.M.PATCH tag on main releases the main app and every feed app with a production id, and uses the same version format as the other Edge App repos. - New sections cover publishing a new feed app (icon, deployed-apps.yml entry, initialize on stage then production, record the ids) and updating one (deployed-apps.yml, code or screenly.yml, one-off runs, removing an app from deploys). - DEPLOYMENT.md keeps how the feed-app workflows work and the field reference, and links to the README for the steps. --- DEPLOYMENT.md | 27 ++++------------------ README.md | 59 ++++++++++++++++++++++++++++++++++++++--------- deployed-apps.yml | 4 ++-- 3 files changed, 55 insertions(+), 35 deletions(-) diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md index 07541fd..be1aaa5 100644 --- a/DEPLOYMENT.md +++ b/DEPLOYMENT.md @@ -26,27 +26,10 @@ apps: An app with no id for an environment is skipped there, not deployed with an empty id. -## Releasing +## Releasing, adding and updating feed apps -Feed apps release together with the main app: +The steps are in the README: -- A push to `main` deploys every feed app with a stage id to **stage**. -- A `vYY.MM.N` tag on `main` deploys every feed app with a production id to **production**. - -Each deploy waits for approval in its environment. See the README's release section for tagging. - -## Adding a feed app - -1. Add an entry to `deployed-apps.yml` with empty ids, and merge it to `main`. -2. Run **Actions → Initialize Custom RSS Reader App** from `main` with the app key and `stage`. It refuses to run if the app already has a stage id, or if an Edge App with that name already exists. -3. Copy the id from the run's summary into `ids.stage` and merge. The next stage deploy includes the app. -4. When it's ready for production, repeat steps 2 and 3 with `production`. - -The shared action's summary also says to set a repo variable. Ignore that for feed apps; their ids live only in `deployed-apps.yml`. - -## Updating feed apps by hand - -Run **Actions → Update RSS Reader Apps** from `main` (stage) or from a release tag (production): - -- **App key:** empty for every app, or one key such as `bbc-news`. -- **Overrides (optional):** description, RSS title, icon URL or RSS URL, used instead of `deployed-apps.yml` for this run only. To change one permanently, edit `deployed-apps.yml`. +- [Releasing](README.md#releasing): one tag releases the main app and every feed app. +- [Publishing a new feed app](README.md#publishing-a-new-feed-app) +- [Updating a feed app](README.md#updating-a-feed-app) diff --git a/README.md b/README.md index 39779bd..b514b7f 100644 --- a/README.md +++ b/README.md @@ -40,30 +40,67 @@ bun run build ## Deployment -```bash -screenly edge-app create --name rss-reader --in-place -bun run deploy -screenly edge-app instance create -``` +This code runs several Edge Apps: -This code also runs the feed apps (BBC News, Fox News, ...), each its own Edge App with its own feed. They are listed in `deployed-apps.yml` and deploy alongside the main app; see [DEPLOYMENT.md](DEPLOYMENT.md), including how to add one. +- **The main RSS Reader app**, which deploys through `update-edge-app.yml` like every other Edge App, using the repo variables `STAGE_EDGE_APP_ID` and `PRODUCTION_EDGE_APP_ID`. +- **Feed apps** (BBC News, Fox News, ...): each is its own Edge App with its own name, icon and default feed, listed in [`deployed-apps.yml`](deployed-apps.yml) and deployed by `update-rss-reader-apps.yml`. All other settings come from `screenly.yml`, so a code or setting change reaches every feed app on the next release. + +All of them release together, through the shared [edge-apps-actions](https://github.com/Screenly/edge-apps-actions). [DEPLOYMENT.md](DEPLOYMENT.md) covers how the feed-app workflows work. ### Releasing -Pushes to `main` start a stage deploy, which waits for approval. To release to production, tag a commit on `main` with the next CalVer version (`vYY.MM.N`, e.g. `v26.11.0`; check `git tag --sort=-v:refname | head -1` for the latest) and push the tag. The workflows refuse tags not on `main` and only treat numeric `v[0-9]*` tags as releases; the production deploy also waits for approval. Replace `vYY.MM.N` below with the new version: +Every deploy waits for approval in its GitHub environment. + +1. **Stage:** merge to `main`. The push deploys the main app and every feed app with a stage id to stage. +2. **Production:** after checking stage, tag that commit on `main` with the next CalVer version, `vYY.M.PATCH` (for example `v26.11.0`, then `v26.11.1`; check `git tag --sort=-v:refname | head -1` for the latest), and push the tag. This deploys the main app and every feed app with a production id to production. Tags not on `main` are refused, and tags that aren't `v` followed by a digit (such as `vrc1`) are ignored. ```bash git checkout main && git pull -git tag vYY.MM.N -git push origin vYY.MM.N +git tag vYY.M.PATCH +git push origin vYY.M.PATCH ``` -Then publish a GitHub Release whose notes list the pull requests merged since the previous release. Add `--draft` to review the notes before publishing: +3. **Release notes:** publish a GitHub Release listing the pull requests merged since the previous release. Add `--draft` to review the notes before publishing: ```bash -gh release create vYY.MM.N --verify-tag --generate-notes --title vYY.MM.N +gh release create vYY.M.PATCH --verify-tag --generate-notes --title vYY.M.PATCH ``` +### Publishing a new feed app + +A feed app needs no code: it is an entry in `deployed-apps.yml`. + +1. **Host an icon** at a public URL. The existing icons are under `https://playground.srly.io/edge-apps/helpers/rss-reader/app-icons/`. +2. **Add an entry** to `deployed-apps.yml` with empty ids, and merge it to `main`: + + ```yaml + apps: + example-news: # app key: lowercase, used to pick the app in the workflows + app_name: 'Example News' # Edge App name and instance title; must be unique + description: 'Latest news from Example News' + rss_title: 'Example News' # shown in the header + icon_url: 'https://.../example-news.svg' + rss_url: 'https://example.com/feed.xml' # check it loads first + ids: + stage: '' + production: '' + ``` + + Apps without an id are skipped by deploys, so merging this changes nothing yet. + +3. **Create it on stage:** run **Actions → Initialize Custom RSS Reader App** from `main`, with environment `stage` and the app key. It refuses to run if the app already has a stage id or an Edge App with that name exists. +4. **Record the id:** copy the id from the run's summary into `ids.stage` and merge. From now on every stage deploy includes the app. +5. **Check it on stage**, then repeat steps 3 and 4 with `production` to create it there and fill in `ids.production`. The next release tag deploys it with everything else. + +The initialize summary also says to set a repo variable. Ignore that for feed apps; their ids live only in `deployed-apps.yml`. + +### Updating a feed app + +- **Its name, description, icon, header title or feed URL:** edit its entry in `deployed-apps.yml` and release as usual. Merging deploys the change to stage, and the next tag deploys it to production. (Changing `app_name` after the app exists doesn't rename it in Screenly; it is only used when the app is created.) +- **Code or other settings:** change the code or `screenly.yml`. Every feed app picks it up on the next release, with no change to `deployed-apps.yml`. +- **A one-off redeploy or test:** run **Actions → Update RSS Reader Apps**, from `main` for stage or from a release tag for production. Leave the app key empty for every app, or enter one such as `bbc-news`. The optional overrides (description, header title, icon URL, feed URL) apply to that run only; to keep a change, put it in `deployed-apps.yml`. +- **Removing an app from deploys:** clear its id for that environment in `deployed-apps.yml`. This stops deploying to it but doesn't delete the app in Screenly. + ## Configuration | Setting | Description | Type | Default | diff --git a/deployed-apps.yml b/deployed-apps.yml index 4d1e131..cea61e5 100644 --- a/deployed-apps.yml +++ b/deployed-apps.yml @@ -1,6 +1,6 @@ # Feed apps: Edge Apps that all run this repo's code, each with its own -# settings and ids. update-rss-reader-apps.yml deploys them; see DEPLOYMENT.md -# for adding one. +# settings and ids. update-rss-reader-apps.yml deploys them; see the README +# ("Publishing a new feed app") for adding one. # # Format: # apps: