You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cordova.apache.org by Michael Brooks <mi...@michaelbrooks.ca> on 2014/04/10 20:00:30 UTC
[cordova-cli] Versioning Confusion
Hi all,
Recently, I've noticed that the cordova-cli is misusing the versioning
scheme
that is used by the phonegap-cli. It's a little confusing, but effective,
so let
me run through it.
---
VERSION BREAKDOWN
---
cordova@x.y.z-a.b.c
---
X.Y.Z
---
x.y.z is the version of Cordova that is bundled with the CLI. We all know
this.
---
A.B.C
---
a.b.c is the package (semver) version of the cordova-cli node library.
Imagine
that the cordova-cli could support any version of Cordova, then a.b.c would
be
the sole version used by the npm package; similar to any other npm package.
This version should always go up.
---
PROBLEM
---
The problem is that the cordova-cli is resetting a.b.c each time it
increments
x.y.z. For projects that use the node interface of the cordova-cli, this is
a
problem.
a.b.c describes changes to the node programmatic interface, just like
any other good node project published to npm. By resetting it, we confuse
and hurt developers who depend on the API because they don't know what
has changed in the node API.
---
BAD EXAMPLE (HOW IT IS TODAY)
---
cordova@3.1.0-0.1.0 - first release
cordova@3.1.0-0.2.0 - minor node api fix
cordova@3.2.0-0.1.0 - what!? Why did the node version reset to 0.1.0?
cordova@3.2.0-0.2.0 - minor node api fix
cordova@3.3.0-0.1.0 - what!? Node API users must manually discover what
changed
---
GOOD EXAMPLE
---
cordova@3.1.0@0.1.0 - first release
cordova@3.1.0@0.1.1 - patch to node package (no node api change)
cordova@3.1.0@0.2.0 - minor to node package (backwards compatible api
change)
cordova@3.2.0@0.2.0 - new cordova release; no node package changes
cordova@3.2.0@0.2.1 - patch to node package
cordova@3.3.0@0.2.2 - new cordova release; patch to node package
cordova@3.3.0@0.3.0 - minor to node package
cordova@3.3.0@1.0.0 - major to node package (non-backwards compatible api
change)
cordova@3.4.0@1.1.0 - new cordova release; minor to node package
cordova@3.4.0@1.1.1 - patch to node package
I hope this helps to improve the cordova-cli versioning habit.
Cheers!
Michael
Re: [cordova-cli] Versioning Confusion
Posted by Michael Brooks <mi...@michaelbrooks.ca>.
>
> However, Andrew previously pointed out that even if we stop doing a.b.c
> reset with releases, the form x.y.z-a.b.c is not valid semver and so isn't
> generally useful anyway. At least not for package.json fuzzy dependency
> versioning.
Unfortunately, the x.y.z-a.b.c approach will not work with fuzzy dependency
resolving in npm.
According to semver, we can use x.y.z+a.b.c, but npm's implementation of
semver does not
support this. At least, it didn't a year ago when I wrote up my original
Cordova CLI versioning
propose [1].
We're pretty much making the best of a bad situation. CLI users can
at-a-glance know what Cordova version
the CLI is using. Node.js library users can lock the cordova node
dependency to a specific version
and at-a-glance know whether any of the public APIs have been broken.
Eventually, Cordova CLI should be able to use any Cordova version. When
that happens, we can drop the
x.y.z and just publish with the a.b.c version.
> I notice that your list of good examples, you change the scheme to
> x.y.z@a.b.c (note the @), does that resolve the issue? Clever.
Oops, that's a typo! No, the @ doesn't resolve it.
[1]
http://mail-archives.apache.org/mod_mbox/cordova-dev/201304.mbox/%3CCAP7NMPqJ-7hXGmdtdvF-N4g37=Qx2xzE4eBh86-i2BMQXe0bXQ@mail.gmail.com%3E
On Thu, Apr 10, 2014 at 11:53 AM, Steven Gill <st...@gmail.com>wrote:
> Thanks for the writeup Mike.
>
> I agree that we are using it wrong. It shouldn't reset every time we change
> the cadence version number. We can implement this change right away unless
> people have reason not to.
>
> I have also heard rumblings about potentially removing the cadence number
> and using just SemVer. Since we are talking version numbers anyways, this
> might be a good time to discuss this.
>
> With platforms releases heading toward independent releases, our
> cadence number will soon become useless. IOS could be at 3.7.0 when
> FirefoxOS is at 3.4.0. What should the cadence number for the CLI be?
>
> When people think of what version Cordova is at, I figure it will be the
> version of the CLI.
>
> Cons
> - tooling dependent on X.Y.Z-A.B.C will break.
> - cadence number is historically how we make big splashes with our
> releases. Will this become more difficult?
>
> Pros
> - using SemVer properly
>
> I would propose if we do switch to SemVer only, that we start with our
> cadence value. For example, the CLI would be version 3.5.0. The cli's
> version number will increase at a much faster pace than platforms, but that
> is expected.
>
> Of course for us to get to this point, we should focus on figuring out our
> independent platform releases.
>
> Sorry for going on a tangent in your thread Mike :p
> Hi all,
>
> Recently, I've noticed that the cordova-cli is misusing the versioning
> scheme
> that is used by the phonegap-cli. It's a little confusing, but effective,
> so let
> me run through it.
>
> ---
> VERSION BREAKDOWN
> ---
>
> cordova@x.y.z-a.b.c
>
> ---
> X.Y.Z
> ---
>
> x.y.z is the version of Cordova that is bundled with the CLI. We all know
> this.
>
> ---
> A.B.C
> ---
>
> a.b.c is the package (semver) version of the cordova-cli node library.
> Imagine
> that the cordova-cli could support any version of Cordova, then a.b.c would
> be
> the sole version used by the npm package; similar to any other npm package.
>
> This version should always go up.
>
> ---
> PROBLEM
> ---
>
> The problem is that the cordova-cli is resetting a.b.c each time it
> increments
> x.y.z. For projects that use the node interface of the cordova-cli, this is
> a
> problem.
>
> a.b.c describes changes to the node programmatic interface, just like
> any other good node project published to npm. By resetting it, we confuse
> and hurt developers who depend on the API because they don't know what
> has changed in the node API.
>
> ---
> BAD EXAMPLE (HOW IT IS TODAY)
> ---
>
> cordova@3.1.0-0.1.0 - first release
> cordova@3.1.0-0.2.0 - minor node api fix
> cordova@3.2.0-0.1.0 - what!? Why did the node version reset to 0.1.0?
> cordova@3.2.0-0.2.0 - minor node api fix
> cordova@3.3.0-0.1.0 - what!? Node API users must manually discover what
> changed
>
> ---
> GOOD EXAMPLE
> ---
>
> cordova@3.1.0@0.1.0 - first release
> cordova@3.1.0@0.1.1 - patch to node package (no node api change)
> cordova@3.1.0@0.2.0 - minor to node package (backwards compatible api
> change)
> cordova@3.2.0@0.2.0 - new cordova release; no node package changes
> cordova@3.2.0@0.2.1 - patch to node package
> cordova@3.3.0@0.2.2 - new cordova release; patch to node package
> cordova@3.3.0@0.3.0 - minor to node package
> cordova@3.3.0@1.0.0 - major to node package (non-backwards compatible api
> change)
> cordova@3.4.0@1.1.0 - new cordova release; minor to node package
> cordova@3.4.0@1.1.1 - patch to node package
>
> I hope this helps to improve the cordova-cli versioning habit.
>
> Cheers!
> Michael
>
Re: [cordova-cli] Versioning Confusion
Posted by Michael Brooks <mi...@michaelbrooks.ca>.
>
> Thanks for the writeup Mike.
> I agree that we are using it wrong. It shouldn't reset every time we change
> the cadence version number. We can implement this change right away unless
> people have reason not to.
Awesome!
I have also heard rumblings about potentially removing the cadence number
> and using just SemVer. Since we are talking version numbers anyways, this
> might be a good time to discuss this.
> ...
> Sorry for going on a tangent in your thread Mike :p.
Steve, let's have this discussion on a separate thread. It's a big topic
and it deserves a focused thread. It's also something we should discuss in
next week's hangout, after everyone's had a chance to put some thought into
it.
Michael
On Thu, Apr 10, 2014 at 11:53 AM, Steven Gill <st...@gmail.com>wrote:
> Thanks for the writeup Mike.
>
> I agree that we are using it wrong. It shouldn't reset every time we change
> the cadence version number. We can implement this change right away unless
> people have reason not to.
>
> I have also heard rumblings about potentially removing the cadence number
> and using just SemVer. Since we are talking version numbers anyways, this
> might be a good time to discuss this.
>
> With platforms releases heading toward independent releases, our
> cadence number will soon become useless. IOS could be at 3.7.0 when
> FirefoxOS is at 3.4.0. What should the cadence number for the CLI be?
>
> When people think of what version Cordova is at, I figure it will be the
> version of the CLI.
>
> Cons
> - tooling dependent on X.Y.Z-A.B.C will break.
> - cadence number is historically how we make big splashes with our
> releases. Will this become more difficult?
>
> Pros
> - using SemVer properly
>
> I would propose if we do switch to SemVer only, that we start with our
> cadence value. For example, the CLI would be version 3.5.0. The cli's
> version number will increase at a much faster pace than platforms, but that
> is expected.
>
> Of course for us to get to this point, we should focus on figuring out our
> independent platform releases.
>
> Sorry for going on a tangent in your thread Mike :p
> Hi all,
>
> Recently, I've noticed that the cordova-cli is misusing the versioning
> scheme
> that is used by the phonegap-cli. It's a little confusing, but effective,
> so let
> me run through it.
>
> ---
> VERSION BREAKDOWN
> ---
>
> cordova@x.y.z-a.b.c
>
> ---
> X.Y.Z
> ---
>
> x.y.z is the version of Cordova that is bundled with the CLI. We all know
> this.
>
> ---
> A.B.C
> ---
>
> a.b.c is the package (semver) version of the cordova-cli node library.
> Imagine
> that the cordova-cli could support any version of Cordova, then a.b.c would
> be
> the sole version used by the npm package; similar to any other npm package.
>
> This version should always go up.
>
> ---
> PROBLEM
> ---
>
> The problem is that the cordova-cli is resetting a.b.c each time it
> increments
> x.y.z. For projects that use the node interface of the cordova-cli, this is
> a
> problem.
>
> a.b.c describes changes to the node programmatic interface, just like
> any other good node project published to npm. By resetting it, we confuse
> and hurt developers who depend on the API because they don't know what
> has changed in the node API.
>
> ---
> BAD EXAMPLE (HOW IT IS TODAY)
> ---
>
> cordova@3.1.0-0.1.0 - first release
> cordova@3.1.0-0.2.0 - minor node api fix
> cordova@3.2.0-0.1.0 - what!? Why did the node version reset to 0.1.0?
> cordova@3.2.0-0.2.0 - minor node api fix
> cordova@3.3.0-0.1.0 - what!? Node API users must manually discover what
> changed
>
> ---
> GOOD EXAMPLE
> ---
>
> cordova@3.1.0@0.1.0 - first release
> cordova@3.1.0@0.1.1 - patch to node package (no node api change)
> cordova@3.1.0@0.2.0 - minor to node package (backwards compatible api
> change)
> cordova@3.2.0@0.2.0 - new cordova release; no node package changes
> cordova@3.2.0@0.2.1 - patch to node package
> cordova@3.3.0@0.2.2 - new cordova release; patch to node package
> cordova@3.3.0@0.3.0 - minor to node package
> cordova@3.3.0@1.0.0 - major to node package (non-backwards compatible api
> change)
> cordova@3.4.0@1.1.0 - new cordova release; minor to node package
> cordova@3.4.0@1.1.1 - patch to node package
>
> I hope this helps to improve the cordova-cli versioning habit.
>
> Cheers!
> Michael
>
Re: [cordova-cli] Versioning Confusion
Posted by Steven Gill <st...@gmail.com>.
Thanks for the writeup Mike.
I agree that we are using it wrong. It shouldn't reset every time we change
the cadence version number. We can implement this change right away unless
people have reason not to.
I have also heard rumblings about potentially removing the cadence number
and using just SemVer. Since we are talking version numbers anyways, this
might be a good time to discuss this.
With platforms releases heading toward independent releases, our
cadence number will soon become useless. IOS could be at 3.7.0 when
FirefoxOS is at 3.4.0. What should the cadence number for the CLI be?
When people think of what version Cordova is at, I figure it will be the
version of the CLI.
Cons
- tooling dependent on X.Y.Z-A.B.C will break.
- cadence number is historically how we make big splashes with our
releases. Will this become more difficult?
Pros
- using SemVer properly
I would propose if we do switch to SemVer only, that we start with our
cadence value. For example, the CLI would be version 3.5.0. The cli's
version number will increase at a much faster pace than platforms, but that
is expected.
Of course for us to get to this point, we should focus on figuring out our
independent platform releases.
Sorry for going on a tangent in your thread Mike :p
Hi all,
Recently, I've noticed that the cordova-cli is misusing the versioning
scheme
that is used by the phonegap-cli. It's a little confusing, but effective,
so let
me run through it.
---
VERSION BREAKDOWN
---
cordova@x.y.z-a.b.c
---
X.Y.Z
---
x.y.z is the version of Cordova that is bundled with the CLI. We all know
this.
---
A.B.C
---
a.b.c is the package (semver) version of the cordova-cli node library.
Imagine
that the cordova-cli could support any version of Cordova, then a.b.c would
be
the sole version used by the npm package; similar to any other npm package.
This version should always go up.
---
PROBLEM
---
The problem is that the cordova-cli is resetting a.b.c each time it
increments
x.y.z. For projects that use the node interface of the cordova-cli, this is
a
problem.
a.b.c describes changes to the node programmatic interface, just like
any other good node project published to npm. By resetting it, we confuse
and hurt developers who depend on the API because they don't know what
has changed in the node API.
---
BAD EXAMPLE (HOW IT IS TODAY)
---
cordova@3.1.0-0.1.0 - first release
cordova@3.1.0-0.2.0 - minor node api fix
cordova@3.2.0-0.1.0 - what!? Why did the node version reset to 0.1.0?
cordova@3.2.0-0.2.0 - minor node api fix
cordova@3.3.0-0.1.0 - what!? Node API users must manually discover what
changed
---
GOOD EXAMPLE
---
cordova@3.1.0@0.1.0 - first release
cordova@3.1.0@0.1.1 - patch to node package (no node api change)
cordova@3.1.0@0.2.0 - minor to node package (backwards compatible api
change)
cordova@3.2.0@0.2.0 - new cordova release; no node package changes
cordova@3.2.0@0.2.1 - patch to node package
cordova@3.3.0@0.2.2 - new cordova release; patch to node package
cordova@3.3.0@0.3.0 - minor to node package
cordova@3.3.0@1.0.0 - major to node package (non-backwards compatible api
change)
cordova@3.4.0@1.1.0 - new cordova release; minor to node package
cordova@3.4.0@1.1.1 - patch to node package
I hope this helps to improve the cordova-cli versioning habit.
Cheers!
Michael
Re: [cordova-cli] Versioning Confusion
Posted by Michal Mocny <mm...@chromium.org>.
We've mumbled about this before here, so +1 to your proposal.
However, Andrew previously pointed out that even if we stop doing a.b.c
reset with releases, the form x.y.z-a.b.c is not valid semver and so isn't
generally useful anyway. At least not for package.json fuzzy dependency
versioning.
I notice that your list of good examples, you change the scheme to
x.y.z@a.b.c (note the @), does that resolve the issue? Clever.
-Michal
On Thu, Apr 10, 2014 at 2:00 PM, Michael Brooks <mi...@michaelbrooks.ca>wrote:
> Hi all,
>
> Recently, I've noticed that the cordova-cli is misusing the versioning
> scheme
> that is used by the phonegap-cli. It's a little confusing, but effective,
> so let
> me run through it.
>
> ---
> VERSION BREAKDOWN
> ---
>
> cordova@x.y.z-a.b.c
>
> ---
> X.Y.Z
> ---
>
> x.y.z is the version of Cordova that is bundled with the CLI. We all know
> this.
>
> ---
> A.B.C
> ---
>
> a.b.c is the package (semver) version of the cordova-cli node library.
> Imagine
> that the cordova-cli could support any version of Cordova, then a.b.c would
> be
> the sole version used by the npm package; similar to any other npm package.
>
> This version should always go up.
>
> ---
> PROBLEM
> ---
>
> The problem is that the cordova-cli is resetting a.b.c each time it
> increments
> x.y.z. For projects that use the node interface of the cordova-cli, this is
> a
> problem.
>
> a.b.c describes changes to the node programmatic interface, just like
> any other good node project published to npm. By resetting it, we confuse
> and hurt developers who depend on the API because they don't know what
> has changed in the node API.
>
> ---
> BAD EXAMPLE (HOW IT IS TODAY)
> ---
>
> cordova@3.1.0-0.1.0 - first release
> cordova@3.1.0-0.2.0 - minor node api fix
> cordova@3.2.0-0.1.0 - what!? Why did the node version reset to 0.1.0?
> cordova@3.2.0-0.2.0 - minor node api fix
> cordova@3.3.0-0.1.0 - what!? Node API users must manually discover what
> changed
>
> ---
> GOOD EXAMPLE
> ---
>
> cordova@3.1.0@0.1.0 - first release
> cordova@3.1.0@0.1.1 - patch to node package (no node api change)
> cordova@3.1.0@0.2.0 - minor to node package (backwards compatible api
> change)
> cordova@3.2.0@0.2.0 - new cordova release; no node package changes
> cordova@3.2.0@0.2.1 - patch to node package
> cordova@3.3.0@0.2.2 - new cordova release; patch to node package
> cordova@3.3.0@0.3.0 - minor to node package
> cordova@3.3.0@1.0.0 - major to node package (non-backwards compatible api
> change)
> cordova@3.4.0@1.1.0 - new cordova release; minor to node package
> cordova@3.4.0@1.1.1 - patch to node package
>
> I hope this helps to improve the cordova-cli versioning habit.
>
> Cheers!
> Michael
>