uttrflow / uttrflow/uttrflow-swift

AGENTS.md still says the source repositories are private and Docs/releasing.md is the only release guide

Open Beginner friendly
#697 0 comments 0 reactions 0 assignees View on GitHub
area:docs documentation good first issue P2
Dominant language
Swift
Stars
4
Forks
17
Avg merge
3h 32m
Merged PRs (30d)
277

Description

The "Building and releasing" section of `AGENTS.md` still says the source repositories are private, that `Docs/releasing.md` is the only description of a release, and that `make publish` uses this Mac's `gh` login. This repository is public, and #471 changed `Docs/releasing.md` itself to say a release can also be cut by the tag workflow in `RELEASING.md`. `CLAUDE.md:1` sends every coding assistant to `AGENTS.md`, so this short version is what an assistant working in the repository takes as the release process.

## Where it is

`AGENTS.md:406`, under `## Building and releasing`:

> `Docs/releasing.md` is the only correct description. In short:

`AGENTS.md:413`:

> `make publish # to the public downloads repository, using this Mac's gh login`

`AGENTS.md:421-422`:

> Downloads go to the public **uttrflow/releases** repository. Source repositories stay
> private.

What the tree says instead:

- `Docs/releasing.md:3-4`: "A release can be cut by hand on a Mac, as this page describes, or by pushing a tag through the workflow documented in [`RELEASING.md`](../RELEASING.md)."
- `Docs/releasing.md:146-148`: "By hand, `Scripts/publish.sh` uses this Mac's `gh` login and the signing key in its keychain. In the workflow, the same script receives `RELEASES_TOKEN` and `SPARKLE_PRIVATE_KEY` from repository secrets."
- `.github/workflows/release.yml:238-240` sets `GH_TOKEN: ${{ secrets.RELEASES_TOKEN }}` and `SPARKLE_PRIVATE_KEY`, then runs `make publish`.
- `RELEASING.md:112-116` ("Releasing by hand") points back to `Docs/releasing.md` for the by-hand path only.
- `Docs/releasing.md:183-187` ("Where downloads live") no longer says the source repositories are private; #471 (for #470) removed that sentence, along with the build-server and secrets claims.

`AGENTS.md:425-428`, a few lines further down, already describes a run triggered by a pushed tag, so the section currently contradicts itself.

## What to change

Edit only `AGENTS.md`, lines 406-423:

1. Line 406: say that `Docs/releasing.md` covers a release by hand and `RELEASING.md` covers the tag workflow, the way `Docs/releasing.md:3-4` does.
2. Line 413: make the `make publish` comment true of both paths, for example "to the public downloads repository: this Mac's `gh` login by hand, `RELEASES_TOKEN` in the workflow".
3. Lines 421-422: delete "Source repositories stay private." Keep the rest of the paragraph. If you want a sentence in its place, take it from `Docs/releasing.md:183-187`: the releases repository holds disk images and `latest.json` and no source code.

Leave the versioning paragraph (`:416-419`) and the tag paragraph (`:425` on) alone; both match `RELEASING.md:18-20` and `release.yml`.

## How to check it

- `git grep -n "stay private\|only correct description" AGENTS.md` returns nothing.
- `make docs-audit` passes. It needs no build.

## Notes

Lines 9 and 320 of `AGENTS.md` also use the word "private", about the repository this one was created from. They are history, not a claim about this repository, and do not need changing.

New here? `CONTRIBUTING.md` has the setup, and everything above is the whole task — ask in a comment if any of it is unclear and you will get an answer.

Contributor guide

Open the contributing guide

Research direction

Edit only AGENTS.md:406-423, comparing its release instructions with Docs/releasing.md, RELEASING.md, and .github/workflows/release.yml. Run git grep for the two outdated phrases, then run make docs-audit; done means the manual and tag-workflow paths are accurately described without changing the versioning or tag paragraphs.

Written by the indexing model from the issue text.

Assessment

Tech stack
github-actions
Domain
documentation, release
Issue type
Documentation
Difficulty
1/5
Estimated time
Under an hour
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
94/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.