alunduil / alunduil/zfs-replicate
The README carries badges, an end-user install path, and links to the supporting docs
- 主要语言
- Python
- 星标
- 24
- 派生
- 6
- 平均合并
- 3 小时 11 分钟
- 30 天内合并 PR
- 49
描述
## Summary
Audit `README.md` with the `readme` skill, which applies ddbeck's checklist and a
shields.io badge principle, and close the gaps it finds.
## Motivation
Filed as a follow-up while working #430. Four gaps are visible without running
the audit, which is enough to say the review is worth doing.
**No badges.** `README.md` contains no shields.io markup at all. The project
runs CI (`.github/workflows/ci.yml`), uploads coverage to Coveralls
(`ci.yml:56-62`), and publishes to PyPI (`release.yml:31`), so build status,
coverage, and the released version are all signals that exist and go unpublished
on the front door.
**No end-user install path.** `README.md:62-63` gives `poetry install` and
`poetry run -- zfs-replicate --help` under "How to use zfs-replicate". That is a
contributor workflow: it assumes a clone and a Poetry installation. This project
publishes to PyPI and the repository homepage points at the PyPI project page,
so someone who wants to run the tool has no documented `pip install` or `pipx
install` route.
**Supporting docs are unreachable.** `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`,
and `CHANGELOG.md` all exist and none is linked from the README. The
"Documentation" list at `README.md:92-104` points at `--help`, the licence, and
four external ZFS articles instead.
**Structure buries the usage.** "Terms of use" at `README.md:26` and
"Prerequisites" at `README.md:31-58` sit between the description and the usage
section, and Prerequisites carries a fourteen-item nested list of ZFS
permissions. A reader deciding whether to use the tool meets the licence and a
permission matrix before they meet an install command.
## Scope
- Run the `readme` skill's audit over `README.md` and work its findings.
- Add badges for signals that already exist, applying the skill's principle that
each badge earns its place and links to its source.
- Document installing from PyPI for end users, keeping the from-source path for
contributors.
- Link `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, and `CHANGELOG.md`.
- Reconsider the heading order so purpose and install precede the prerequisites
detail.
- Decide whether "Terms of use" becomes a conventional licence section.
## Acceptance criteria
- [ ] A reader can install and run `zfs-replicate` without cloning the
repository
- [ ] Every badge maps to a signal that exists and links to its source
- [ ] `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, and `CHANGELOG.md` are reachable
from the README
- [ ] No section duplicates content #463 moves into `docs/`
## Additional context
#463 removes the "Setting properties on the replica" and "Tuning the send
stream" sections from the README and replaces them with a pointer. Both issues
edit the same headings, so whichever lands second takes the conflicts, and the
structural decisions here should assume #463's shape rather than the current
one.
#410 adds a private security disclosure path. If a `SECURITY.md` lands, the
README should link it alongside the other supporting documents.
The Nix pointer at `README.md:65-68` arrived in #617 and is current.
贡献指南
评估
这个 Issue 还没有评估数据。