Design guidelines and SemVer

classic Classic list List threaded Threaded
9 messages Options
Reply | Threaded
Open this post in threaded view
|

Design guidelines and SemVer

Peter Ansell
On 15 February 2015 at 21:29, Benedikt Ritter <[hidden email]> wrote:
<snip>

> We like to underline, that we have no experience with the RDF
> specification. From a technical point of view we can help to develop the
> proposed API (according to our design guide lines [3]).

Hi Benedikt,

On my personal projects I tend to work from the SemVer specification
[5], which isn't oriented to Java specifically, but operates with the
same general principles.

How open is the Commons project to formally use the SemVer
specification as a dependency of the (probably much older)
specification published at [3] and expand on it to provide definitions
specific to Java.

The main reason would be that SemVer, although it has a relatively
short history, is fairly widely used across different languages and
potentially easier to recognise for outsiders.

Cheers,

Peter

>
> [1] http://markmail.org/message/mnlh64qod7cuuj56
> [2] http://markmail.org/message/wl6hpkb4nhsroro5
> [3] http://commons.apache.org/releases/versioning.html
> [4] http://markmail.org/message/ylmw7qzx23br4ver

[5] http://semver.org/

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Design guidelines and SemVer

Benedikt Ritter-4
Hello Peter

2015-02-15 22:49 GMT+01:00 Peter Ansell <[hidden email]>:

> On 15 February 2015 at 21:29, Benedikt Ritter <[hidden email]> wrote:
> <snip>
>
> > We like to underline, that we have no experience with the RDF
> > specification. From a technical point of view we can help to develop the
> > proposed API (according to our design guide lines [3]).
>
> Hi Benedikt,
>
> On my personal projects I tend to work from the SemVer specification
> [5], which isn't oriented to Java specifically, but operates with the
> same general principles.
>
> How open is the Commons project to formally use the SemVer
> specification as a dependency of the (probably much older)
> specification published at [3] and expand on it to provide definitions
> specific to Java.
>
> The main reason would be that SemVer, although it has a relatively
> short history, is fairly widely used across different languages and
> potentially easier to recognise for outsiders.
>

After looking at our docs one more time, I've come to the conclusion that
they could use some love :-)
I think what we do usually is very close to SemVer.

One thing that is special at commons is, that we chance the package name
and the maven coordinates when we break binary compatibility (= bump up the
major version number). We do this to avoid jar hell. This way two versions
of the same commons library can be in the same classpath.

Benedikt


>
> Cheers,
>
> Peter
>
> >
> > [1] http://markmail.org/message/mnlh64qod7cuuj56
> > [2] http://markmail.org/message/wl6hpkb4nhsroro5
> > [3] http://commons.apache.org/releases/versioning.html
> > [4] http://markmail.org/message/ylmw7qzx23br4ver
>
> [5] http://semver.org/
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [hidden email]
> For additional commands, e-mail: [hidden email]
>
>


--
http://people.apache.org/~britter/
http://www.systemoutprintln.de/
http://twitter.com/BenediktRitter
http://github.com/britter
Reply | Threaded
Open this post in threaded view
|

Re: Design guidelines and SemVer

sebb-2-2
On 17 February 2015 at 06:13, Benedikt Ritter <[hidden email]> wrote:

> Hello Peter
>
> 2015-02-15 22:49 GMT+01:00 Peter Ansell <[hidden email]>:
>
>> On 15 February 2015 at 21:29, Benedikt Ritter <[hidden email]> wrote:
>> <snip>
>>
>> > We like to underline, that we have no experience with the RDF
>> > specification. From a technical point of view we can help to develop the
>> > proposed API (according to our design guide lines [3]).
>>
>> Hi Benedikt,
>>
>> On my personal projects I tend to work from the SemVer specification
>> [5], which isn't oriented to Java specifically, but operates with the
>> same general principles.
>>
>> How open is the Commons project to formally use the SemVer
>> specification as a dependency of the (probably much older)
>> specification published at [3] and expand on it to provide definitions
>> specific to Java.
>>
>> The main reason would be that SemVer, although it has a relatively
>> short history, is fairly widely used across different languages and
>> potentially easier to recognise for outsiders.
>>
>
> After looking at our docs one more time, I've come to the conclusion that
> they could use some love :-)
> I think what we do usually is very close to SemVer.
>
> One thing that is special at commons is, that we chance the package name

s/chance/change/

> and the maven coordinates when we break binary compatibility (= bump up the
> major version number). We do this to avoid jar hell. This way two versions
> of the same commons library can be in the same classpath.

I hope most other projects with Maven jars do the same, particularly
ones which are libraries.
I know HttpComponents does.

> Benedikt
>
>
>>
>> Cheers,
>>
>> Peter
>>
>> >
>> > [1] http://markmail.org/message/mnlh64qod7cuuj56
>> > [2] http://markmail.org/message/wl6hpkb4nhsroro5
>> > [3] http://commons.apache.org/releases/versioning.html
>> > [4] http://markmail.org/message/ylmw7qzx23br4ver
>>
>> [5] http://semver.org/
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: [hidden email]
>> For additional commands, e-mail: [hidden email]
>>
>>
>
>
> --
> http://people.apache.org/~britter/
> http://www.systemoutprintln.de/
> http://twitter.com/BenediktRitter
> http://github.com/britter

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Design guidelines and SemVer

Peter Ansell
On 17 February 2015 at 21:48, sebb <[hidden email]> wrote:
> On 17 February 2015 at 06:13, Benedikt Ritter <[hidden email]> wrote:

<snip, sounds good>

>> and the maven coordinates when we break binary compatibility (= bump up the
>> major version number). We do this to avoid jar hell. This way two versions
>> of the same commons library can be in the same classpath.
>
> I hope most other projects with Maven jars do the same, particularly
> ones which are libraries.
> I know HttpComponents does.

I haven't noticed many projects changing their Maven coordinates when
bumping the major version number, but it is useful for those reasons,
as long as the package names inside also change.

Cheers,

Peter

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Design guidelines and SemVer

sebb-2-2
On 17 February 2015 at 22:56, Peter Ansell <[hidden email]> wrote:

> On 17 February 2015 at 21:48, sebb <[hidden email]> wrote:
>> On 17 February 2015 at 06:13, Benedikt Ritter <[hidden email]> wrote:
>
> <snip, sounds good>
>
>>> and the maven coordinates when we break binary compatibility (= bump up the
>>> major version number). We do this to avoid jar hell. This way two versions
>>> of the same commons library can be in the same classpath.
>>
>> I hope most other projects with Maven jars do the same, particularly
>> ones which are libraries.
>> I know HttpComponents does.
>
> I haven't noticed many projects changing their Maven coordinates when
> bumping the major version number, but it is useful for those reasons,
> as long as the package names inside also change.

I would hope all projects increase the major version when breaking compat.
But some may well use a major version bump to denote large increases
in functionality etc.
This is not strictly SemVer, but if the API is well designed from the
outset there may be no need to break compatibility for many years.
Minor version increments then may not reflect the functionality improvement.
Version numbers are not just technical qualifiers, they may also play
a role in how the product is perceived.

If binary compat is maintained, the package/Maven ids should remain the same.

> Cheers,
>
> Peter
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [hidden email]
> For additional commands, e-mail: [hidden email]
>

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Design guidelines and SemVer

Peter Ansell
On 18 February 2015 at 12:28, sebb <[hidden email]> wrote:

> On 17 February 2015 at 22:56, Peter Ansell <[hidden email]> wrote:
>> On 17 February 2015 at 21:48, sebb <[hidden email]> wrote:
>>> On 17 February 2015 at 06:13, Benedikt Ritter <[hidden email]> wrote:
>>
>> <snip, sounds good>
>>
>>>> and the maven coordinates when we break binary compatibility (= bump up the
>>>> major version number). We do this to avoid jar hell. This way two versions
>>>> of the same commons library can be in the same classpath.
>>>
>>> I hope most other projects with Maven jars do the same, particularly
>>> ones which are libraries.
>>> I know HttpComponents does.
>>
>> I haven't noticed many projects changing their Maven coordinates when
>> bumping the major version number, but it is useful for those reasons,
>> as long as the package names inside also change.
>
> I would hope all projects increase the major version when breaking compat.

