[DISCUSS] rewording versioning proposal?

[Juan Pablo Santos Rodríguez <ju...@gmail.com>]

Hi,

the recent thread on the public api made me question how do we version
different releases, based on what kind of changes to expect from them.

https://jspwiki-wiki.apache.org/Wiki.jsp?page=VersioningProposal contains
the current proposal for JSPWiki versioning. It states:

"""
As of JSPWiki entering Apache, we'll adopt the following versioning system:

major.minor.revision[-identifier-build]

Where

* major = Major release, which breaks compatibility (binary or source) with
previous versions.
* minor = Update with new major functionality which maybe breaks downwards
compatibility.
* revision = Bug fixes or minor functionality updates. Forward and backward
compatibility within the same major.minor revision is retained.
[...]
"""

I'd like to rephrase the first two points to:

* major = Major release, which breaks compatibility (binary or source) with
previous versions on the public API.
* minor = Update with new major functionality, which breaks compatibility
(binary or source) with previous versions on any place except the public
API.

Public API would still have to be defined (=don't want to tie this thread
to the public api one):
- either what is ongoing on the o.a.w.api package
- or the classes / interfaces needed to develop custom plugins / filters /
page providers
- or whatever we see fit

The reasoning behind this change is that current wording makes the
difference between major and minor (a bit) blurry: any backward
incompatible
change could fit either major or minor versioning. The suggested rewording
pursues to clearly differentiate when to increase each number:
* major: *All* custom plugins / filters / page providers will need some
work to run on the new version, be it reimporting a class or completely
rewritting them.
* minor: there are backwards incompatible changes, which *may* be
translated on *some* plugins / filters / page providers, but generally
speaking they should work, or at least they'll be loaded by JSPWiki.
* revision: *All* custom plugins / filters / page providers will continue
to work at this level.

thoughts? makes sense? is it clear as it is, and doesn't need further
editing?


thanks in advance,
juan pablo

Re: [DISCUSS] rewording versioning proposal?

[Murray Altheim <mu...@altheim.com>]

Juan Pablo wrote:
> I've just sent another mail on how to tackle the backward compatibility
> issue under the public api thread, so I'll skip
> that here. I understand the rewording is fine with you (whether we end up
> breaking backwards compatibility or not)?

I'd prefer that we not break backwards compatibility if at all possible, as
previously discussed, so no, I was speaking of the appropriateness of the
rewording, which I entirely agree with as necessary for such a big change.

I'll respond to the details in the other thread.

> Do you find it specificies more clearly what to expect with each type of
> release?

Yes, thank you.

> If there are no objections, I'd like to update the versioning proposal
> somewhere near next Friday..

Thanks as always for your very hard work.

Cheers,

Murray

...........................................................................
Murray Altheim <murray18 at altheim dot com>                       = =  ===
http://www.altheim.com/murray/                                     ===  ===
                                                                   = =  ===
     In the evening
     The rice leaves in the garden
     Rustle in the autumn wind
     That blows through my reed hut.
            -- Minamoto no Tsunenobu

Re: [DISCUSS] rewording versioning proposal?

[Juan Pablo Santos Rodríguez <ju...@gmail.com>]

Hi Murray,

I've just sent another mail on how to tackle the backward compatibility
issue under the public api thread, so I'll skip
that here. I understand the rewording is fine with you (whether we end up
breaking backwards compatibility or not)?
Do you find it specificies more clearly what to expect with each type of
release?

If there are no objections, I'd like to update the versioning proposal
somewhere near next Friday..


thx in advance,
juan pablo

On Sun, Mar 8, 2020 at 5:58 AM Murray Altheim <mu...@altheim.com> wrote:

