alunduil / alunduil/zfs-replicate

The README carries badges, an end-user install path, and links to the supporting docs

未关闭
#623 0 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看
enhancement
主要语言
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 还没有评估数据。

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。