[GH-ISSUE #287] Clarify guidance on when to release 1.0.0 #5324

New Issue

GiteaMirror · 2026-06-15T11:37:52-05:00

GiteaMirror commented

2026-06-15 11:37:52 -05:00

Originally created by @VWoeltjen on GitHub (Nov 25, 2015).
Original GitHub issue: https://github.com/semver/semver/issues/287

In the FAQ, the answer to the question How do I know when to release 1.0.0? is:

If your software is being used in production, it should probably already be 1.0.0. If you have a stable API on which users have come to depend, you should be 1.0.0. If you're worrying a lot about backwards compatibility, you should probably already be 1.0.0.

From a reader's perspective, one of two things is true:

One of those ifs applies to me, and I should probably be at 1.0.0 (so the answer is "some time in the past")
None of those ifs applies to me, and I don't know if I should be at 1.0.0 or not.

In other words, this answer is only useful when it's too late; proactive readers who are trying to follow the spirit of the specification don't actually get an answer from this.

Ultimately, it's the reader's responsibility to make the right judgment for their project. But maintaining compatibility is a large liability to a project (with a large benefit to users of the project), so people who have uncertainty - the same people who go to read FAQs - are going to be inclined to err on the side of caution and stay in 0.x.y. I think some more constructive guidance here ("you are probably ready if...") might reduce some of the 1.0.0 aversion that has been noted.

Originally created by @VWoeltjen on GitHub (Nov 25, 2015). Original GitHub issue: https://github.com/semver/semver/issues/287 In the FAQ, the answer to the question [How do I know when to release 1.0.0?](https://github.com/mojombo/semver/blob/v2.0.0/semver.md#how-do-i-know-when-to-release-100) is: > If your software is being used in production, it should probably already be 1.0.0. If you have a stable API on which users have come to depend, you should be 1.0.0. If you're worrying a lot about backwards compatibility, you should probably already be 1.0.0. From a reader's perspective, one of two things is true: - One of those ifs applies to me, and I should probably be at 1.0.0 (so the answer is "some time in the past") - None of those ifs applies to me, and I don't know if I should be at 1.0.0 or not. In other words, this answer is only useful when it's too late; proactive readers who are trying to follow the spirit of the specification don't actually get an answer from this. Ultimately, it's the reader's responsibility to make the right judgment for their project. But maintaining compatibility is a large liability to a project (with a large benefit to users of the project), so people who have uncertainty - the same people who go to read FAQs - are going to be inclined to err on the side of caution and stay in 0.x.y. I think some more constructive guidance here ("you are probably ready if...") might reduce some of the 1.0.0 aversion that [has been noted](https://github.com/mojombo/semver/pull/127#issuecomment-47832310).

GiteaMirror added the question staled labels 2026-06-15 11:37:52 -05:00

GiteaMirror closed this issue

2026-06-15 11:37:54 -05:00

GiteaMirror commented

2026-06-15 11:37:55 -05:00

@jwdonahue commented on GitHub (Dec 9, 2017):

@VWoeltjen,

After reviewing ~180 odd issues here at semver/semver, I have come to the conclusion that the 0.x.x loop-hole should be permanently closed. I agree the documentation is a little weak, as you point out, but I am inclined to recommend to anyone who has projects at 0.x.x, they should immediately set the major version to 1, reset minor and patch to zero and add a prerelease tag. Then the spec and the FAQ pretty much hold together.

@jwdonahue commented on GitHub (Dec 9, 2017): @VWoeltjen, After reviewing ~180 odd issues here at semver/semver, I have come to the conclusion that the 0.x.x loop-hole should be permanently closed. I agree the documentation is a little weak, as you point out, but I am inclined to recommend to anyone who has projects at 0.x.x, they should immediately set the major version to 1, reset minor and patch to zero and add a prerelease tag. Then the spec and the FAQ pretty much hold together.

GiteaMirror commented

2026-06-15 11:37:55 -05:00

@ajbogh commented on GitHub (Dec 14, 2018):

This has come under scrutiny by some of my coworkers. By my own logic, using item 4 as an example that 0.x.y signifies beta or pre-release software, they claim that the line "The public API SHOULD NOT be considered stable" within 4 indicates that it's OK to have a public API with 0.x.y.

The next number (5) starts with "Version 1.0.0 defines the public API." This should not have to change, as long as people don't misinterpret number 4 as allowing public APIs with pre-1.0 versions.

The line in the FAQ in the issue above states "If you're worrying a lot about backwards compatibility, you should probably already be 1.0.0" to which these people might say "if a project isn't worried about backwards compatibility then they don't need to be at 1.0.0".

Please update item 4 to state that versions prior to 1.0 should be considered Beta or Pre-release software and is not recommended for production environments. The easiest change is to remove the sentence "The public API SHOULD NOT be considered stable".

@ajbogh commented on GitHub (Dec 14, 2018): This has come under scrutiny by some of my coworkers. By my own logic, using item 4 as an example that 0.x.y signifies beta or pre-release software, they claim that the line "The public API SHOULD NOT be considered stable" within 4 indicates that it's OK to have a public API with 0.x.y. The next number (5) starts with "Version 1.0.0 defines the public API." This should not have to change, as long as people don't misinterpret number 4 as allowing public APIs with pre-1.0 versions. The line in the FAQ in the issue above states "If you're worrying a lot about backwards compatibility, you should probably already be 1.0.0" to which these people might say "if a project isn't worried about backwards compatibility then they don't need to be at 1.0.0". Please update item 4 to state that versions prior to 1.0 should be considered Beta or Pre-release software and is not recommended for production environments. The easiest change is to remove the sentence "The public API SHOULD NOT be considered stable".

GiteaMirror commented

2026-06-15 11:37:55 -05:00

@alexandrtovmach commented on GitHub (Jun 10, 2020):

This issue looks staled and will be closed in 10 days if there are no objections. Thanks everyone for contributions, you're amazing 🎆

@alexandrtovmach commented on GitHub (Jun 10, 2020): This issue looks staled and will be closed in 10 days if there are no objections. Thanks everyone for contributions, you're amazing :fireworks:

GiteaMirror commented

2026-06-15 11:37:56 -05:00

@alexandrtovmach commented on GitHub (Jun 19, 2020):

👻 👻 👻
Closed as staled

@alexandrtovmach commented on GitHub (Jun 19, 2020): 👻 👻 👻 Closed as staled

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/semver#5324