Yesterday several of us (roughly the top contributors [1] to Cockpit)
discussed removing the '0.x' from the Cockpit version number.
The plan is from here on out to just go with integer versions, starting
with version '118' following version '0.117'.
Cockpit releases weekly. Some versions of Linux distributions closely
track that weekly release. Other choose particular releases to include,
based on features and other criteria.
Cockpit now has a stable javascript API and file layout for components
[2], as well as backwards compatible transport protocol. I hope to post
more documentation about these guarantees soon.
Cheers,
Stef
[1]
https://github.com/cockpit-project/cockpit/graphs/contributors?from=2016-...
[2] http://cockpit-project.org/guide/latest/development.html

Yesterday several of us (roughly the top contributors [1] to
Cockpit)
discussed removing the '0.x' from the Cockpit version number.
The plan is from here on out to just go with integer versions, starting
with version '118' following version '0.117'.
Cockpit releases weekly. Some versions of Linux distributions closely
track that weekly release. Other choose particular releases to include,
based on features and other criteria.
Cockpit now has a stable javascript API and file layout for components
[2], as well as backwards compatible transport protocol. I hope to post
more documentation about these guarantees soon.

On 08/18/2016 02:24 AM, Stef Walter wrote:
> Yesterday several of us (roughly the top contributors [1] to Cockpit)
> discussed removing the '0.x' from the Cockpit version number.
>
> The plan is from here on out to just go with integer versions, starting
> with version '118' following version '0.117'.
>
> Cockpit releases weekly. Some versions of Linux distributions closely
> track that weekly release. Other choose particular releases to include,
> based on features and other criteria.
>
> Cockpit now has a stable javascript API and file layout for components
> [2], as well as backwards compatible transport protocol. I hope to post
> more documentation about these guarantees soon.
What about making a 1.0 release?

That's a good question. But let me turn it around. What would the
benefit of 1.0 be?
Cockpit uses continuous integration and delivery. We deliver every week,
and most of them are solid and stable. Certain Linux distributions track
the weekly updates, others pick certain releases and avoid churn for
those users.
So the numbers go up regularly. What would the benefit of having numbers
like "1.110" or "1.202" really be?
I like the systemd or CoreOS model for a project like Cockpit. Cockpit
integrates the system, updates steadily as the system changes, and isn't
a library or API.
But if you have reasons not to do that, I'd love to hear them.
Cheers,
Stef

On 18.08.2016 22:12, Josh Berkus wrote:
> On 08/18/2016 02:24 AM, Stef Walter wrote:
>> Yesterday several of us (roughly the top contributors [1] to Cockpit)
>> discussed removing the '0.x' from the Cockpit version number.
>>
>> The plan is from here on out to just go with integer versions, starting
>> with version '118' following version '0.117'.
>>
>> Cockpit releases weekly. Some versions of Linux distributions closely
>> track that weekly release. Other choose particular releases to include,
>> based on features and other criteria.
>>
>> Cockpit now has a stable javascript API and file layout for components
>> [2], as well as backwards compatible transport protocol. I hope to post
>> more documentation about these guarantees soon.
>
> What about making a 1.0 release?
That's a good question. But let me turn it around. What would the
benefit of 1.0 be?
Cockpit uses continuous integration and delivery. We deliver every week,
and most of them are solid and stable. Certain Linux distributions track
the weekly updates, others pick certain releases and avoid churn for
those users.
So the numbers go up regularly. What would the benefit of having numbers
like "1.110" or "1.202" really be?
I like the systemd or CoreOS model for a project like Cockpit. Cockpit
integrates the system, updates steadily as the system changes, and isn't
a library or API.
But if you have reasons not to do that, I'd love to hear them.

