Skip to content

docs: identity is edited in app/Identity.xcconfig, and SCOPE.md names a directory that exists - #288

Merged
prakashrj merged 1 commit into
mainfrom
docs/identity-lives-in-the-xcconfig
Sep 3, 2026
Merged

docs: identity is edited in app/Identity.xcconfig, and SCOPE.md names a directory that exists#288
prakashrj merged 1 commit into
mainfrom
docs/identity-lives-in-the-xcconfig

Conversation

@prakashrj

Copy link
Copy Markdown
Contributor

Three corrections to the two documents an agent reads before touching anything. Docs only; no behaviour changes.

1. AGENTS.md's identity invariant still pointed at .bootstrap.env

The critical-invariants row ended "afterward, the value is set in .bootstrap.env". bin/rename.sh has written app/Identity.xcconfig since identity became a slot, and the "Where your code goes" table seventeen lines below already calls that file "the one tracked identity file". An agent reading this file top-down gets two incompatible instruction sets out of one document, and the one it hits first is the wrong one.

The row now points at app/Identity.xcconfig and keeps the .bootstrap.env mention rather than deleting it, because deleting it would be its own kind of false: APP_NAME / BUNDLE_ID there really are read, by the Fastfile and by release.yml / canary-local-mode.yml. The row now says which of the two is which — the xcconfig is where the build gets its identity; the dotenv is a handle for fastlane and the release workflows.

2. SCOPE.md's one test named a directory that has never existed

Does this addition require modifying Swift source files in app/HelloApp/ to use it?

Measured rather than assumed, with git ls-tree -r --name-only <ref> -- app/ at five refs including the root commit f9cd5a8: zero entries under app/HelloApp/ at every one of them, and app/Shared/ present at every one. That sentence is the entire contribution rule, so a contributor who runs it literally has to guess which directory is meant — and the guess is the rule. It now names app/Shared/.

3. The template-owned row's issue pointer now says whose slug it is

| Do not edit files under bin/, ci/, .github/workflows/, Makefile | Template-owned | Override via env, or open an upstream issue at indiagrams/apple-shipkit |

Correct as it stands here. It stops being correct the moment somebody forks, because bin/rename.sh's Step D substitutes that slug wherever it appears. Measured on this tree: 15 tracked files once the script's own PATHSPEC_EXCLUSIONS are applied, AGENTS.md among them. So in a personalized fork the one line telling a reader where to send fixes upstream has been rewritten to point back at the fork itself, and no gate sees it happen — this was found downstream, in a fork whose copy of that row named the fork.

The cell now says outright that the slug names the TEMPLATE and not your own fork, and that a copy naming your fork means a sweep rewrote it. That makes the defect visible to whoever is reading the personalized copy.

Narrowing the sweep is behaviour and is not in this PR. It is in the parameterization change that follows.

Test plan

  • git ls-tree -r --name-only <ref> -- app/ at 212b489, c6c324f, d714006, 658bd32 and the root commit f9cd5a8: app/HelloApp/ = 0 entries at all five, app/Shared/ present at all five.
  • git grep -lw -F -e 'indiagrams/apple-shipkit' -- . <PATHSPEC_EXCLUSIONS> = 15 files, AGENTS.md among them.
  • Markdown only. No script, workflow, manifest or test is touched; git diff --stat is AGENTS.md | 4 ++--, CHANGELOG.md | 10 ++++++++++, SCOPE.md | 2 +-.
  • CHANGELOG entry included, per CONTRIBUTING.md.

… a directory that exists

Three corrections to the two documents an agent reads before touching
anything, all measured against this tree rather than recalled.

AGENTS.md's critical-invariants row on identity still ended "afterward,
the value is set in .bootstrap.env". bin/rename.sh has written
app/Identity.xcconfig since identity became a slot, and the "Where your
code goes" table seventeen lines below already called that file "the one
tracked identity file". An agent reading top-down got two incompatible
instruction sets out of one document. The row now points at
app/Identity.xcconfig and states what the .bootstrap.env handle is still
for -- APP_NAME / BUNDLE_ID there are read by the Fastfile and by
release.yml / canary-local-mode.yml -- rather than dropping the mention
and leaving a reader to wonder whether those keys still matter.

SCOPE.md's one test named app/HelloApp/. Measured with
`git ls-tree -r --name-only <ref> -- app/` at five refs, including the
root commit f9cd5a8: zero entries under app/HelloApp/ at every one, and
app/Shared/ present at every one. The test is the whole contribution
rule, so a reader who runs it literally has to guess which directory is
meant. It now names app/Shared/.

The template-owned row's "open an upstream issue at
indiagrams/apple-shipkit" now says outright that the slug names the
TEMPLATE, not the reader's own fork. bin/rename.sh's Step D substitutes
that slug wherever it appears: measured at 15 tracked files once the
script's own PATHSPEC_EXCLUSIONS are applied, AGENTS.md among them. So
in a personalized fork the one line telling a reader where to send fixes
upstream has been rewritten to point back at the fork. This change makes
that visible in prose; narrowing the sweep is behaviour and is not in a
docs-only change.

Co-Authored-By: Claude <noreply@anthropic.com>
@prakashrj
prakashrj merged commit d74d89d into main Sep 3, 2026
11 checks passed
@prakashrj
prakashrj deleted the docs/identity-lives-in-the-xcconfig branch September 3, 2026 21:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant