[GH-ISSUE #1068] Clarification (an additional FAQ entry) on documentation error. #1521

New Issue

GiteaMirror · 2026-04-16T10:56:22-05:00

GiteaMirror commented

2026-04-16 10:56:22 -05:00

Originally created by @dannyniu on GitHub (Dec 29, 2024).
Original GitHub issue: https://github.com/semver/semver/issues/1068

I'm setting up my workflow to the latest standard, and I bump into this problem.

What if my software code is correct, but its documentation is in error? Possible scenarios:

an off-by-one error,
wrong assumption, etc.

I asked this at here: https://softwareengineering.stackexchange.com/q/456161/290091 and I got answers. But what's not satisfactory is that, all the answers are considering documents as decoupled from the code, which I do not completely agree.

So ultimately, what should developers do to the version number, when the software is correct while the document/specification is wrong?

Originally created by @dannyniu on GitHub (Dec 29, 2024). Original GitHub issue: https://github.com/semver/semver/issues/1068 I'm setting up my workflow to the latest standard, and I bump into this problem. What if my software code is correct, but its documentation is in error? Possible scenarios: 1. an off-by-one error, 2. wrong assumption, etc. I asked this at here: https://softwareengineering.stackexchange.com/q/456161/290091 and I got answers. But what's not satisfactory is that, all the answers are considering documents as decoupled from the code, which I do not completely agree. So ultimately, what should developers do to the version number, when the software is correct while the document/specification is wrong?

GiteaMirror commented

2026-04-16 10:56:23 -05:00

@dannyniu commented on GitHub (Dec 29, 2024):

Previously:

Documentation-only updates are obviously patch - they don't break anything and they aren't adding a new runtime feature.

You can use a prerelease identifier, sure, but then semver ranges in ecosystems like npm aren't likely to automatically update to them.

Originally posted by @ljharb in https://github.com/semver/semver/issues/609#issuecomment-779469594

This is a completely different situation. The client code is already making non-existing assumption about the callee/dependency that only exist in docs.

@dannyniu commented on GitHub (Dec 29, 2024): Previously: > Documentation-only updates are obviously patch - they don't break anything and they aren't adding a new runtime feature. > > You can use a prerelease identifier, sure, but then semver ranges in ecosystems like npm aren't likely to automatically update to them. > > _Originally posted by @ljharb in https://github.com/semver/semver/issues/609#issuecomment-779469594_ This is a completely different situation. The client code is already making non-existing assumption about the callee/dependency that only exist in docs.

GiteaMirror commented

2026-04-16 10:56:24 -05:00

@ljharb commented on GitHub (Dec 29, 2024):

I think it depends on the kind of error, and the consequences of correcting it - but either way, what the code actually does is far more important/impactful then what the docs say.

@ljharb commented on GitHub (Dec 29, 2024): I think it depends on the kind of error, and the consequences of correcting it - but either way, what the code actually does is far more important/impactful then what the docs say.

GiteaMirror commented

2026-04-16 10:56:24 -05:00

@masoudaflaki commented on GitHub (Jun 11, 2025):

Hi thanks for support and sponsor

@masoudaflaki commented on GitHub (Jun 11, 2025): Hi thanks for support and sponsor

GiteaMirror commented

2026-04-16 10:56:25 -05:00

@dannyniu commented on GitHub (Jun 13, 2025):

@ljharb The specific kind of error in question, is where the downstream "consumer code" depend on a documented behavior not present, or is different from that in the "provider code".

I think this might be most relevant.

@dannyniu commented on GitHub (Jun 13, 2025): @ljharb The specific kind of error in question, is where the downstream "consumer code" depend on a documented behavior not present, or is different from that in the "provider code". I think [this](https://semver.org/#what-do-i-do-if-i-accidentally-release-a-backward-incompatible-change-as-a-minor-version) might be most relevant.

GiteaMirror commented

2026-04-16 10:56:26 -05:00

@ljharb commented on GitHub (Jun 14, 2025):

That particular FAQ item is wrong imo; it shouldn’t say “minor”, it should say “non-major” or “patch”.

@ljharb commented on GitHub (Jun 14, 2025): That particular FAQ item is wrong imo; it shouldn’t say “minor”, it should say “non-major” or “patch”.

GiteaMirror commented

2026-04-16 10:56:27 -05:00

@steveklabnik commented on GitHub (Jun 16, 2025):

I'd agree with that.

@steveklabnik commented on GitHub (Jun 16, 2025): I'd agree with that.

GiteaMirror commented

2026-04-16 10:56:28 -05:00

@ljharb commented on GitHub (Jun 16, 2025):

→ #1128 to fix the FAQ

@ljharb commented on GitHub (Jun 16, 2025): → #1128 to fix the FAQ

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/semver#1521