Skip to content

docs: rewrite the README as a front page for people deciding to use it - #21

Closed
systemfsoftware-maker wants to merge 2 commits into
mainfrom
docs/readme-rewrite
Closed

systemfsoftware-maker wants to merge 2 commits into
mainfrom
docs/readme-rewrite

Conversation

@systemfsoftware-maker

Copy link
Copy Markdown
Contributor

Rewrites the README for a reader deciding whether to use the package: what it is, status, install route, the verdict, and reading a package's API.

  • Front-end detail moves unchanged to docs/front-ends.md (35 sentences, all from the old README apart from a two-line intro).
  • Development setup and provenance move to CONTRIBUTING.md.

Claims checked against the source

  • Public surface: Verdict.cell, Verdict.judge, ApiModel.serialise, FrontEnd.readPackage, analyse, isolatedEmitterLayer, compilerEmitterLayer, SurfaceRejected, RuleCorpusRejected are exported from packages/api-extractor/src/mod.ts and its namespaces.
  • Verdict document fields and finding fields match verdict.schema.ts and finding.schema.ts; the three Effect-channel examples (E_WIDENED major, E_WIDENED_IN_INPUT minor, E_TAG_REMOVED major) match corpus.v1.json.
  • NodeServices imported from @effect/platform-node as the package's own integration tests do.
  • bootstrap, test, lint, typecheck exist in the root package.json; the oracle version and commit match LICENSE.
  • Planned items match the plan's later PRs; none exists in the tree.
  • Install: this repository has no push-to-nix.systemfsoftware.com workflow on main and publishes no npm package (release.yml), so the README says that a consumer takes the flake and the tarballs through the producer route, and that Nix fetches what a producer has pushed and builds the rest.

No code changes.

The pitch, status and install route come first, then the verdict and reading a package. The front-end detail moves to docs/front-ends.md and the development setup and provenance to CONTRIBUTING.md. Each claim was checked against the source.
@systemfsoftware-bot

Copy link
Copy Markdown
Contributor

Closed: it adds back 34 .sfs-deps/ tarballs that #20 removed (packages come from nix.systemfsoftware.com), and the README was not written with the write-readme-md skill. Redone on a fresh branch from main.

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