Sorry, I should have been clearer. Even in projects that bump the
major version based on a compatibility difference, I haven't noticed
many changing their groupId or artifactId, or changing their Java
package names internally. Obviously they change the version. Changing
package names is just generally viewed as too drastic a step I think
in general, given that Java will ensure typesafety and method
availability when compiling against the new version anyway. And
therefore not needing to change the maven ids as they can't coexist on
the classpath without OSGi/etc. anyway. In the case of OSGi either
method could work given enough effort on the package wrappers part.

I am not trying to say that the system is perfect, but that is what
the general behaviour seems to be, even with people who try very hard
to follow SemVer and similar ideas.

Cheers,

Peter

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Design guidelines and SemVer

Benedikt Ritter-4
2015-02-18 5:09 GMT+01:00 Peter Ansell <[hidden email]>:

> On 18 February 2015 at 12:28, sebb <[hidden email]> wrote:
> > On 17 February 2015 at 22:56, Peter Ansell <[hidden email]>
> wrote:
> >> On 17 February 2015 at 21:48, sebb <[hidden email]> wrote:
> >>> On 17 February 2015 at 06:13, Benedikt Ritter <[hidden email]>
> wrote:
> >>
> >> <snip, sounds good>
> >>
> >>>> and the maven coordinates when we break binary compatibility (= bump
> up the
> >>>> major version number). We do this to avoid jar hell. This way two
> versions
> >>>> of the same commons library can be in the same classpath.
> >>>
> >>> I hope most other projects with Maven jars do the same, particularly
> >>> ones which are libraries.
> >>> I know HttpComponents does.
> >>
> >> I haven't noticed many projects changing their Maven coordinates when
> >> bumping the major version number, but it is useful for those reasons,
> >> as long as the package names inside also change.
> >
> > I would hope all projects increase the major version when breaking
> compat.
>
> Sorry, I should have been clearer. Even in projects that bump the
> major version based on a compatibility difference, I haven't noticed
> many changing their groupId or artifactId, or changing their Java
> package names internally. Obviously they change the version. Changing
> package names is just generally viewed as too drastic a step I think
> in general, given that Java will ensure typesafety and method
> availability when compiling against the new version anyway. And
> therefore not needing to change the maven ids as they can't coexist on
> the classpath without OSGi/etc. anyway. In the case of OSGi either
> method could work given enough effort on the package wrappers part.
>

I think it is important to take into account what kind of project we're
talking about. For a framework like spring or hibernate there is no need to
change package names and maven coords, because you won't have two different
versions of the jars in your classpath (it simply makes no sense at all).
When talking about little libraries like the one developed at commons,
things are different. It is likely that you will end up with several
conflicting versions in your classpath through transetive dependencies. So
often you can do nothing about that, because you don't own the code that
references an out dated version of, say commons lang. If we don't go all
the way and change both, maven coords and the package name, users will have
a hard time getting their applications to work.

Maybe we should elaborate about this in our versioning guide lines...

Regards,
Benedikt


>
> I am not trying to say that the system is perfect, but that is what
> the general behaviour seems to be, even with people who try very hard
> to follow SemVer and similar ideas.
>
> Cheers,
>
> Peter
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [hidden email]
> For additional commands, e-mail: [hidden email]
>
>


--
http://people.apache.org/~britter/
http://www.systemoutprintln.de/
http://twitter.com/BenediktRitter
http://github.com/britter
Reply | Threaded
Open this post in threaded view
|

Re: Design guidelines and SemVer

Stian Soiland-Reyes
Also, as changing Java package names is a drastic step, you would
think three times before introducing breaking changes at all. (or if
you do - do so with a big bang and "fix everything" :) ).

