docs: make the quick start clone a repository that exists - #86
Merged
Conversation
Every quick start in the tree opened with
git clone https://github.com/anthropic/EoS.git
That repository does not exist — `gh api repos/anthropic/EoS` returns 404. It
is step one of the documented onboarding path in seven files: GETTING_STARTED,
the host/stm32/rpi4/nrf52 quickstarts, the integration guide and the STM32
tutorial. Any external developer following the docs stopped there.
The §30 12-month framework lists "tested quick start" among the 0–3 month
Foundation deliverables. It was not tested, and could not have been.
Two further defects behind the URL, both of which only surface once the clone
succeeds:
- The docs then `cd EoS/eos/examples/blink-gpio`, but cloning eos.git creates
a directory called `eos` with `examples/` at its root. `EoS/eos/...` belongs
to a multi-repo workspace that the single clone command never produces. The
single-repo quick starts now use the path the clone actually creates. The
guides that genuinely describe the multi-repo workspace are left alone —
their paths are right, and what they are missing is a step that sets the
workspace up, which is a larger documentation question than this change.
- They pass -DCMAKE_TOOLCHAIN_FILE=toolchains/arm-none-eabi.cmake, which does
not exist. The ARM toolchain files are arm-cortex-m4.cmake,
arm-none-eabi-stm32f4.cmake and arm-none-eabi-r5.cmake. Pointed at
arm-cortex-m4.cmake, which is the one the CI job and the Cortex-M reference
class use.
Verified by running the host quick start verbatim against the published repo,
from an empty directory:
git clone https://github.com/embeddedos-org/eos.git
cd eos/examples/blink-gpio
cmake -B build -DEOS_PRODUCT=iot
cmake --build build
./build/blink-gpio
[blink] Starting LED blink on pin 13
[blink] LED ON
The example itself was always fine. Only the instructions were wrong.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This was referenced Sep 3, 2026
Kartikey1306
added a commit
to Kartikey1306/eos
that referenced
this pull request
Sep 4, 2026
The pin in the previous commit stops an eBoot or ebuild master that does not compile from turning every eos pull request red. It also stops that break being visible from here at all, which on its own is the worse half of the trade: the next upstream breakage would be silent instead of loud, and the pin would sit at a172a6d indefinitely because nothing would ever ask -- while quietly dropping the six eBoot commits that follow it. `.github/workflows/upstream-drift.yml` is the other half. It builds eBoot at master and compares both pins against their master, so an upstream break still surfaces, on a run that blocks no pull request and names the repository responsible. Design choices, each one avoiding a defect this repo has been filing against: Its own file, schedule + workflow_dispatch only. The first draft was a job inside eos-simulation.yml guarded by `if: github.event_name == 'schedule'`. That works, but the run showed it on the PR as a SKIPPED check -- and a required-check gate that treats any non-success as a failure, which is the design in embeddedos-org#121, would trip on exactly that. Moving it out removes the check from PR runs entirely rather than relying on every future gate to exempt it. Not `continue-on-error`. A job reporting success over a failure is the fail-open shape we keep finding in aggregating gates. This one may fail honestly precisely because it gates nothing. Failing is reserved for "upstream does not build". A pin merely behind a healthy master is a warning: actionable, not broken. The pins are read out of eos-simulation.yml, not copied. A second copy of a SHA is a second thing to forget. The read demands a 40-character hex value and fails closed if it cannot find one, so a renamed or reformatted key stops the job instead of silently letting it check a pin of "". The failure message is scoped to the build step's own outcome, so a checkout, apt or pin-read failure cannot report itself as evidence about eBoot's master. The summary says eBoot is built and ebuild is only compared, rather than implying both were checked. Verified by execution, not by reading: eBoot @ a172a6d (the pin) host build rc=0, 0 errors eBoot @ 22d8f8b (master) host build rc=2, "no member named 'reserved' in 'eos_image_header_t'" at eos_image.h:135 and :142 -- the same defect CI reports, so the pin is demonstrably the difference pin extraction, run against the real file and two mutations of it: real workflow -> both SHAs read correctly, and the eBoot one resolves to embeddedos-org#86's merge key renamed to EBOOT_SHA -> fails closed, rc=1 value unquoted and shortened -> fails closed, rc=1 drift logic, run against the real repositories: pin 6 behind healthy master -> "behind by 6" warning, no failure pin absent from master -> "not an ancestor" warning, exit 0 under set -e (the first draft printed "pinned pin not found on master commit(s)") pin equal to master -> no warning eos on this branch: cmake build rc=0, ctest 39/39, pytest 15/15 with the new workflow file present, test_crypto_ed25519_loworder registered and passing. When eBoot embeddedos-org#94 lands, bump EBOOT_COMMIT to that merge; this job is what will say whether it holds. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Every quick start in the tree opens with:
That repository does not exist.
gh api repos/anthropic/EoS→ 404.It is step one of the documented onboarding path in seven files:
GETTING_STARTED.md, the host/stm32/rpi4/nrf52 quickstarts, the integration guide, and the STM32 tutorial. Any external developer following the docs stopped there.§30's 12-month framework lists "tested quick start" among the 0–3 month Foundation deliverables. It was not tested, and could not have been.
Two further defects, only visible once the clone succeeds
The path doesn't exist either. The docs then
cd EoS/eos/examples/blink-gpio, but cloningeos.gitcreates a directory calledeoswithexamples/at its root.EoS/eos/...belongs to a multi-repo workspace the single clone command never produces.Fixed for the single-repo quick starts. Left alone for the guides that genuinely describe the multi-repo workspace — their paths are correct, and what they're missing is a step that sets the workspace up. That's a larger documentation question than this change, and I'd rather flag it than guess at it.
The toolchain file doesn't exist. They pass
-DCMAKE_TOOLCHAIN_FILE=toolchains/arm-none-eabi.cmake. The real ARM toolchain files arearm-cortex-m4.cmake,arm-none-eabi-stm32f4.cmakeandarm-none-eabi-r5.cmake. Pointed atarm-cortex-m4.cmake— the one the CI job and the Cortex-M reference class use.Verification
Ran the host quick start verbatim against the published repo, from an empty directory:
The example itself was always fine. Only the instructions were wrong.
Docs only — no source changes, so this is independent of #82 and can land on its own.
🤖 Generated with Claude Code