Skip to content

The README comparison table makes undated, unsourced claims about other projects #166

Description

@eiserv

What

The README's "Why easySFTP?" section carries a feature comparison table against four other actions (Dylan700/sftp-upload-action, SamKirkland/FTP-Deploy-Action, wlixcc/SFTP-Deploy-Action, wangyucode/sftp-upload-action), asserting things about each of them: host key verification support, atomic per-file upload, skip-unchanged behaviour, delete safety guards, and more.

There is no date on the table and no link to the evidence behind any individual cell.

Why it matters

This repo already has a rule for exactly this failure mode, and it applies here with more force, not less. CLAUDE.md says of docs/providers.md:

Provider entries are the one page where a plausible guess is worse than a gap: a wrong port or path costs a user a broken deploy and they cannot tell it came from nobody's machine. Every entry carries a *Last verified: DATE, source* line.

The comparison table has the same property with an added edge: it makes claims about other people's projects, in the most prominent position in the repository, and every one of those projects can change tomorrow. A "no" that was true when written and is false now is not a stale note, it is a public misrepresentation of somebody else's work. That is the kind of thing that draws a justified complaint, and it is avoidable.

Some cells are also inherently fuzzy. "not documented" (used twice) is an honest phrasing of an absence of evidence, but it sits in the same column as hard yes/no claims and reads as a verdict. "partial (rsync)" is an interpretation, not an observation.

To be clear, nothing here says the table is wrong. The point is that its accuracy is currently unverifiable by a reader and unmaintainable by a future contributor, because there is no record of what was checked, when, or against which version.

Suggested direction

Apply the providers.md standard to the table:

  1. Add a *Last verified: DATE* line directly beneath it.
  2. Record the version or commit of each compared action that was checked. A short footnote list is enough.
  3. Where a cell says "not documented", make the phrasing unambiguous that it means "the project's README does not state this", not "this project does not do this".
  4. Add a one-line invitation to open an issue if a maintainer of a compared project believes a cell is wrong. Cheap, and it converts a potential complaint into a correction.

Optionally, add a note to CLAUDE.md extending the evidence-only rule to the README comparison table, so future automated sessions treat it the same way as docs/providers.md rather than editing it freely.

Labelled needs-check because deciding how much verification effort this table is worth (and whether to keep it at all) is a judgment call for the maintainer, not something to change unilaterally.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationneeds-checkNeeds a closer look by a human or a future session before acting

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions