Rewrite the README for people who are not developers - #3
Conversation
…lease workflow rehearsable The README opened with a paragraph about .NET and Avalonia and buried the download link under a table of runtime identifiers. Someone who just wants their wallpaper to stop showing a beach at midnight had to read past the build system to find out whether the app does what they want. It now leads with a banner, a download link and a screenshot, says what the app is for in two sentences, and explains why it exists at all before it explains how it is built. The feature list is a table of plain-language capabilities rather than implementation notes, the code-signing warning is written as reassurance instead of an apology, and there is an FAQ covering the questions a non-developer actually asks: does it upload my photos, does it need to be running, what formats work, where are my settings. The build instructions are still there, moved below the fold where they belong. Both screenshots are in, Windows and macOS. docs/banner.png is generated rather than hand-drawn, by scripts/render-readme- banner.ps1, so it can be re-rendered when the wording or the size changes: a day-to-night sky with the sun, moon and hills from the application icon. Release workflow: - A manual run is now a rehearsal. It builds and checks all six artifacts and publishes nothing, so the packaging path can be exercised without burning a tag; "publish" drafts the release from a manual run when that is what you want. - The release is tagged explicitly with the version. softprops/action-gh-release defaults tag_name to github.ref, so a manual run would have created a release tagged with the branch name it ran from. - Artifacts are checked by name rather than counted, so a rename or a platform that published the wrong runtime fails in CI instead of in someone's download. - The run summary lists every artifact with its size and the SHA-256 sums, which is what makes a rehearsal worth reading. - Collecting artifacts moved out of the publishing job, so the checks run whether or not anything is going to be published. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: c39b7c249b
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| with: | ||
| # Explicit, because the default is github.ref: on a manual run that | ||
| # would be a branch name, and the release would be tagged with it. | ||
| tag_name: v${{ needs.version.outputs.version }} |
There was a problem hiding this comment.
When workflow_dispatch runs with publish enabled from a non-default branch and v<version> does not already exist, softprops/action-gh-release creates the tag through GitHub's release API; without target_commitish, that API targets the repository's default branch. The artifacts are built from the selected dispatch ref, so the resulting tag can point at different source code than the published binaries, breaking the release's provenance. Pass the dispatched SHA as target_commitish (and avoid replacing artifacts for an unrelated existing tag).
Useful? React with 👍 / 👎.
1 participant
It now leads with a banner, a download link and a screenshot, says what the app is for in two sentences, and explains why it exists at all before it explains how it is built. The feature list is a table of plain-language capabilities rather than implementation notes, the code-signing warning is written as reassurance instead of an apology, and there is an FAQ covering the questions a non-developer actually asks: does it upload my photos, does it need to be running, what formats work, where are my settings. The build instructions are still there, moved below the fold where they belong. Both screenshots are in, Windows and macOS.
Release workflow: