#39 · stacks/uplink

Part of #6.

These are the files a contributor and a curious user read before they read any code, and they lead somewhere else. Three of the links are dead or point at another repository, the document that explains CI describes a pipeline this repository does not run, and the bug template asks a menubar app user for a minimal reproduction. The cost is not that the files are stale, it is that someone follows them: forks the wrong repository, trusts a CI description CI contradicts, or gives up on an issue form that has no field for the thing they actually know.

What is there today

.github/EXPLANATIONS.md#L9 says CI auto fixes and applies code style updates through a pull request, .github/EXPLANATIONS.md#L10 says it runs unit and end to end tests, and .github/EXPLANATIONS.md#L11 says it runs with node-versions set to [18x]. CI has three jobs and they run lint (.github/workflows/ci.yml#L51), typecheck (.github/workflows/ci.yml#L87) and bun run test (.github/workflows/ci.yml#L130). There is no auto fix job, no end to end suite, and no node setup at all: the runtime comes from Pantry (.github/workflows/ci.yml#L33).
.github/EXPLANATIONS.md#L14 advertises Renovate as the dependency bot. AGENTS.md forbids it, and .github/workflows/buddy-bot.yml#L4 quotes that same rule as the reason the hand written workflow exists. .github/EXPLANATIONS.md#L27 sends readers to the discussions of stacksjs/stacks.
.github/workflows/README.md lists three workflows: CI at .github/workflows/README.md#L5, Release at .github/workflows/README.md#L10, Labeler at .github/workflows/README.md#L11. Five are present. Deploy runs on every CI completion on main (.github/workflows/deploy.yml#L12) and Buddy Bot runs on three schedules (.github/workflows/buddy-bot.yml#L18). Those three entries also use em dashes, which AGENTS.md rules out.
.github/CONTRIBUTING.md#L28 tells a contributor to fork the framework repository, .github/CONTRIBUTING.md#L32 clones {github-username}/stacks, and .github/CONTRIBUTING.md#L45 adds git@github.com:stacksjs/stacks.git as upstream. Nothing in the file names this repository, says it is macOS only, or mentions that the watcher reads nothing until Full Disk Access is granted.
The testing section says to run buddy test (.github/CONTRIBUTING.md#L150) and describes that as unit and e2e (.github/CONTRIBUTING.md#L141), and its second sentence stops mid word at .github/CONTRIBUTING.md#L152. The command that actually exercises this app is in the README: ./pantry/.bin/bun test tests/unit/uplink (README.md#L121).
.github/ISSUE_TEMPLATE/config.yml#L3 links github.com/stacksjs/contribute, which returns 404. .github/ISSUE_TEMPLATE/bug_report.yml#L42 and .github/ISSUE_TEMPLATE/feature_request.yml#L41 link stacksjs/contributing, which exists but is not this repository, and .github/ISSUE_TEMPLATE/bug_report.yml#L40 links a code of conduct in another repository while .github/CODE_OF_CONDUCT.md sits here.
.github/ISSUE_TEMPLATE/bug_report.yml#L21 makes a minimal reproduction required and .github/ISSUE_TEMPLATE/bug_report.yml#L29 makes bunx envinfo --system --binaries --browsers required. Neither suits an app whose failure mode is a text that went unanswered on one Mac. .github/ISSUE_TEMPLATE/bug_report.yml#L46 sends questions to GitHub Discussions, which is disabled on this repository.
.github/ISSUE_TEMPLATE/feature_request.yml#L13 prompts the reporter to write as a developer using Stacks.
.github/stale.yml#L1 is Probot Stale configuration. The GitHub app it was written for is retired and no workflow in .github/workflows reads the file.
There is no pull request template and no CODEOWNERS in .github/.
package.json#L6 sets the description to the single word Uplink, and the manifest declares no repository, homepage or bugs field, so nothing links back out of it. The GitHub repository itself does have a description and a homepage, so the gap is only in the manifest. The repository has no topics.
LICENSE.md#L3 reads Copyright (c) 2023 Open Web Foundation, which matches neither the current year nor the names in .github/FUNDING.yml#L1.
.github/workflows/deploy.yml#L198 says the verification step checks "the CSRF cookie the city form needs, and the tour data". What the step asserts is a changed build id (.github/workflows/deploy.yml#L206), that /dashboard returns 404 (.github/workflows/deploy.yml#L219), and that the hero image is served (.github/workflows/deploy.yml#L225).
config/buddy-bot.ts#L29 enables workflow generation, config/buddy-bot.ts#L30 points it at .github/workflows, and config/buddy-bot.ts#L31 through config/buddy-bot.ts#L35 turn on the daily, weekly and monthly templates. The hand written .github/workflows/buddy-bot.yml already carries all three schedules (.github/workflows/buddy-bot.yml#L18, .github/workflows/buddy-bot.yml#L19, .github/workflows/buddy-bot.yml#L22) and already reads BUDDY_BOT_TOKEN (.github/workflows/buddy-bot.yml#L57), so configuring that token is enough for buddy-bot to write three more workflow files and open every update twice.

Proposal

Delete .github/EXPLANATIONS.md. The only part of it that is true is a list of workflows, and .github/workflows/README.md owns that list.
Rewrite .github/workflows/README.md around the five workflows present (CI, Release, Deploy, Buddy Bot, Labeler), one line each naming what triggers it and what it does, with hyphens in place of the em dashes.
Rewrite .github/CONTRIBUTING.md for this repository: clone stacksjs/uplink, macOS 13 or later, ./buddy uplink:install then ./buddy uplink:doctor, that Full Disk Access has to be granted before the watcher sees anything, ./pantry/.bin/bun test tests/unit/uplink for the tests, ./buddy lint and ./buddy typecheck before a pull request, and conventional commits. Drop the framework tour of make:* and dev:*, and finish the sentence that breaks off at .github/CONTRIBUTING.md#L152.
Rewrite .github/ISSUE_TEMPLATE/bug_report.yml around what a user of this app can actually produce: macOS version, Uplink version, whether it is the downloaded app or the from source service, which check in ./buddy uplink:doctor fails (the check names are in app/Uplink/doctor.ts#L91 through app/Uplink/doctor.ts#L136), and the tail of ~/Library/Logs/Uplink.log (app/Uplink/settings.ts#L19). Remove the reproduction field, the envinfo field and the Discussions pointer.
Rewrite .github/ISSUE_TEMPLATE/feature_request.yml to talk about Uplink rather than a developer using Stacks, and point .github/ISSUE_TEMPLATE/config.yml at this repository's contributing guide instead of github.com/stacksjs/contribute. Link the local .github/CODE_OF_CONDUCT.md from both templates.
Delete .github/stale.yml.
Add .github/PULL_REQUEST_TEMPLATE.md (what changed, how it was checked on a Mac, which doctor checks still pass) and .github/CODEOWNERS.
Fill in package.json: a real description, repository, homepage and bugs. Set repository topics on GitHub as part of the same change.
Fix LICENSE.md#L3 to the current year and the holder named in .github/FUNDING.yml#L1.
Replace the comment at .github/workflows/deploy.yml#L194 through .github/workflows/deploy.yml#L199 with what the step checks now: a changed build id, /dashboard and the framework default views returning 404, and the hero image being served.
Set workflows.enabled to false in config/buddy-bot.ts#L29, leaving the hand written workflow as the single owner of the schedules.

Requirements

Every link resolves, and resolves here. After the rewrite, no community health file may link stacksjs/stacks, stacksjs/contribute or stacksjs/contributing. Where a contributing guide, code of conduct or security policy is referenced, it is the copy in this repository.
The bug template asks only for what the reporter has. A user who downloaded the DMG has a macOS version, a version string in the popover, a doctor output and a log file. They do not have a reproduction repository, and bunx envinfo is not installed on their machine. Make no field required that such a user cannot fill.
One owner for the buddy-bot schedules. Flipping workflows.enabled to false is the decision, not just a default. Say so in the config comment so the next reader does not turn it back on and get duplicate update runs.
Delete rather than correct where the file has no job. .github/EXPLANATIONS.md duplicates .github/workflows/README.md, and nothing reads .github/stale.yml. Rewriting either one leaves two places to keep in step.
Hyphens, not em dashes. AGENTS.md forbids em dashes and separator en dashes in anything a person reads, and .github/workflows/README.md currently breaks that rule in three places.
Leave .github/SECURITY.md and .github/CODE_OF_CONDUCT.md in place. Both are usable as they stand. This issue is not a rewrite of the whole directory.

Acceptance

grep -rn "stacksjs/stacks\|stacksjs/contribute\|stacksjs/contributing" .github/ matches only the issue reference inside the buddy-bot workflow header comment.
Every statement in .github/workflows/README.md about CI is true of .github/workflows/ci.yml, and all five workflows in .github/workflows are listed.
.github/EXPLANATIONS.md and .github/stale.yml no longer exist.
.github/CONTRIBUTING.md gets a contributor from a fresh clone of this repository to a running watcher and a passing test run, on a Mac, without opening another repository.
A filled in bug report tells a maintainer the macOS version, the Uplink version, which doctor check failed and the last lines of the log, and demands no reproduction.
package.json carries a description, repository, homepage and bugs; LICENSE.md#L3 carries the current year and the right holder; the repository has topics.
config/buddy-bot.ts has workflows.enabled: false, so a configured BUDDY_BOT_TOKEN cannot add a second set of workflow files.
No file touched by the change contains an em dash or a separator en dash.