docs: rewrite the README against what the repo actually contains - #56
Merged
Conversation
The old README linked 17 paths that no longer exist, listed the licence three different ways, and described the AI extension at length after that extension had been deleted. - Licence is Apache 2.0, which is what LICENSE has always said. The badge claimed MIT and a second licence section claimed MIT plus a commercial source-available licence for extensions/ai, pointing at a LICENSE file that does not exist. - Dropped every AI extension reference. The directory is gone. - Extension table now lists all 22 that exist, with cron, dashboard, discovery, features and security added from their own READMEs. Queue, Search and orpc are marked in progress, as the old status section had it. - Fixed every documentation and example link against the tree. - Removed the duplicate licence section, the Links section that repeated the docs list, and the Why Forge section that restated Key Features. 557 lines to 258, with no information dropped that was still true.
Contributor
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
Conventional Commits ValidationPR Title: valid |
LICENSING.md documented a dual-licensing scheme that does not exist: MIT for core and a Commercial Source-Available Licence for extensions/ai. LICENSE is Apache 2.0, and extensions/ai was deleted. llm.txt repeated the same claim and advertised the extension in two other places; both are now corrected to Apache 2.0. CONTRIBUTING.md now exists. The README linked to it and had done for some time. It carries the workflow the README described, plus what each conventional-commit prefix does to the release, since that is the part a first contributor gets wrong. The roadmap is gone rather than redated. It listed v2.1 for Q1 2025, v2.2 for Q2 2025 and v3.0 for Q3 2025, all long past, and a roadmap nobody maintains is worse than none.
Contributor
Conventional Commits ValidationPR Title: valid |
Contributor
Conventional Commits ValidationPR Title: valid |
.gitignore line 121 is `**/*.md`, with an allowlist of exceptions under it. CONTRIBUTING.md was written in the previous commit and silently not staged, which left the README linking to a file the repo did not carry. Adding the exception rather than forcing the add, so the next person to write it does not hit the same silence.
Contributor
Conventional Commits ValidationPR Title: valid |
Contributor
Conventional Commits ValidationPR Title: valid |
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.
The README described a repository that no longer exists in several places. This rewrites it against what is actually in the tree.
Corrections, not just editing
The licence was stated three different ways, and the badge was wrong.
LICENSEis and has been Apache 2.0. The badge said MIT. A second licence section near the bottom said MIT for core plus a Commercial Source-Available Licence forextensions/ai, and pointed atextensions/ai/LICENSE, which does not exist. The file is now the single Apache 2.0 statement that matchesLICENSE.Every AI extension reference is gone.
extensions/ai/is not in the tree. The README carried a table row, a docs link, a full worked code example, a licensing section and a roadmap item for it.17 of the 24 relative links were dead, including all six core-concept doc links, all four getting-started links, and six of the nine example links. Every link in the rewrite resolves against the tree.
The extension table was both incomplete and self-contradictory. It listed 18 rows all marked shipped, while a separate status section further down said 17 total with Queue, Search and orpc in progress. Five extensions that exist (
cron,dashboard,discovery,features,security) were not listed at all. There is now one table of all 22, with descriptions for the new five taken from their own READMEs, and the three in-progress ones marked as the status section had them.Editing
Removed the duplicate licence section, the Links section that repeated the documentation list and the badges, and the Why Forge section that restated Key Features in different words. Dropped the emoji headings, the check-mark decorations, the title-case headings, the bold-header bullet lists, and the marketing register ("Enterprise-Grade", "breathtaking" adjacent). Examples now point at directories that exist, chosen from
examples/.557 lines to 258. No claim that was still true has been dropped.
Follow-up: the three loose ends are closed
LICENSING.mdis deleted. It documented MIT for core plus a Commercial Source-Available Licence forextensions/ai.LICENSEis Apache 2.0 andextensions/aino longer exists, so every claim in the file was wrong.llm.txtrepeated the same licence claim and named the extension in two other places; all three are corrected.CONTRIBUTING.mdnow exists. The README linked to it and always had. It carries the workflow the README described, plus what each conventional-commit prefix does to the release, since that is the part a first-time contributor gets wrong and the tooling acts on it silently.The roadmap is gone rather than redated. It promised v2.1 in Q1 2025, v2.2 in Q2 2025 and v3.0 in Q3 2025, all more than a year past. An unmaintained roadmap is worse than none.
One thing worth a look:
.gitignoreline 121Writing
CONTRIBUTING.mdsurfaced this. Line 121 is a blanket**/*.md, with an allowlist under it forREADME.md,docs/**, and some dashboard contract files. Any markdown file outside that allowlist is silently ignored, sogit addreports success and stages nothing. That is how the first commit here ended up with a README linking to aCONTRIBUTING.mdthe repo did not carry.This adds
!/CONTRIBUTING.mdto the allowlist rather than forcing the add. But the underlying rule will do the same thing to the nextCODE_OF_CONDUCT.md,SECURITY.md, or architecture note somebody writes, and none of those exist yet. Narrowing**/*.mdto the directories that actually accumulate scratch markdown would be a better fix than growing the allowlist one file at a time. Out of scope here.