Hi Brian, I've just updated the page with your changes so hopefully all is clearer now :-) I'm thinking that the next logical evolution would be to put that section on a new "release model" (or whatever) page, along with the release train, semantic version and any other related theme that would fit in there. IIRC, we haven't those things written down except on MLs threads..
In any case, thanks for your patience + suggestions! br, juan pablo On Sun, Dec 2, 2018 at 6:29 AM Brian Burch <br...@pingtoo.com> wrote: > I am deliberately top-posting because I will try to rephrase both the > original paragraphs (quoted below and subsequently modified). I must > confess I am still not 100% sure whether I fully understand all the > wrinkles of what you intend to say! Let this be a clean start and we can > snip out the old history if any further discussion is needed... > > Here is your (our?) latest version, quoted from > https://jspwiki-wiki.apache.org/Wiki.jsp?page=NewIn2.11:- > > "JSPWiki tries to follow semantic version, meaning that, f.ex., a 2.10.0 > to 2.10.3 upgrade should be transparent (a "minor" release). However, > going from 2.10.whatever to 2.11.0 (a "major" release) means there can > be some backwards incompatible changes; again, f.ex., something like > requiring a higher Java version to run or compile JSPWiki. Those changes > should be clearly described on the appropiate NewIn.. page, so you are > able to know what to expect when upgrading. > > That said, the M# is only there to note that the release has happened in > the middle of a transition to a "major" release (from X.Y to X.Y+1), so > next M# releases could still have breaking changes (with X.Y), and still > retain the release numbering, until X.Y+1 gets released. In any case, M# > releases are as production-ready as any other JSPWiki release. This > label does not mean that these releases are incomplete, or only for the > brave, or in beta or something along those lines." > > > ... and here is my suggested rewording:- > > JSPWiki follows a semantic version identifier naming convention. A minor > release upgrade from (say) 2.10.0 to 2.10.3 ought to be be transparent. > However, a major release upgrade from (say) 2.10.3 to 2.11.0 is very > likely to break compatibility with the earlier release. This might be > something like requiring a higher release of java to compile or execute > the code. You should always refer to the appropriate "NewIn" page in > this wiki to familiarise yourself with the change as part of planning > for an upgrade to a new major release. > > That said, while a new major release is under development, it might > prove appropriate to break compatibility in some way without releasing a > new major version. In such a case, this new milestone (intermediate) > release will be given an M# identification such as 2.10.0-M1. > > M# releases are as production-ready as any other JSPWiki release, so the > label does not mean the release is incomplete, or only for the brave, or > in beta, or something along those lines. Often an M# release will change > an internal API, which will affect associated code such as plugins, or > it might alter some configuration parameters. You should check the > "NewIn" page before upgrading to an M# release, but not be concerned > about its stability. > > > Juan Pablo, you will find nearly all of your original words in my > suggested new version, along with your replies to my questions. However, > I am still a little concerned that I have failed to express the whole > set of concepts accurately. I won't be upset if you change it in any > way, or even decide to ignore it! > > I look forward to reading the latest version, and the "NewIn" page, as > well as testing the new milestone release soon. I hope to find enough > time this week to help with the pre-release evluation. > > Regards, > > Brian > > > On 1/12/18 5:27 am, Juan Pablo Santos Rodríguez wrote: > > Hi Brian, > > > > My idea is that breaking changes occur in major releases, that is X.Y and > > X.Y+1. Milestones happen in between a major release, so several M# may > > contain breaking changes, when compared to X.Y. Once X.Y+1 is reached, > > there shouldn't be more M#. > > > > As per the url, that's correct, right now yields a 404. Once the release > is > > done, it'll be populated. You can check its contents at > > https://jspwiki.apache.org/japicmp/2.11.0.M1-SNAPSHOT/ > > > > > > br, > > juan pablo > > > > El vie., 30 nov. 2018 0:52, Brian Burch <br...@pingtoo.com> escribió: > > > >> On 30/11/18 9:21 am, Juan Pablo Santos Rodríguez wrote: > >>> Hi Brian, > >>> > >>> many thanks for your comments :-) I've reworded the page following your > >>> advice, so hopefully it makes more sense now. Haven't had a lot of > sleep > >>> lately so it isn't unexpected that the text got dense.. > >>> > >>> anyway thanks again; if you see the page isn't still clear enough, > plese > >>> feel free to edit as you see fit. > >> > >> I am pleased you were not offended by my suggestions. However, I prefer > >> to leave the editorial changes to you at this late stage. I don't want > >> to break anything at this critical stage. I have two comments, neither > >> of which I know exactly how to deal with. I don't mean to tinker > >> unnecessarily, but I think this paragraph is important. > >> > >> 1. I still don't understand exactly what you are trying to say about any > >> series of M sub-releases. I get the point about each being production > >> ready, so I like the new placing of this sentence. However, are you > >> trying to say each M sub-release in a family will be externally > >> compatible (still serving page content, etc), but internal APIs are not > >> guaranteed to be identical? That would mean someone like me who needs to > >> use any plugins (i.e. development interfaces) has to be more careful of > >> an upgrade? > >> > >> ...if so, then > >> > >> 2. https://jspwiki.apache.org/japicmp/2.11.0.M1/ gives me 404 page not > >> found! > >> > >> ... which (ironic smile) makes it a little hard to peer into the murky > >> water looking for alligators! > >> > >> You and I are on different sides of the world, so you should get some > >> sleep now and I will go out in the sunshine for a walk with my friends > >> who we are visiting in Sydney. > >> > >> I'll nibble away at this paragraph over the weekend if you believe I am > >> helping to make this section clearer, but first I need to know what I am > >> trying to say - syntax is easy, semantics is a lot harder! > >> > >> Thanks, > >> > >> Brian > >> > >>> br, > >>> juan pablo > >>> > >>> On Thu, Nov 29, 2018 at 11:36 PM Brian Burch <br...@pingtoo.com> > wrote: > >>> > >>>> On 30/11/18 7:54 am, Juan Pablo Santos Rodríguez wrote: > >>>>> Hi, > >>>>> > >>>>> I've came up with > >>>> https://jspwiki-wiki.apache.org/Wiki.jsp?page=NewIn2.11 > >>>>> which will be refered on the upcoming release. It contains a "What > does > >>>>> that M# mean anyway?" section which I'd thank a lot if someone could > >>>> review > >>>>> it > >>>> > >>>> OK Juan Pablo, I will bite on your bait! > >>>> > >>>> Quoting in full.... > >>>> > >>>> "Said that, the M# is only there to note that the release has happened > >>>> in the middle of a transition to a "major" release, so next releases > >>>> could still have breaking changes and still retain the release > >>>> numbering. It does not mean the release is incomplete, only for the > >>>> brave, in beta or something along those lines. These releases should > be > >>>> as production-ready as any other JSPWiki release." > >>>> > >>>> > >>>> Sorry to pick this important paragraph apart, but you did ask for > >>>> comments!!! > >>>> > >>>> 1. The English I learnt (a very long time ago) at school taught me to > >>>> say "That said,..." rather than "Said that,.." in this particular > >>>> context. It doesn't bother me in the slightest, but perhaps you might > >>>> like to change it given my next comments are probably more worthy of a > >>>> change to the paragraph? > >>>> > >>>> 2. "It does not.." before the sentence "These Releases.." is a bit of > a > >>>> "glass half-empty" approach, rather than an upbeat "glass half full" > >>>> one. I would switch those sentences around so anyone who is reading > the > >>>> paragraph is reassured first, rather than warned. > >>>> > >>>> 3. I found the "These Releases.." sentence confusing, even though I > >>>> thought I knew what it meant. Did you mean to say "for example, > >>>> 2.11.0-M1 might (or might not) be followed by 2.11.0-M2, but backward > >>>> compatibility with 2.11.0 would be maintained across this family of > >>>> stable sub-releases (aka milestones)." I hope my version is what you > >>>> mean to say, but if you mean the opposite then it should be > highlighted > >>>> as some sort of serious warning and be accompanied with a pointer on > how > >>>> to evaluate the risk of breakage in any particular upgrade case. > >>>> > >>>> I hope my comments are helpful, because they are made by someone who > has > >>>> a long history with jspwiki and a keen interest in this new milestone > >>>> release. > >>>> > >>>>> Also, most probably I won't be able to run the vote until next > Monday, > >> so > >>>>> the release most probably will delay a few days.. :-/ > >>>> > >>>> I've been lurking on the dev list for years and recently my own > plugins > >>>> broke for no apparent reason (NOT jspwiki). Instead of fixing the > >>>> immediate problem, I intend to move my production system onto 2.11, no > >>>> matter how painful that might be to get my plugins working again. I am > >>>> not expecting to have an easy "ride" from 2.10.3-git-32. > >>>> > >>>> Take your time with M1. I for one am very grateful for all the work > you > >>>> and the team have done so far and I look forward to moving from a > clunky > >>>> "default" skin to a nice "fishy" new one! > >>>> > >>>> HTH Brian > >>>> > >>>>> best regards, > >>>>> juan pablo > >>>>> > >>>>> On Tue, Nov 27, 2018 at 3:34 PM Harry Metske <harry.met...@gmail.com > > > >>>> wrote: > >>>>> > >>>>>> sounds all good. > >>>>>> > >>>>>> thanks for all your efforts > >>>>>> > >>>>>> regards, > >>>>>> Harry > >>>>>> > >>>>>> > >>>>>> Op zo 25 nov. 2018 om 21:18 schreef Juan Pablo Santos Rodríguez < > >>>>>> juanpablo.san...@gmail.com> > >>>>>> > >>>>>>> Hi, > >>>>>>> > >>>>>>> I'd like to proceed with the vote of our next release, 2.11.0-M1, > >> next > >>>>>>> week. I've to come up with a new in 2.11 wiki page, and put in > there > >>>> what > >>>>>>> does those Msomething means and main features for this release > >> (Haddock > >>>>>> by > >>>>>>> default, new wiki pages, Java 8, new maven coordinates for jspwiki > >> jar, > >>>>>>> breaking changes, etc.). If all goes well, I'm expecting we could > >> have > >>>>>> the > >>>>>>> release out by 2/3rd of December. > >>>>>>> > >>>>>>> > >>>>>>> br, > >>>>>>> juan pablo > >>>>>>> > >>>>>> > >>>>> > >>>> > >>>> > >>> > >> > >> > > > >
