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 <murra...@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 > >