> Hi Juan Pablo,
>
> I appreciate your effort at clarifying the versioning of the public API,
> and sympathize with the situation the project is in. And thanks for your
> long reply to Jurgen, that was enlightening.
>
> I do think it important to point out that JSPWiki is somewhat different
> to a lot of other Apache projects, which are often software libraries,
> where usage is by developers who (hopefully) have the resources to
> perform proper upgrades and generally already understand the exigencies
> of major-minor versions and what that means. I'm not against the
> versioning idea; it's probably a good thing to consider that the public
> API proposal would be part of a major version change and therefore would
> likely break backward compatibility.
>
> But this is where I would once again point out that JSPWiki is actually
> rather different than most other Apache libraries in that the users are
> not developers but site administrators, i.e., end users. And wherever
> someone has hired a contractor to create a custom plugin, or done so for
> themselves, being able to upgrade to the next version of JSPWiki is still
> extremely important, particularly as regards security patches, etc.  In
> several of my jobs over the last few years I might note that despite the
> employers being large government agencies there have been a number of
> projects that are struggling to migrate from Java 7 to Java 8, and the
> resources to jump to a current version simply don't exist. This despite
> the management knowing the security implications of using obsolete
> versions,
> and despite their products getting plenty of new feature releases.
> Upgrading
> a wiki in these situations would be an extremely low priority. One of them
> just upgraded Confluence, but not to the most recent version as that would
> have broken compatibility with other systems tied to older software.
>
> So even if the public API is part of a major version change, I'll go back
> to my original point: "There are likely a lot of private plugins developed
> for personal or professional sites (that we never hear about) whose
> developers are either too busy or otherwise unavailable for updating them,
> and it'd be a shame to force those sites to either abandon what might be
> essential plugins or never upgrade."
>
> I don't think we want to create islands of JSPWiki installations that
> can't be upgraded. If the public API proposal goes ahead I would again
> advocate that we include an adapter or facade package that permits the
> existing plugins to still function, if that's at all possible. If the
> public API is truly just a public API and doesn't make functional changes,
> then this shouldn't be too difficult, basically "fake" classes using the
> old names with casts to the new classes.
>
> I agree with Jürgen in that JSPWiki is suitable for hacking. A public API
> would (at least in theory) actually make that easier, and writing plugins
> easier. I'm one who would like to be able to write to a cleaner interface
> that JSPWiki's current one, which has developed organically over many,
> many years. So yes, the public API is a very good idea, and perhaps long
> overdue, but I don't want to leave our users behind either.
>
> Cheers,
>
> Murray
>
> On 8/03/20 1:01 PM, Juan Pablo Santos Rodríguez wrote:
> > Hi,
> >
> > the recent thread on the public api made me question how do we version
> > different releases, based on what kind of changes to expect from them.
> >
> > https://jspwiki-wiki.apache.org/Wiki.jsp?page=VersioningProposal
> contains
> > the current proposal for JSPWiki versioning. It states:
> >
> > """
> > As of JSPWiki entering Apache, we'll adopt the following versioning
> system:
> >
> > major.minor.revision[-identifier-build]
> >
> > Where
> >
> > * major = Major release, which breaks compatibility (binary or source)
> with
> > previous versions.
> > * minor = Update with new major functionality which maybe breaks
> downwards
> > compatibility.
> > * revision = Bug fixes or minor functionality updates. Forward and
> backward
> > compatibility within the same major.minor revision is retained.
> > [...]
> > """
> >
> > I'd like to rephrase the first two points to:
> >
> > * major = Major release, which breaks compatibility (binary or source)
> with
> > previous versions on the public API.
> > * minor = Update with new major functionality, which breaks compatibility
> > (binary or source) with previous versions on any place except the public
> > API.
> >
> > Public API would still have to be defined (=don't want to tie this thread
> > to the public api one):
> > - either what is ongoing on the o.a.w.api package
> > - or the classes / interfaces needed to develop custom plugins / filters
> /
> > page providers
> > - or whatever we see fit
> >
> > The reasoning behind this change is that current wording makes the
> > difference between major and minor (a bit) blurry: any backward
> > incompatible
> > change could fit either major or minor versioning. The suggested
> rewording
> > pursues to clearly differentiate when to increase each number:
> > * major: *All* custom plugins / filters / page providers will need some
> > work to run on the new version, be it reimporting a class or completely
> > rewritting them.
> > * minor: there are backwards incompatible changes, which *may* be
> > translated on *some* plugins / filters / page providers, but generally
> > speaking they should work, or at least they'll be loaded by JSPWiki.
> > * revision: *All* custom plugins / filters / page providers will continue
> > to work at this level.
> >
> > thoughts? makes sense? is it clear as it is, and doesn't need further
> > editing?
> >
> >
> > thanks in advance,
> > juan pablo
> >
>
> --
>
> ...........................................................................
> Murray Altheim <murray18 at altheim dot com>                       = =  ===
> http://www.altheim.com/murray/                                     ===
> ===
>                                                                     = =
> ===
>      In the evening
>      The rice leaves in the garden
>      Rustle in the autumn wind
>      That blows through my reed hut.
>             -- Minamoto no Tsunenobu
>
>

Re: [DISCUSS] rewording versioning proposal?

[Murray Altheim <mu...@altheim.com>]

Hi Juan Pablo,

I appreciate your effort at clarifying the versioning of the public API,
and sympathize with the situation the project is in. And thanks for your
long reply to Jurgen, that was enlightening.

