exadra37-versioning/explicit-versioning

A specification for Software Releases that care about intentional breaking changes being explicit announced in the versioning schema.

explicit-versioning's Issues

Best Practices for Development and Production Releases

Due to this comment it will be good to create a separated documentation file with examples how to use Explicit Versioning for Development releases and Production Releases.

Maybe something like how-to-use.md file should then be linked from the Specification in the README.

Software Versioning Workflow

Following up on issue #4, depending on the background of the Developer trying to do Software Versioning, by following the Best Practices for Software Versioning and Explicit Versioning, he/she may found the need to understand how the workflow look like.

So instead of accumulating the workflow examples in the same document we explain the Best Practices we will have a dedicated document WORKFLOW.md just for this.

Optional Identifiers

After the Explicit Version schema we may want to use optional identifiers, like:

• 1.0.0.0-Alpha1
• 1.0.0.0-Beta1
• 1.0.0.0-RC1
• 1.0.0.0-Build123

And any other one we may need for our internal or public Software Release process.

This optional identifiers MUST NOT clash with the Explicit Versioning Specification Schema intentions:

For example not using an Optional Identifier to say that:

• Major Relase.
• Breaking change release.
• Compatible Release.
• Fix Release.

A section in the Specification must be added to clarify this Optional Identifiers usage.

This is related with the Pull Request comment #2 (comment)

Improve Required Identifiers Schema

Release
is incremented when changing the API, changing the UX, switching to a new recommended version or ending support for previous versions.

When working on issue #4 I realized that the text for the Release identifier is somewhat contradictory, due to saying that can be used to release new versions or to end support for previous versions.

Giving a version 1.0.28.32 that we end support for it means we will tag it as 2.0.0.0, but for this to happen the functionality MUST have changed a lot, what means we are using a new version.

Putting it in another way if we already have a version 2.* how you gone increment the version 1.* to mark is end of support???

Ending support for a previous version should be done using the Optional Identifier, like:

• 1.0.28.32-End_Of_Support.
• 1.0.28.32-EOS
• 1.0.28.32-Final

Also I have found a better naming for the first identifier that will please @colomet

Disruptive.Incompatible.Compatible.Fix

"Why" example seems to be coming from an erroneous premise

So, take this with a grain of salt - someone linked me this github because they wanted my opinion on the idea of Explicit Versioning instead of SemVer, so I took a quick look.

One thing strikes me as awkward, but again, I'm not invested at all in this versioning system so this is just me playing devil's advocate.

The problem I'm seeing is that The Why Page specifically mentions Laravel 4.x as an example of why one would need something else than SemVer to version stuff. But this entire section contradicts the premise, for one simple reason:

Laravel didn't start using SemVer until version 6, so version 4 didn't have to follow the MAJOR.MINOR.PATCH system, so they were introducing changes that weren't backwards compatible in minor versions. This isn't because SemVer is wrong, it's because they simply weren't using SemVer at that time.

Version 6 and higher follow SemVer ( patch notes, first item ), while versions up to 5.8 followed their own "paradigm.major.minor" versioning ( 5.8 patch notes, first item ).

So what does this tell me? It tells me the "WHY" is wrong and the entire premise is flawed. To solidify the reason why anyone would want to move away from SemVer, you should find an example of where SemVer actually fails in its own protocols, and you haven't demonstrated this.

As a side-note, your "Disruptive" vs "Breaking" versions really don't add much, since a breaking backwards-incompatible change would, by definition, always be disruptive to the user.

Improve navigation across documents

To improve the navigation across the several documents in the Explicit Versioning repository:

• Each document must contain at least 1 link to go back to the HOME page, the README.md file.
• The HOME page file must contain a section with a list with links to all documents and their sections.

Terms Scope in Explicit Versioning Context

Depending on the background of each Developer or User reading the Explicit Versioning it may happen that it will not recognize some of the terms used or have another idea about them.

This can be true specially for non native English speakers, like me, that in the begin of my Developer journey was having a very hard time to grasp all this new terms and concepts.

Sometimes I was even understanding them in a wrong way and just realising that much more ahead in my journey.

So to help in this situations I will add a documentation to give scope in the context of Explicit Versioning for each of the terms used for the Required and Optional Identifiers as also for any other term that I think it may deserve it.

Add FAQ document

While Explicit Versioning is gaining traction, some questions will popup overtime and this questions may be already documented, but normally we Humans are good in overlook them when reading the documentation.

This can happens because:

• we are reading in a rush.
• not reading with attention.
• reading when tired.
• we are being simple lazy and instead of reading we just open a new issue and wait for somebody else to do the work for us.

As a Moderator in a forum I see all them happen a lot, specially the last one.

So the FAQ will be a place to put the Question and Reply for the most pertinent questions we will find overtime.

Anyway when a question popups and the document is referring to is not clear enough, than we must amend the document instead.

This FAQ document will be separated from the README holding the Specification.

Ordering Explicit Versions

In this spec, pre-release identifiers (like 1.6.2.0-Alpha1) are treated the same to release identifiers (like 3.5.0.1-LTS_2021-07). However, this should not be the case; when ordering versions, pre-releases should be placed before the full release and EOS & LTS should probably be placed after.

This spec doesn't mention how versions should be compared, something like 0.16.1.4 < 1.0.0.0-Alpha1 < 1.0.0.0-Beta2 < 1.0.0.0-RC1.

I'd recommend following the SemVer method of using a plus sign to append metadata about the build, which I would consider EOS & LTS to be a part of (for example, 1.0.6.2+LTS_2020-12), and then also follow the SemVer method of ordering versions by disregarding the contents of the metadata and then comparing in numerical order for the dotted versions and ASCII order for the pre-release identifiers. i.e., disruptive -> incompatible -> compatible -> fix -> identifiers, which release versions being ordered after pre-releases. This change would split §Optional Identifiers into a new section about build metadata, which could also be expanded on to support information other than EOS & LTS like build IDs etc.