Projects versioning strategy

Today Asciidoctor projects use different versioning schemas.

Versioning schemas

Core versioning (same version)

The following projects are using the same number as the core:

• Asciidoctor core 1.5.2
• AsciidoctorJ 1.5.2
• Asciidoctor.js 1.5.2
• Asciidoclet 1.5.2
• Asciidoctor Gradle Plugin 1.5.2

Core plus fourth number versioning

The fourth number is used to release new version for the same core version:

• Asciidoctor Chrome Extension 1.5.2.111
• Asciidoctor Maven Plugin 1.5.2.1

The Asciidoctor Chrome Extension is using semantic version on the fourth number (i.e. three digits on the fourth number).
Version 1.5.2.111 should be read as version 1.1.1 of the extension using Asciidoctor 1.5.2.

Other versioning (not the latest version)

I'm not sure if the following projects are compatible with/using Asciidoctor 1.5.2 ?

• Asciidoctor ANT 1.5.1
• Asciidoctor EPUB3 1.5.0.alpha.4
• Asciidoctor PDF 1.5.0.alpha.9

Semantic versioning

The following projects are using semantic versioning (not related to the core version):

• Asciidoctor IntelliJ Plugin 0.10
• Brackets Asciidoc Preview 1.1.8
• Asciidoctor Firefox Addon 0.4.0
• Asciidoctor Diagram 1.3.1
• Atom Asciidoc Preview 0.6.0

Proposal

I think it would be great to use the same versioning strategy across the Asciidoctor organisation.

While Asciidoctor core version is an essential information, I think we should embrace semantic versioning.
To avoid confusion between core version and projects versions we could use "build metadata" as defined in the semantic versioning.
For example, if we want to denote that the plugin version 0.1.4 is using Asciidoctor 1.5.2, we could use the version 0.1.4+core1.5.2.
This can be useful when project version and core version are "conflicting" (i.e. 0.1.4, 1.5.0, 1.5.1...).
Another proposal from Dan:

Here's another option to consider. I think it's fine for modules to move ahead of the core version in prereleases. Otherwise, everything has to wait for core to be released to start having prereleases, and that just makes no sense. So we'd only guarantee the alignment with core when the final version is released. You can then use all the prerelease syntax of SemVer leading up to the final release of the module. (so this release can be 1.5.3-). Part of the reason we're in this situation is because core releases are moving too slow. It's been hard for me to balance expectations with releases, but I'm working to get there. I think we should assume (to put some pressure on it) that core will move a bit faster. I also don't think that the version alignment has to be down to the patch version. The idea all along was to let the patch version (the 3rd position) float and the alignment be on the minor version only (e.g., 1.5). (We could also start to make bigger shifts in the versions of core to make that more comfortable). We did try to allow the versions between core and the gradle plugin to vary widely and it was massively confusing. So it seems to me that the right answer is to have alignment to a point (e.g., 1.5), but not overdo it. But I'm still trying to figure this out myself, so that's just my hunch.

source

What do you think ?

---

If you reply to this email, your message will be added to the discussion below:

http://discuss.asciidoctor.org/Projects-versioning-strategy-tp3841.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

We've had this conversation before, but I don't think some of the projects were around when we finalized on using a semantic version following asciidoctor core, with a final digit to implement for the project itself, like what the Chrome extension is doing. That being said, everything on 1.5.x *should* all be compatible. The outlining projects, I really have no clue about. It would be very nice to fix this and be done with it (again) :)

On Mon, Oct 12, 2015 at 1:34 AM, ggrossetie [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Today Asciidoctor projects use different versioning schemas.

Versioning schemas

Core versioning (same version)

The following projects are using the same number as the core:

• Asciidoctor core 1.5.2
• AsciidoctorJ 1.5.2
• Asciidoctor.js 1.5.2
• Asciidoclet 1.5.2
• Asciidoctor Gradle Plugin 1.5.2

Core plus fourth number versioning

The fourth number is used to release new version for the same core version:

• Asciidoctor Chrome Extension 1.5.2.111
• Asciidoctor Maven Plugin 1.5.2.1

The Asciidoctor Chrome Extension is using semantic version on the fourth number (i.e. three digits on the fourth number).
Version 1.5.2.111 should be read as version 1.1.1 of the extension using Asciidoctor 1.5.2.

Other versioning (not the latest version)

I'm not sure if the following projects are compatible with/using Asciidoctor 1.5.2 ?

• Asciidoctor ANT 1.5.1
• Asciidoctor EPUB3 1.5.0.alpha.4
• Asciidoctor PDF 1.5.0.alpha.9

Semantic versioning

The following projects are using semantic versioning (not related to the core version):

• Asciidoctor IntelliJ Plugin 0.10
• Brackets Asciidoc Preview 1.1.8
• Asciidoctor Firefox Addon 0.4.0
• Asciidoctor Diagram 1.3.1
• Atom Asciidoc Preview 0.6.0

Proposal

I think it would be great to use the same versioning strategy across the Asciidoctor organisation.

While Asciidoctor core version is an essential information, I think we should embrace semantic versioning.
To avoid confusion between core version and projects versions we could use "build metadata" as defined in the semantic versioning.
For example, if we want to denote that the plugin version 0.1.4 is using Asciidoctor 1.5.2, we could use the version 0.1.4+core1.5.2.
This can be useful when project version and core version are "conflicting" (i.e. 0.1.4, 1.5.0, 1.5.1...).
Another proposal from Dan:

Here's another option to consider. I think it's fine for modules to move ahead of the core version in prereleases. Otherwise, everything has to wait for core to be released to start having prereleases, and that just makes no sense. So we'd only guarantee the alignment with core when the final version is released. You can then use all the prerelease syntax of SemVer leading up to the final release of the module. (so this release can be 1.5.3-). Part of the reason we're in this situation is because core releases are moving too slow. It's been hard for me to balance expectations with releases, but I'm working to get there. I think we should assume (to put some pressure on it) that core will move a bit faster. I also don't think that the version alignment has to be down to the patch version. The idea all along was to let the patch version (the 3rd position) float and the alignment be on the minor version only (e.g., 1.5). (We could also start to make bigger shifts in the versions of core to make that more comfortable). We did try to allow the versions between core and the gradle plugin to vary widely and it was massively confusing. So it seems to me that the right answer is to have alignment to a point (e.g., 1.5), but not overdo it. But I'm still trying to figure this out myself, so that's just my hunch.

source

What do you think ?

---

If you reply to this email, your message will be added to the discussion below:

http://discuss.asciidoctor.org/Projects-versioning-strategy-tp3841.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

... [show rest of quote]

--

Jason Porter
http://en.gravatar.com/lightguardjp

---

If you reply to this email, your message will be added to the discussion below:

http://discuss.asciidoctor.org/Projects-versioning-strategy-tp3841p3842.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

Here's a useful article on versioning for library maintainers. Good input for establishing our own strategy.

http://www.schneems.com/2015/11/29/what-is-semver.html

-Dan

On Mon, Oct 12, 2015 at 8:22 AM, LightGuardjp [via Asciidoctor :: Discussion] <[hidden email]> wrote:

We've had this conversation before, but I don't think some of the projects were around when we finalized on using a semantic version following asciidoctor core, with a final digit to implement for the project itself, like what the Chrome extension is doing. That being said, everything on 1.5.x *should* all be compatible. The outlining projects, I really have no clue about. It would be very nice to fix this and be done with it (again) :)