Well, one of the fundamental problems with going to a whole-integer release
number is that it basically doesn't provide you with any opportunity to change
your mind. Once you move to version 118, there's no way to revert to saying
"Man, I really wish we had a way to say that *this* release was a better one for
those distros that pick one and avoid churn". Because if you decided to go back
to a major.minor.patch style release, it's going to have to start at 119.0.0 (or
else rename the project to go back to 1.0.0, for those distros that don't have
something like epoch to deal with it).
There are other, non-technical benefits to a more traditional version scheme.
For example, there is a very human response to seeing anything move from 0.x to
1.x. The sense there is that the project has *arrived*. Furthermore, a major
version number jump provides a clear notification to tech press that it's a good
time to do a re-review and talk about it again. If you make the shift to
whole-version numbers, you'll get exactly one more of these short of sending
people out to actually talk to journalists (or writing really compelling content
for distro release announcements, but those will end up promoting the distro,
not the project).
We saw this with NetworkManager... when it finally moved to the 1.x series, all
of the major news sites immediately went back and did brand new reviews and
perceived it as finally "ready". It didn't matter that the project had been
functional and stable for years before that; the move to 1.0 provided a
significant opportunity for press and to let people see that they should come
back and give it another look. Crazily enough, the number of cargo-cult "never
use NetworkMangler(sic)" posts dropped enormously after the 1.0 release because
people came back and tried it again.
I'd actually disagree with making Cockpit 1.0 at this particular moment. I think
it has come a long way, is very stable and it is a great piece of software.
However, I also think that the optimum 1.0 point would have been when the API
and transport protocol went stable. That would have been a very clear
delineation. So my thoughts right now are that Cockpit should wait a while
longer until it's about to land some truly killer feature (maybe the Ansible
Galaxy stuff that came up at Flock?) and declare *that* a 1.0 release.

> But if you have reasons not to do that, I'd love to hear
them.
>
Well, one of the fundamental problems with going to a whole-integer release
number is that it basically doesn't provide you with any opportunity to change
your mind. Once you move to version 118, there's no way to revert to saying
"Man, I really wish we had a way to say that *this* release was a better one for
those distros that pick one and avoid churn". Because if you decided to go back
to a major.minor.patch style release, it's going to have to start at 119.0.0 (or
else rename the project to go back to 1.0.0, for those distros that don't have
something like epoch to deal with it).

The "change your mind" argument is interesting.
A related "change your mind" argument (apologize if I'm doing a straw
man), is if we didn't actually want to stay 'stable' later and say ...
"Well it turns out that we want to break everything and go to 2.0".
I haven't heard any long term contributor saying they want to keep that
door open. We don't want to do a python 3.x. Even if we did, renaming
the package names would appropriate.
In case anyone is wondering, we have avenues to track the rapid
development in the javascript and operating system space, that do not
involve the Cockpit version number. From the very fact that each part of
Cockpit is its own bundle including its own javascript dependencies ...
to the fact that the shared parts of Cockpit have been inter-operable
for many releases now.
However in a last resort, we can just go to the YEAR.N epoch for a
version number.

There are other, non-technical benefits to a more traditional version
scheme.
For example, there is a very human response to seeing anything move from 0.x to
1.x. The sense there is that the project has *arrived*. Furthermore, a major
version number jump provides a clear notification to tech press that it's a good
time to do a re-review and talk about it again. If you make the shift to
whole-version numbers, you'll get exactly one more of these short of sending
people out to actually talk to journalists (or writing really compelling content
for distro release announcements, but those will end up promoting the distro,
not the project).

Dropping the 0.x accomplishes exactly the same thing here.
In addition the non-technical to response to 1.0 is: I'll wait for 1.1
... which in our case would come out a week later :S
Cockpit is continuously developed, integrated, and delivered. We're able
to do that with aggressive upstream testing and feedback. On busy days
10,000 of instances are started to test Cockpit changes.
Out of the 50 or so releases in the past year, there's been one or two
releases in the last year that were broken in a major way.
So the goal of Cockpit is to be continuously developed, continuously
integrated, and stable. Having versions like 1.1, 1.2, 1.3, 2.x doesn't
tell that story at all.
Are those ambitious goals? Yup. But it's not an arbitrary goal. People
are already depending on the stability of Cockpit, and it would be a
total cop-out to do an incompatible 2.x later on.

We saw this with NetworkManager... when it finally moved to the 1.x
series, all
of the major news sites immediately went back and did brand new reviews and
perceived it as finally "ready". It didn't matter that the project had
been
functional and stable for years before that; the move to 1.0 provided a
significant opportunity for press and to let people see that they should come
back and give it another look. Crazily enough, the number of cargo-cult "never
use NetworkMangler(sic)" posts dropped enormously after the 1.0 release because
people came back and tried it again.
I'd actually disagree with making Cockpit 1.0 at this particular moment. I think
it has come a long way, is very stable and it is a great piece of software.
However, I also think that the optimum 1.0 point would have been when the API
and transport protocol went stable. That would have been a very clear
delineation. So my thoughts right now are that Cockpit should wait a while
longer until it's about to land some truly killer feature (maybe the Ansible
Galaxy stuff that came up at Flock?) and declare *that* a 1.0 release.

