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
