Skip to content

Restructure the README - #46

Merged
avgvi merged 1 commit into
mainfrom
readme-update
Oct 11, 2026
Merged

avgvi merged 1 commit into
mainfrom
readme-update

Conversation

@avgvi

@avgvi avgvi commented Oct 11, 2026

Copy link
Copy Markdown
Member

The README opened with a long paragraph about dependency pins and kept the main visual and the reasons to use the project far down a 343-line page. This restructures it so the first screen says what the project does and why to use it, and the rest scans as tables.

  • Top unchanged: logo, title, tagline, Website, Quick Start and Docs links, and all badges.
  • New pitch line and a jump-link row (Install, Quick start, Why this fork, Features, Storage, Migrating, Docs), with flow.gif moved up as the hero image.
  • "Why streaming-community": five bullets, each backed by CI or a merged pull request.
  • Installation: one command and a table of the optional extras.
  • Quick start: one short example that writes MDS shards and streams them through a DataLoader. Unlike the previous examples, which were all skipped, it runs under pytest-codeblocks in CI.
  • Key features: one table with a one-line benefit per feature, each linking to its docs page. The mixing example and the determinism, convergence and throughput results move into collapsible sections; the results are labelled as measured for the original MosaicML Streaming.
  • New tables for storage backends (address prefixes and required extras, taken from streaming/base/storage/download.py) and for compatibility (supported ranges next to what CI checks).
  • About this fork: the fork paragraph is unchanged; "What stays the same" and the migration steps are unchanged inside a collapsible section. The starter-code table, the project showcase and the citation are collapsed too.
  • Community section with Discussions, Issues, CONTRIBUTING, SECURITY and CHANGELOG, and the star line.
  • Fixes the "Disk usage limits" link, which pointed at a docs file that does not exist.

Only HTML that PyPI keeps is used (tables, <details>, <img>, <div align>), and all images use absolute URLs. The jump links target the heading ids GitHub and PyPI generate.

Checked: pytest README.md gives 1 passed (the quick start) and 6 skipped; the pre-commit hooks pass; twine check --strict passes on a built wheel; on the pushed branch, GitHub renders all 6 collapsible sections and 6 tables, and every jump link resolves to its section. The PyPI page changes with the next release.

@avgvi
avgvi merged commit 1b059a0 into main Oct 11, 2026
15 checks passed
@avgvi
avgvi deleted the readme-update branch October 11, 2026 22:52
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.

1 participant