So I think this specialization looks all sensible, specially for
Apache Commons which are utility libraries that could easily be found
multiple times in different versions across dependencies.

So it would be good if the Commons versioning guideline linked to the
(now pretty well known) semantic versioning doc and was aligned with
it terminology-wise - as practically it's pretty much the same. Shall
I sketch out a draft?

On 18 February 2015 at 06:19, Benedikt Ritter <[hidden email]> wrote:

> 2015-02-18 5:09 GMT+01:00 Peter Ansell <[hidden email]>:
>
>> On 18 February 2015 at 12:28, sebb <[hidden email]> wrote:
>> > On 17 February 2015 at 22:56, Peter Ansell <[hidden email]>
>> wrote:
>> >> On 17 February 2015 at 21:48, sebb <[hidden email]> wrote:
>> >>> On 17 February 2015 at 06:13, Benedikt Ritter <[hidden email]>
>> wrote:
>> >>
>> >> <snip, sounds good>
>> >>
>> >>>> and the maven coordinates when we break binary compatibility (= bump
>> up the
>> >>>> major version number). We do this to avoid jar hell. This way two
>> versions
>> >>>> of the same commons library can be in the same classpath.
>> >>>
>> >>> I hope most other projects with Maven jars do the same, particularly
>> >>> ones which are libraries.
>> >>> I know HttpComponents does.
>> >>
>> >> I haven't noticed many projects changing their Maven coordinates when
>> >> bumping the major version number, but it is useful for those reasons,
>> >> as long as the package names inside also change.
>> >
>> > I would hope all projects increase the major version when breaking
>> compat.
>>
>> Sorry, I should have been clearer. Even in projects that bump the
>> major version based on a compatibility difference, I haven't noticed
>> many changing their groupId or artifactId, or changing their Java
>> package names internally. Obviously they change the version. Changing
>> package names is just generally viewed as too drastic a step I think
>> in general, given that Java will ensure typesafety and method
>> availability when compiling against the new version anyway. And
>> therefore not needing to change the maven ids as they can't coexist on
>> the classpath without OSGi/etc. anyway. In the case of OSGi either
>> method could work given enough effort on the package wrappers part.
>>
>
> I think it is important to take into account what kind of project we're
> talking about. For a framework like spring or hibernate there is no need to
> change package names and maven coords, because you won't have two different
> versions of the jars in your classpath (it simply makes no sense at all).
> When talking about little libraries like the one developed at commons,
> things are different. It is likely that you will end up with several
> conflicting versions in your classpath through transetive dependencies. So
> often you can do nothing about that, because you don't own the code that
> references an out dated version of, say commons lang. If we don't go all
> the way and change both, maven coords and the package name, users will have
> a hard time getting their applications to work.
>
> Maybe we should elaborate about this in our versioning guide lines...
>
> Regards,
> Benedikt
>
>
>>
>> I am not trying to say that the system is perfect, but that is what
>> the general behaviour seems to be, even with people who try very hard
>> to follow SemVer and similar ideas.
>>
>> Cheers,
>>
>> Peter
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: [hidden email]
>> For additional commands, e-mail: [hidden email]
>>
>>
>
>
> --
> http://people.apache.org/~britter/
> http://www.systemoutprintln.de/
> http://twitter.com/BenediktRitter
> http://github.com/britter



--
Stian Soiland-Reyes
Apache Taverna (incubating)
http://orcid.org/0000-0001-9842-9718

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Design guidelines and SemVer

Benedikt Ritter-4
2015-02-18 13:22 GMT+01:00 Stian Soiland-Reyes <[hidden email]>:

> Also, as changing Java package names is a drastic step, you would
> think three times before introducing breaking changes at all. (or if
> you do - do so with a big bang and "fix everything" :) ).
>
> So I think this specialization looks all sensible, specially for
> Apache Commons which are utility libraries that could easily be found
> multiple times in different versions across dependencies.
>
> So it would be good if the Commons versioning guideline linked to the
> (now pretty well known) semantic versioning doc and was aligned with
> it terminology-wise - as practically it's pretty much the same. Shall
> I sketch out a draft?
>