So all that said, I think this is *still* something we want to do: have
monotonously increasing version numbers.
That said, this discussion has been good. There's a few more things we
should probably do before we remove the '0.x' prefix.
* Documenting exactly what is stable and what's not.
* Providing a simple way (ie: other than packaging 'Requires') for
Cockpit components/plugins to indicate the minimum version of Cockpit
that they require.
* Representing the version numbers (Cockpit is not a single entity)
correctly in the javascript API and in the About dialog.
None of the above require breaking compatibility, but they are finishing
touches that we should have in place.
Stef

Cockpit is continuously developed, integrated, and delivered.
We're able
to do that with aggressive upstream testing and feedback. On busy days
10,000 of instances are started to test Cockpit changes.
Out of the 50 or so releases in the past year, there's been one or two
releases in the last year that were broken in a major way.
So the goal of Cockpit is to be continuously developed, continuously
integrated, and stable. Having versions like 1.1, 1.2, 1.3, 2.x doesn't
tell that story at all.

So, I'm looking at this from an advocacy perspective.
We've never had a 1.0 release. We haven't really promoted cockpit
outside of the Red Hat circle. If Cockpit is all the sudden version
118, people won't know what they're supposed to use ... and we lose an
opportunity for promoting the project to external OSS communities and users.
There's also that the other project to use whole numbers for versions,
and increase them frequently, has created a bad reputation from that
(Firefox). So many users' experience with large version numbers is
going to be negative.
I understand where you're coming from on this. However, we will pay a
price in advocacy/adoption terms if we do something unexpected with
version numbers. It means that we spend time explaining our version
numbers to people instead of explaining Cockpit.
--
--
Josh Berkus
Project Atomic
Red Hat OSAS

Stef,
> Cockpit is continuously developed, integrated, and delivered. We're able
> to do that with aggressive upstream testing and feedback. On busy days
> 10,000 of instances are started to test Cockpit changes.
>
> Out of the 50 or so releases in the past year, there's been one or two
> releases in the last year that were broken in a major way.
>
> So the goal of Cockpit is to be continuously developed, continuously
> integrated, and stable. Having versions like 1.1, 1.2, 1.3, 2.x doesn't
> tell that story at all.
So, I'm looking at this from an advocacy perspective.

There's also that the other project to use whole numbers for
versions,
and increase them frequently, has created a bad reputation from that
(Firefox). So many users' experience with large version numbers is
going to be negative.

Firefox is a *great* example of what we're trying to achieve here.
Ambitious as it were ... some points:
1. First of all I use "Firefox" and expect it to be updated regularly
... I don't use "Firefox 3.8" ... ditto for Chrome.
This is the same experience we want. Admins can use port 9090 to
access an interface with the specific capabilities of that server.
The version number of Cockpit itself is secondary and a diagnostic
tool for when things don't function as expected..
2. Firefox won't get to say: "Oh we now have version 2.x which breaks
all the (web) apps you've written so far. Too bad." That's the same
goal we'd like to have for Cockpit's functionality and plugins.
As time goes on grow, there will be functionality added, and other
parts deprecated or removed. There are independent protocol and
javascript API versioning mechanisms in place in Cockpit to account
for this.
But a major break to (python) 3.x just isn't part of the plan.
3. Various parts of Cockpit can have different version numbers and
work together. Just like parts of GNOME, or parts of Fedora (think
modularity cough) have different version numbers.
4. Cockpit has stable releases weekly. Not all users are forced to cycle
through each one ... but this dilutes semantic versioning advantages
significantly.
I do understand and respect the traditional "1.0" approach to software,
but it's hard to make it work or apply in this case.

I understand where you're coming from on this. However, we will
pay a
price in advocacy/adoption terms if we do something unexpected with
version numbers. It means that we spend time explaining our version
numbers to people instead of explaining Cockpit.

The idea is not to explain version numbers at all. But rather "just use
Cockpit". Cockpit version numbers are a diagnostic tool for when things
don't behave as expected.
In fact we've added some finishing touches on the diagnostic aspects of
version numbers here:
1. https://github.com/cockpit-project/cockpit/pull/4964
2. And we'll probably put a bit of effort into the about dialog to
show the various versions of the parts in play when it comes to
diagnosing an issue.
3. Lastly we'll better document what's "stable" and what's
"internal"
before making this move.
This discussion has resulted in some good checks and forethought, but
all in all, even after taking the discussion into account, the
significant contributors to Cockpit have been in support of simply
dropping the '0.x'.
Stef

On 22.08.2016 18:25, Josh Berkus wrote:
> Stef,
>
>> Cockpit is continuously developed, integrated, and delivered. We're able
>> to do that with aggressive upstream testing and feedback. On busy days
>> 10,000 of instances are started to test Cockpit changes.
>>
>> Out of the 50 or so releases in the past year, there's been one or two
>> releases in the last year that were broken in a major way.
>>
>> So the goal of Cockpit is to be continuously developed, continuously
>> integrated, and stable. Having versions like 1.1, 1.2, 1.3, 2.x doesn't
>> tell that story at all.
>
> So, I'm looking at this from an advocacy perspective.
We had more discussion about this today in our IRC meeting.
> We've never had a 1.0 release. We haven't really promoted cockpit
> outside of the Red Hat circle.
That has indeed been a sore point. We discussed how to help Cockpit into
Ubuntu's repositories as a concrete step forward.
> If Cockpit is all the sudden version
> 118, people won't know what they're supposed to use ... and we lose an
> opportunity for promoting the project to external OSS communities and users.
We can promote the fact that it's no longer 0.x and has stable API,
plug-ability and so on.
> There's also that the other project to use whole numbers for versions,
> and increase them frequently, has created a bad reputation from that
> (Firefox). So many users' experience with large version numbers is
> going to be negative.
Firefox is a *great* example of what we're trying to achieve here.
Ambitious as it were ... some points:
1. First of all I use "Firefox" and expect it to be updated regularly
... I don't use "Firefox 3.8" ... ditto for Chrome.
This is the same experience we want. Admins can use port 9090 to
access an interface with the specific capabilities of that server.
The version number of Cockpit itself is secondary and a diagnostic
tool for when things don't function as expected..

That said, I don't disagree that this is what we want. But the version number
even today is basically invisible to the *user*. It is interesting primarily to
the administrator of the system (and even then, only insofar as it matches up to
the feature announcement including the thing they wanted to see added).
I'd claim that this part of the argument is *irrelevant* to the discussion,
because the exact nature of the version number doesn't matter as long as it is
an index to a set of features (meaning that changing it from 0.x to something
else would result in exactly zero change in this experience).

2. Firefox won't get to say: "Oh we now have version 2.x
which breaks
all the (web) apps you've written so far. Too bad." That's the same
goal we'd like to have for Cockpit's functionality and plugins.

Actually, they've done *exactly* this with the change in plugin and extension
APIs in Firefox between releases and it has caused *enormous* headaches for many
people (for example, it completely broke FreeIPA's autoconfiguration plugin,
making it much harder to configure a client). There are plenty of other examples
of good extensions that suddenly got broken with basically no advance knowledge
of the user. Of course, then the user goes and complains to the extension writer
instead...
From the perspective of the user, versions like this are "minor updates" and
when things break in a minor update, they get very angry.

As time goes on grow, there will be functionality added, and
other
parts deprecated or removed. There are independent protocol and
javascript API versioning mechanisms in place in Cockpit to account
for this.
But a major break to (python) 3.x just isn't part of the plan.

Right, but the best laid plans of mice and men oft go awry...
Consider the possibility that there might come a time when Cockpit would go HTTP
2.0-only, for example. That *would* mean a backwards-incompatible break with any
browser that only supported HTTP 1.1 (for example).
Or consider a day in the future where JavaScript is no longer the gold standard
in browser scripting and you perform a major rewrite.
I will grant you that these are exceptional circumstances... but not impossible
ones (and I'm sure there are others not immediately coming to mind). Version
numbers *do* provide a simple, programmatic way of indicating to other software
that they may need to change to adapt to the new thing (without the maintainer
of that software needing to actively be monitoring release announcements of
Cockpit).

3. Various parts of Cockpit can have different version numbers and
work together. Just like parts of GNOME, or parts of Fedora (think
modularity cough) have different version numbers.

Sure, but the overall project should have a version number that is
representative of the whole system. With semantic versioning, you can actually
use this as a shorthand to express which portions of the project are stable vs.
in-development or experimental, simply by setting the Major version to 0.
So you might have Cockpit 1.2.0 that contains:
cockpit-bridge = 1.2.0
cockpit-selinux= 0.56.0
They could be released as the 1.2.0 set but a conservative deployment could
easily have tools that would skip installing 0.x portions of it.

4. Cockpit has stable releases weekly. Not all users are forced to
cycle
through each one ... but this dilutes semantic versioning advantages
significantly.
I do understand and respect the traditional "1.0" approach to software,
but it's hard to make it work or apply in this case.

I'm not sure in what way it dilutes the semantic versioning at all. I think you
skipped to a conclusion without presenting the evidence there.
As I mentioned above, if we version components independently, we can use semver
to indicate stability. For the stable components, we increment the Minor release
each week until we hit a case where something that was deprecated is removed, at
which point we bump the major number for that component and the project as a
whole and continue.
The way I see it working is that the individual components would see their own
updates following semver and we would just use the highest-versioned of any of
them as the overall project version (since that would guarantee that
compatibility changes were propagated).

> I understand where you're coming from on this. However, we
will pay a
> price in advocacy/adoption terms if we do something unexpected with
> version numbers. It means that we spend time explaining our version
> numbers to people instead of explaining Cockpit.
The idea is not to explain version numbers at all. But rather "just use
Cockpit". Cockpit version numbers are a diagnostic tool for when things
don't behave as expected.

Forgive my bluntness, but that's naive. It works *kind of* for Firefox because
the majority of users don't have specific feature requests; they just want to
browse cat videos. However, for the set of users for which specific features
matter (usually either extension writers or integration engineers for major
sites like Netflix), this versioning scheme *is* problematic because they don't
have any inherent clues when their stuff is going to stop working and their
users will be upset. They are forced to either use humans to monitor the project
changes (which is costly) or take their chances and try to fix things fast when
they break (which has problems with user perception and also means their
sustaining engineers are overworked and stressed).
Cockpit is very specifically addressing a different audience than Firefox: it's
addressing the administrator of a complex system. This is a class of user that
*does* have specific feature needs and *will* notice when things stop working
(and will be very noisy about it).
(As an aside, it's also a class of people that are largely in opposition to the
idea of constant new features and prefer LTS support for existing features as
well, but let's talk about that in a different thread.)

In fact we've added some finishing touches on the diagnostic
aspects of
version numbers here:
1. https://github.com/cockpit-project/cockpit/pull/4964
2. And we'll probably put a bit of effort into the about dialog to
show the various versions of the parts in play when it comes to
diagnosing an issue.
3. Lastly we'll better document what's "stable" and what's
"internal"
before making this move.
This discussion has resulted in some good checks and forethought, but
all in all, even after taking the discussion into account, the
significant contributors to Cockpit have been in support of simply
dropping the '0.x'.

I'm a little surprised that the conversation has focused so heavily on the
Firefox and Chrome decision to go to rapid major versions rather than picking
systemd which is a much closer analog to Cockpit; it's system software whose
feature set is highly relevant to administrators. I don't have any information
to share specifically right now, but I'd suggest that it might be useful to do
at least a straw poll of real users and get their opinion on whether that
versioning scheme works for them, irritates them or is irrelevant to them. That
would be a much better guidepost for Cockpit I think than looking at the
common-user case of the browsers.

Yeah, and we couldn't really figure out what the criteria for a 1.0
release would be.
A stable API would be one, but few people should care about the Cockpit
plugin API.
Being bug free enough to let people use it for real on real systems
would be another, but we have achieved that some time ago already, IMO.
I am very happy with the simple integer versions, precisely because they
don't have any meaning, so there is less to discuss... hopefully. :-)

So all that said, I think this is *still* something we want to do:
have
monotonously increasing version numbers.

OK.
There's one other technical issue: how to handle bugfixes and security
updates?
One of the issues with "whole number" releases is that distros are
likely to include a specific version. We'll need some way for packagers
to pull in things like security updates, and the way packaging systems
-- including containers -- work, that expects some kind of major/minor
version number.
I realize that's not how Cockpit releases work, but we need an answer
which will be acceptable to packagers.
--
--
Josh Berkus
Project Atomic
Red Hat OSAS

On 08/22/2016 08:11 AM, Stef Walter wrote:
> So all that said, I think this is *still* something we want to do: have
> monotonously increasing version numbers.
OK.
There's one other technical issue: how to handle bugfixes and security
updates?
One of the issues with "whole number" releases is that distros are
likely to include a specific version. We'll need some way for packagers
to pull in things like security updates, and the way packaging systems
-- including containers -- work, that expects some kind of major/minor
version number.
I realize that's not how Cockpit releases work, but we need an answer
which will be acceptable to packagers.

The usual mechanism of package revisions would be in play here.
For example, lets look at system in Fedora:
229 == is an upstream version
229-13 == is a downstream in Fedora 24 (bugfixes, security fixes)
Or systemd in Debian:
231 == is an upstream version
231-4 == is a downstream in Debian unstable (bugfixes, etc.)
Hope that makes sense.
Cheers,
Stef