I do think it important to point out that JSPWiki is somewhat different
to a lot of other Apache projects, which are often software libraries,
where usage is by developers who (hopefully) have the resources to
perform proper upgrades and generally already understand the exigencies
of major-minor versions and what that means. I'm not against the
versioning idea; it's probably a good thing to consider that the public
API proposal would be part of a major version change and therefore would
likely break backward compatibility.

But this is where I would once again point out that JSPWiki is actually
rather different than most other Apache libraries in that the users are
not developers but site administrators, i.e., end users. And wherever
someone has hired a contractor to create a custom plugin, or done so for
themselves, being able to upgrade to the next version of JSPWiki is still
extremely important, particularly as regards security patches, etc.  In
several of my jobs over the last few years I might note that despite the
employers being large government agencies there have been a number of
projects that are struggling to migrate from Java 7 to Java 8, and the
resources to jump to a current version simply don't exist. This despite
the management knowing the security implications of using obsolete versions,
and despite their products getting plenty of new feature releases. Upgrading
a wiki in these situations would be an extremely low priority. One of them
just upgraded Confluence, but not to the most recent version as that would
have broken compatibility with other systems tied to older software.

So even if the public API is part of a major version change, I'll go back
to my original point: "There are likely a lot of private plugins developed
for personal or professional sites (that we never hear about) whose
developers are either too busy or otherwise unavailable for updating them,
and it'd be a shame to force those sites to either abandon what might be
essential plugins or never upgrade."

I don't think we want to create islands of JSPWiki installations that
can't be upgraded. If the public API proposal goes ahead I would again
advocate that we include an adapter or facade package that permits the
existing plugins to still function, if that's at all possible. If the
public API is truly just a public API and doesn't make functional changes,
then this shouldn't be too difficult, basically "fake" classes using the
old names with casts to the new classes.

I agree with Jürgen in that JSPWiki is suitable for hacking. A public API
would (at least in theory) actually make that easier, and writing plugins
easier. I'm one who would like to be able to write to a cleaner interface
that JSPWiki's current one, which has developed organically over many,
many years. So yes, the public API is a very good idea, and perhaps long
overdue, but I don't want to leave our users behind either.

Cheers,

Murray

On 8/03/20 1:01 PM, Juan Pablo Santos Rodríguez wrote:
> Hi,
> 
> the recent thread on the public api made me question how do we version
> different releases, based on what kind of changes to expect from them.
> 
> https://jspwiki-wiki.apache.org/Wiki.jsp?page=VersioningProposal contains
> the current proposal for JSPWiki versioning. It states:
> 
> """
> As of JSPWiki entering Apache, we'll adopt the following versioning system:
> 
> major.minor.revision[-identifier-build]
> 
> Where
> 
> * major = Major release, which breaks compatibility (binary or source) with
> previous versions.
> * minor = Update with new major functionality which maybe breaks downwards
> compatibility.
> * revision = Bug fixes or minor functionality updates. Forward and backward
> compatibility within the same major.minor revision is retained.
> [...]
> """
> 
> I'd like to rephrase the first two points to:
> 
> * major = Major release, which breaks compatibility (binary or source) with
> previous versions on the public API.
> * minor = Update with new major functionality, which breaks compatibility
> (binary or source) with previous versions on any place except the public
> API.
> 
> Public API would still have to be defined (=don't want to tie this thread
> to the public api one):
> - either what is ongoing on the o.a.w.api package
> - or the classes / interfaces needed to develop custom plugins / filters /
> page providers
> - or whatever we see fit
> 
> The reasoning behind this change is that current wording makes the
> difference between major and minor (a bit) blurry: any backward
> incompatible
> change could fit either major or minor versioning. The suggested rewording
> pursues to clearly differentiate when to increase each number:
> * major: *All* custom plugins / filters / page providers will need some
> work to run on the new version, be it reimporting a class or completely
> rewritting them.
> * minor: there are backwards incompatible changes, which *may* be
> translated on *some* plugins / filters / page providers, but generally
> speaking they should work, or at least they'll be loaded by JSPWiki.
> * revision: *All* custom plugins / filters / page providers will continue
> to work at this level.
> 
> thoughts? makes sense? is it clear as it is, and doesn't need further
> editing?
> 
> 
> thanks in advance,
> juan pablo
> 

-- 

...........................................................................
Murray Altheim <murray18 at altheim dot com>                       = =  ===
http://www.altheim.com/murray/                                     ===  ===
                                                                    = =  ===
     In the evening
     The rice leaves in the garden
     Rustle in the autumn wind
     That blows through my reed hut.
            -- Minamoto no Tsunenobu