docs: document releases, publishing and updating feed apps

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)

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                                |

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: