Repository navigation
docs: make the quick start clone a repository that exists - #86
Merged
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>
srpatcha
pushed a commit
that referenced
this pull request
Sep 8, 2026
…135) * fix(build): restore the low-order Ed25519 suite that #93 removed `CI — eos` and `Python Unit Tests` are red on master (769191a), and both fail for one reason: these suites exist in tests/ but no add_executable() in tests/CMakeLists.txt builds them, so they never run: ['test_crypto_ed25519_loworder.c'] 3aa8644 (#93, "remove duplicate test targets from tests/CMakeLists.txt") removed all four lines that build and register test_crypto_ed25519_loworder. It was not a duplicate — there was exactly one registration before that commit, and it took it. What stopped running is the suite that guards #101: Ed25519 rejecting low-order public keys. A low-order key makes every term of the verification equation collapse to the identity regardless of the message, so a signature of all zeros verifies against any content at all. The fix is still in services/crypto/src/ed25519_verify.c and still correct; nothing has been checking it since #93 merged, and nothing would have noticed if a later change had removed it too. Restored verbatim from 3aa8644^, in its original position before test_crypto_sha512. No other file changes. The guard that caught this is test_cmake_test_registration.py, added recently. It did exactly its job — this is the first thing it found. Verified: test_cmake_test_registration.py -> 5 passed (1 failed on master) pytest tests/ -> 15 passed (14 passed 1 failed on master) test_crypto_ed25519_loworder -> 5/5 tests passed ctest -> 39/39 passed (master builds 38) * ci: pin the eBoot and ebuild checkouts instead of floating on master Every open eos pull request is currently red on `EoS Full-Stack Simulation`, and none of them caused it. The kernel job checks out embeddedos-org/eBoot at `ref: master`, and eBoot master does not compile: include/eos_image.h:135 and :142 static-assert offsetof(eos_image_header_t, reserved) for a member that became tlv_len + tlv_hash, and core/ed25519_verify.c redefines point_is_identity -- two pairs of PRs that each merged clean and broke the build together. eBoot #94 repairs it and waits on review; until it lands, no change to any eos PR can make this job pass, and after it lands the next broken eBoot master does the same thing again. A floating `ref: master` makes every eos PR's CI depend on the moment-to- moment state of another repository's default branch. Pinning the two compiled-against checkouts makes the job a function of this repository plus two recorded SHAs -- red means the PR broke something, green means it did not, and a cross-repo bump is a reviewable one-line diff with CI on it. EBOOT_COMMIT a172a6d6e1e6 the newest eBoot master ancestor that compiles; found by walking master back and building each candidate. Its child 8a015b2 already carries the ed25519 redefinition. EBUILD_COMMIT e5d8052f3e2c ebuild's current master, frozen as-is. Both of its checkouts feed steps that are commented out (eFab does not exist), so this pin only removes the float. The middleware matrix (10 repos) still floats; it runs those repos' own tests rather than compiling eos against them, and 10 more pins deserve their own decision. When eBoot #94 merges, bump EBOOT_COMMIT to the merge SHA. Verified before pushing, master vs pin under the job's own configuration (-DEBLDR_BOARD=qemu_arm64 -DEBLDR_VERIFY_STAGE1=OFF -DCMAKE_BUILD_TYPE=Release, cross-compile mode): eBoot@master fails at the eos_image.h asserts, the exact error in the job log; eBoot@a172a6d builds every target, rc=0. Both pinned SHAs verified reachable from their repos' master. Workflow parses; the three `ref:` edits and the env block are the whole diff. This PR's own simulation run is the live test: it uses this branch's workflow and should go green while every master-based PR stays red. * ci: make the pin visible when it goes stale, not silently permanent 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 #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 #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 #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> --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Kartikey1306
added a commit
to Kartikey1306/eos
that referenced
this pull request
Sep 14, 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.
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
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