On Mon, Oct 12, 2015 at 1:34 AM, ggrossetie [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Today Asciidoctor projects use different versioning schemas.

Versioning schemas

Core versioning (same version)

The following projects are using the same number as the core:

• Asciidoctor core 1.5.2
• AsciidoctorJ 1.5.2
• Asciidoctor.js 1.5.2
• Asciidoclet 1.5.2
• Asciidoctor Gradle Plugin 1.5.2

Core plus fourth number versioning

The fourth number is used to release new version for the same core version:

• Asciidoctor Chrome Extension 1.5.2.111
• Asciidoctor Maven Plugin 1.5.2.1

The Asciidoctor Chrome Extension is using semantic version on the fourth number (i.e. three digits on the fourth number).
Version 1.5.2.111 should be read as version 1.1.1 of the extension using Asciidoctor 1.5.2.

Other versioning (not the latest version)

I'm not sure if the following projects are compatible with/using Asciidoctor 1.5.2 ?

• Asciidoctor ANT 1.5.1
• Asciidoctor EPUB3 1.5.0.alpha.4
• Asciidoctor PDF 1.5.0.alpha.9

Semantic versioning

The following projects are using semantic versioning (not related to the core version):

• Asciidoctor IntelliJ Plugin 0.10
• Brackets Asciidoc Preview 1.1.8
• Asciidoctor Firefox Addon 0.4.0
• Asciidoctor Diagram 1.3.1
• Atom Asciidoc Preview 0.6.0

Proposal

I think it would be great to use the same versioning strategy across the Asciidoctor organisation.

While Asciidoctor core version is an essential information, I think we should embrace semantic versioning.
To avoid confusion between core version and projects versions we could use "build metadata" as defined in the semantic versioning.
For example, if we want to denote that the plugin version 0.1.4 is using Asciidoctor 1.5.2, we could use the version 0.1.4+core1.5.2.
This can be useful when project version and core version are "conflicting" (i.e. 0.1.4, 1.5.0, 1.5.1...).
Another proposal from Dan:

Here's another option to consider. I think it's fine for modules to move ahead of the core version in prereleases. Otherwise, everything has to wait for core to be released to start having prereleases, and that just makes no sense. So we'd only guarantee the alignment with core when the final version is released. You can then use all the prerelease syntax of SemVer leading up to the final release of the module. (so this release can be 1.5.3-). Part of the reason we're in this situation is because core releases are moving too slow. It's been hard for me to balance expectations with releases, but I'm working to get there. I think we should assume (to put some pressure on it) that core will move a bit faster. I also don't think that the version alignment has to be down to the patch version. The idea all along was to let the patch version (the 3rd position) float and the alignment be on the minor version only (e.g., 1.5). (We could also start to make bigger shifts in the versions of core to make that more comfortable). We did try to allow the versions between core and the gradle plugin to vary widely and it was massively confusing. So it seems to me that the right answer is to have alignment to a point (e.g., 1.5), but not overdo it. But I'm still trying to figure this out myself, so that's just my hunch.

source

What do you think ?

---

If you reply to this email, your message will be added to the discussion below:

http://discuss.asciidoctor.org/Projects-versioning-strategy-tp3841.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

... [show rest of quote]

--

Jason Porter
http://en.gravatar.com/lightguardjp

---

If you reply to this email, your message will be added to the discussion below:

http://discuss.asciidoctor.org/Projects-versioning-strategy-tp3841p3842.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

... [show rest of quote]

--

Dan Allen | @mojavelinux | http://google.com/profiles/dan.j.allen