Skip to content

[README] Guide a fresh clone through its first build - #745

Merged
hannesa2 merged 1 commit into
masterfrom
readme-fresh-clone-setup
Oct 3, 2026
Merged

hannesa2 merged 1 commit into
masterfrom
readme-fresh-clone-setup

Conversation

@goneng

@goneng goneng commented Oct 2, 2026 •

Copy link
Copy Markdown
Collaborator

Get a new contributor from clone to running app without guesswork. A fresh clone needs a one-time setup step (make bootstrap) that was not documented anywhere, and skipping it, or having it cut off, failed with errors that pointed elsewhere, such as a missing script, rather than at the step that was missed.

Changes

  • Document the setup step: the README says to run it before the first build, in Xcode or on the command line, and gives the shortest path from a fresh clone to a running app. This replaces the 2023 build script from discussion I can't get the built app to run: GitX quit unexpectedly. #366 the README linked to, which the Makefile now covers.
  • Make clear that signing is optional: Debug builds, from Xcode or make run, sign ad-hoc and need no setup, while the README read as if every build needed a Dev.xcconfig. make Dev.xcconfig is now the one way to set it up, since it reads everything off the certificate and says what is missing; writing the file by hand and digging the team ID out of Keychain Access are gone.
  • Name the setup step when it was skipped: make deps and the warning before each build now say to run make bootstrap, instead of failing on a missing file or suggesting a target that leaves the dependencies unbuilt.
  • Let make bootstrap finish a run that was cut off: an interrupted submodule update leaves a clone without its first commit, which every later update fails on, and clones that were never checked out, which every later update skips. scripts/repair-submodules.sh removes the first for the update to clone again and checks out the second; neither holds anything to lose, and a submodule in any other state is left alone. The check before each build reports both.

Test plan

  • In a test clone, recreated both states as an interrupted run leaves them (a cut-off openssl under objective-git, and git-diff-image and screenShotScript never checked out): the old update failed with "Unable to find current revision" and the old check was silent; the new check lists all three (and fails on CI), and one make git-submodule-sync repairs them, leaving a clean tree.
  • The script leaves alone a local edit, an unborn HEAD that still has refs, an emptied index beside an untracked file, and deleted files with the index intact; its check is silent on healthy checkouts.
  • In a fresh worktree with no submodules checked out, make deps stops and suggests make bootstrap. CI's own make deps steps still pass, on a checkout that has its submodules.

@goneng
goneng force-pushed the readme-fresh-clone-setup branch 2 times, most recently from 9a4a476 to a581440 Compare October 2, 2026 20:45
@goneng goneng changed the title Point a fresh clone at make bootstrap before its first build Guide a fresh clone through its first build Oct 2, 2026
@goneng
goneng force-pushed the readme-fresh-clone-setup branch 3 times, most recently from e1c3ae4 to ce8d1ac Compare October 2, 2026 21:41
@goneng
goneng marked this pull request as ready for review October 2, 2026 21:55
@goneng
goneng requested a review from hannesa2 October 2, 2026 23:09
Get a new contributor from clone to running app without guesswork:
The one-time setup a fresh clone needs was undocumented, and 
skipping it failed with errors that pointed elsewhere.

- Document the setup step in the README, and the shortest path from a
  fresh clone to a running app, in place of the outdated build script
  it linked to
- Make clear that signing with your own certificate is optional, and
  leave `make Dev.xcconfig` as the one way to set it up
- Have the build name the setup step when it was skipped, instead of
  failing on a missing file
- Let `make bootstrap` finish a run that was cut off, by a dropped
  connection for instance, which running it again could not do before
@goneng
goneng force-pushed the readme-fresh-clone-setup branch from ce8d1ac to d618058 Compare October 2, 2026 23:13
@goneng goneng changed the title Guide a fresh clone through its first build [README] Guide a fresh clone through its first build Oct 2, 2026
@hannesa2
hannesa2 merged commit 4b772f9 into master Oct 3, 2026
3 checks passed
@hannesa2
hannesa2 deleted the readme-fresh-clone-setup branch October 3, 2026 06:20
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.

2 participants