docs: re-link orphaned docs and slim engineering.md#313
Merged
Conversation
After #311 realigned the docs, index.md again omitted four files that exist under docs/: everos-demo, use-cases, migration-to-1.0.0, and release-notes-1.1.0. Restore them so every docs/*.md is reachable from the index, and rewrite engineering.md for an external audience. index.md: - Re-add a Tutorials section: everos-demo, use-cases - See also: + release-notes-1.1.0, + migration-to-1.0.0 - Reframe the Engineering section as contributor-facing (not "internal") engineering.md (575 -> 113 lines): - Drop internal-only material: the self-justifying scope rationale, the Claude Code loading internals, the infra failure-impact table, the roadmap, and the "investing in infrastructure" essay - Fix claims that were false for this GitHub repo: GitLab-primary CI, the dev/master branch model, and the Gitmoji commit convention - Keep what helps a contributor: toolchain, local make targets, the CI gates, and the main-branch + Conventional Commits workflow Conventions now match the repo's own .gitlint and GitHub Actions. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Update the inbound descriptions of engineering.md now that it is a contributor reference rather than an "infrastructure overview", and repoint the one reference that named content the trim removed. - CLAUDE.md, README, README.zh-CN, architecture.md: reword the link text to "contributor engineering reference: build, test, CI, conventions" - CLAUDE.md: the GitFlow Lite rationale pointer now targets .claude/skills/new-branch/SKILL.md (engineering.md no longer carries it) Co-Authored-By: Claude Opus 4.8 (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
2 participants
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.
What
Two related docs fixes:
index.mdwas missing four docs again. After docs: align docs with v1.1 and trim README #311 realigned the docs, the index stopped linking four files that still exist underdocs/:everos-demo.md,use-cases.md,migration-to-1.0.0.md,release-notes-1.1.0.md. Anyone navigating from the index silently missed them.engineering.mdwas an internal doc, partly false on GitHub. It described the internal GitLab setup (GitLab-primary CI,dev/masterbranches, Gitmoji commits) — none of which match this public repo, where CI is GitHub Actions, the branch ismain, and commits are enforced as Conventional Commits by the repo's own.gitlint.index.md
everos-demo,use-casesrelease-notes-1.1.0, +migration-to-1.0.0After this, every
docs/*.md(excluding the generatedopenapi.json) is linked from the index.engineering.md (575 → 113 lines)
Dropped (internal-only / not useful to external contributors):
Corrected (was factually wrong for this repo):
.gitlab-*files don't exist here)dev/masterGitFlow →main.gitlint+ thecommits.ymlCI gate)Kept (genuinely useful to a contributor): toolchain, local
maketargets, the CI gate table, and the branch + commit workflow.Verification
make docs-checkpasses (Markdown + internal links).docs/*.mdis now reachable fromindex.md.check_commit_messages.py/check_pr_title.py.Scope
Docs only. No code, API, or test changes. The five inbound references to
engineering.md(CLAUDE.md, README, README.zh-CN, index.md, architecture.md) still resolve — the filename is unchanged.🤖 Generated with Claude Code