Skip to content

docs: fix metadata, slim the README, widen CI to 3.10-3.13 - #1

Merged
TheronRadley merged 2 commits into
mainfrom
arena/7545f9e9-tiny-git
Oct 10, 2026
Merged

TheronRadley merged 2 commits into
mainfrom
arena/7545f9e9-tiny-git

Conversation

@TheronRadley

Copy link
Copy Markdown
Owner

What this does

Works the "quick wins" and the two documentation items from the roadmap, top to bottom.

Quick wins

  • Clone URL — github.com/example/tiny-git → github.com/TheronRadley/tiny-git. Also fixed four project.urls in pyproject.toml that were still pointing at example/.
  • Intro & naming — removed the duplicated tiny-git (tiny-git), and added a table explaining the hyphen once: tiny-git is the distribution and the command, tinygit is the importable package, because hyphens are not legal in Python identifiers.
  • Live badges — replaced [Tests: 98 Passed (0 Failed)] with the workflow's own badge, and stripped baked-in counts from the prose. Counts now live in docs/testing.md with the command to regenerate them.
  • Topics — ⚠️ blocked, needs you. gh repo edit --add-topic returns HTTP 403: Resource not accessible by integration. The token reports admin: true on the repo but the app installation lacks the Administration permission that the topics endpoint requires. Add python, git, version-control, educational under Settings → General → Topics, or grant the app that permission.
  • Social preview — image generated and committed to docs/, but GitHub has no API for social previews; it must be uploaded under Settings → General → Social preview.

Docs

  • Slim README — invariants table, test breakdown, and benchmarks moved into docs/ behind a documentation index. The README keeps the pitch, install, quick start, and command list.
  • Git-compatibility note — new "Not wire-compatible with real Git" section. Verified in src/tinygit/objects.py: Tree.serialize() emits UTF-8 mode sha name\n lines, and .tinygit/index is JSON. Real git reads binary trees and a binary index, so neither tool can read the other's repository.

Packaging & CI

  • Python floor — requires-python lowered >=3.12 → >=3.10, classifiers and ruff/mypy targets follow. Matrix is now ubuntu + macos × 3.10–3.13, fail-fast: false.
  • Windows — added as a non-blocking job. os.chmod(0o755) only flips the read-only bit on Windows, so the executable-mode round-trip tests cannot pass there. The four specific call sites are named in a workflow comment; promote the job once they skip on platforms without POSIX mode bits.
  • .gitattributes — * text=auto eol=lf, so blobs and fixtures are never rewritten on a Windows checkout.
  • PEP 639 license — license = "MIT" with setuptools>=77, clearing the build deprecation that would otherwise block a PyPI publish (deadline 2027-02-18).

CHANGELOG

Collapsed the 1.0.0 / 1.1.0 entries into a single 1.0.0. Neither version was ever tagged or published, every feature listed under both is present in the shipped code, and 1.1.0 stays reserved for the roadmap's tag / count-objects / gc work — so this file, pyproject.toml, and the v1.0.0 tag will agree.

Corrections to claims that were wrong

Claim Reality
fsck sample output showed ✓ 3 objects checked The quick start immediately above it produces 6 objects (2 blobs + 2 trees + 2 commits). Output replaced with a real captured run.
"full CLI workflows … live CLI subprocess execution" grep -rn subprocess tests/ returns nothing. test_cli_contract.py calls main() in-process. Noted as an open gap in docs/testing.md.
Benchmark table listed status and diff rows run_benchmarks.py emits status_staged, status_clean, and diff_clean. The table did not match the script that produced it.
"Over 25 dedicated test functions" for merging 27 across six files — roughly right, but now stated without a number that will rot.

Verification

Run locally on Python 3.11.2 (below the old >=3.12 floor):

pytest                     -> 98 passed in 3.96s
ruff check src tests       -> All checks passed!
mypy src                   -> Success: no issues found in 16 source files
mypy --python-version 3.10 -> Success: no issues found in 16 source files
python -m build            -> sdist + wheel, no deprecation warnings

The wheel was installed into a clean venv and the tiny-git console script exercised end to end (init → config → add → commit → fsck → log). Benchmarks were re-run at 100/1,000/2,500/10,000 files; all operations scale between 9.1× and 10.5× for a 10× file increase, i.e. linear.

3.10 is asserted by this PR's CI run, not by a local run — there is no 3.10 interpreter in the sandbox. If the 3.10 leg goes red, the floor needs to move back to >=3.11.

Follow-ups (not in this PR)

  • Topics and social preview need repo-settings access.
  • Windows: guard the four exec-bit assertions, then promote the job into the blocking matrix.
  • A real subprocess CLI test via sys.executable -m tinygit.

Arena Agent and others added 2 commits October 10, 2026 10:10
Quick wins from the roadmap, plus the two documentation items.

README
- Fix the clone URL: github.com/example/tiny-git -> github.com/TheronRadley/tiny-git.
- Remove the duplicated "tiny-git (tiny-git)" in the intro and explain the
  hyphen once: `tiny-git` is the distribution/command, `tinygit` is the
  importable package, because hyphens are not legal in Python identifiers.
- Replace the hardcoded "[Tests: 98 Passed (0 Failed)]" line with a live
  GitHub Actions badge, and drop the baked-in counts from the prose.
- Move the invariants table, the test-suite breakdown, and the benchmark
  table into docs/ behind a documentation index. The README keeps the
  pitch, install, quick start, and command list.
- Add a "Not wire-compatible with real Git" section: trees are UTF-8 text
  and the index is JSON, so real git cannot read a .tinygit repository.
- Correct the sample `fsck` output. It claimed 3 objects for the quick
  start that precedes it; the real run produces 6.

docs/
- New docs/testing.md: what the suite covers, a dated per-module inventory,
  and the command to regenerate it. Notes that no test currently spawns a
  real subprocess -- the CLI contract tests call main() in-process.
- New docs/benchmarks.md: freshly measured numbers at 100/1k/2.5k/10k files
  with the exact hardware, Python version, and run count recorded. The old
  README table did not match the script's actual output keys.

Packaging & CI
- pyproject: fix the four project.urls still pointing at example/tiny-git,
  lower requires-python to >=3.10 with matching classifiers, target ruff and
  mypy at py310, and switch to the PEP 639 SPDX license expression
  (setuptools>=77) to clear the build deprecation that would block a
  future PyPI publish.
- tests.yml: matrix over ubuntu+macos x Python 3.10-3.13 with fail-fast off,
  plus a clearly-labelled non-blocking Windows job. Windows is kept
  non-blocking because the executable-mode round-trip tests cannot pass
  there; the specific blockers are listed in a comment.
- Add .gitattributes pinning eol=lf so blobs and test fixtures are never
  rewritten on a Windows checkout.

CHANGELOG
- Collapse the 1.0.0/1.1.0 entries into a single 1.0.0. Neither was ever
  tagged or published, every feature listed under both is in the shipped
  code, and 1.1.0 stays reserved for the roadmap's tag/count-objects/gc work.

Co-authored-by: arena-agent <297053741+arena-agent@users.noreply.github.com>
Generated at 1774x887 (exact 2:1) and resampled to GitHub's recommended
1280x640 with Lanczos, landing at 0.6 MB -- under the 1 MB upload cap.
GitHub exposes no API for social previews, so it still has to be attached
manually under Settings -> General -> Social preview; keeping the source in
the repo means it is version-controlled and regenerable.

Co-authored-by: arena-agent <297053741+arena-agent@users.noreply.github.com>
@TheronRadley
TheronRadley merged commit fe8b1f3 into main Oct 10, 2026
8 of 9 checks passed
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