Sounds like a good idea to me. You can change the side directly by editing
it in svn [1]. Publishing the site is explained on our website as well [2].

Regards,
Benedikt

[1] http://svn.apache.org/repos/asf/commons/cms-site/
[2] http://commons.apache.org/site-publish.html


>
> On 18 February 2015 at 06:19, Benedikt Ritter <[hidden email]> wrote:
> > 2015-02-18 5:09 GMT+01:00 Peter Ansell <[hidden email]>:
> >
> >> On 18 February 2015 at 12:28, sebb <[hidden email]> wrote:
> >> > On 17 February 2015 at 22:56, Peter Ansell <[hidden email]>
> >> wrote:
> >> >> On 17 February 2015 at 21:48, sebb <[hidden email]> wrote:
> >> >>> On 17 February 2015 at 06:13, Benedikt Ritter <[hidden email]>
> >> wrote:
> >> >>
> >> >> <snip, sounds good>
> >> >>
> >> >>>> and the maven coordinates when we break binary compatibility (=
> bump
> >> up the
> >> >>>> major version number). We do this to avoid jar hell. This way two
> >> versions
> >> >>>> of the same commons library can be in the same classpath.
> >> >>>
> >> >>> I hope most other projects with Maven jars do the same, particularly
> >> >>> ones which are libraries.
> >> >>> I know HttpComponents does.
> >> >>
> >> >> I haven't noticed many projects changing their Maven coordinates when
> >> >> bumping the major version number, but it is useful for those reasons,
> >> >> as long as the package names inside also change.
> >> >
> >> > I would hope all projects increase the major version when breaking
> >> compat.
> >>
> >> Sorry, I should have been clearer. Even in projects that bump the
> >> major version based on a compatibility difference, I haven't noticed
> >> many changing their groupId or artifactId, or changing their Java
> >> package names internally. Obviously they change the version. Changing
> >> package names is just generally viewed as too drastic a step I think
> >> in general, given that Java will ensure typesafety and method
> >> availability when compiling against the new version anyway. And
> >> therefore not needing to change the maven ids as they can't coexist on
> >> the classpath without OSGi/etc. anyway. In the case of OSGi either
> >> method could work given enough effort on the package wrappers part.
> >>
> >
> > I think it is important to take into account what kind of project we're
> > talking about. For a framework like spring or hibernate there is no need
> to
> > change package names and maven coords, because you won't have two
> different
> > versions of the jars in your classpath (it simply makes no sense at all).
> > When talking about little libraries like the one developed at commons,
> > things are different. It is likely that you will end up with several
> > conflicting versions in your classpath through transetive dependencies.
> So
> > often you can do nothing about that, because you don't own the code that
> > references an out dated version of, say commons lang. If we don't go all
> > the way and change both, maven coords and the package name, users will
> have
> > a hard time getting their applications to work.
> >
> > Maybe we should elaborate about this in our versioning guide lines...
> >
> > Regards,
> > Benedikt
> >
> >
> >>
> >> I am not trying to say that the system is perfect, but that is what
> >> the general behaviour seems to be, even with people who try very hard
> >> to follow SemVer and similar ideas.
> >>
> >> Cheers,
> >>
> >> Peter
> >>
> >> ---------------------------------------------------------------------
> >> To unsubscribe, e-mail: [hidden email]
> >> For additional commands, e-mail: [hidden email]
> >>
> >>
> >
> >
> > --
> > http://people.apache.org/~britter/
> > http://www.systemoutprintln.de/
> > http://twitter.com/BenediktRitter
> > http://github.com/britter
>
>
>
> --
> Stian Soiland-Reyes
> Apache Taverna (incubating)
> http://orcid.org/0000-0001-9842-9718
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [hidden email]
> For additional commands, e-mail: [hidden email]
>
>


--
http://people.apache.org/~britter/
http://www.systemoutprintln.de/
http://twitter.com/BenediktRitter
http://github.com/britter