Hi, Another problem with automatic is that we don`t always tag affects-version on the actual version when it was introduced, but the version we actually tested with. This might lead to displaying blockers on the release notes of versions that were not responsible with introducing the actual problem. Until now, we haven`t had that many cases and the 7.2, 7.3 releases could be considered (from my POV) exceptions which had multiple issues due to the nature/complexity of the changes they introduced. So, in the end, I believe I`m +1 to stick to manual. Thanks, Eduard On Fri, Nov 13, 2015 at 7:00 PM, vincent(a)massol.net <vincent(a)massol.net> wrote:

I am +1 to keep doing what we have been doing so far, which is, on a case-by-case basis and depending on the importance of the blocker, to manually add a notice (/error macro) in the release notes, informing users. If we want to document this as a best practice, I`m ok with it. I`m not a fan of increasing maintainance/work load in this aspect, but that`s just my opinion. Thanks, Eduard On Fri, Nov 13, 2015 at 8:21 PM, vincent(a)massol.net <vincent(a)massol.net> wrote:

On Fri, Nov 13, 2015 at 9:48 PM, vincent(a)massol.net <vincent(a)massol.net> wrote: I can only speak for myself, but I do as well. Now it depends of the nature of the blocker. All regression are blockers, but the regression could still be minor and not so annoying for most users. In that case, I do not. Up to now, what we put at the top in error box were blocker that we think make the release unrecommended for most users. And IMO, we should continue doing this manually at least. We already add know issue we know about to the RN, so adding blockers at the top is not really adding them to the RN, but making them more visible. This could be a good idea but not in replacement to our current practice, since it is less understandable, and more common then our current practice, making the information less meaningful for users. This could even cause more confusion, if those blocker are minor regression on specific areas. This is not so true, blocker means we don’t want this in the next release, and as I said, it is generally true for any regression. But the actual blocker could have several level of importance for different kind of user, and in the end only affect very few of them but so hardly that it is still blocker. If you look at your sample, I am even afraid by what users will understand of them. Either they will be afraid so much, that they will not upgrade, or they will not understand and consider they are not affected. See XWIKI-12502, XWIKI-12342, XWIKI-12251, what users will think of them ? And on the other side, XWIKI-12218, while we want it in the next release, was it really so blocker for end users ? In your example above, those that could be interesting and understandable warnings for some users are XWIKI-12612, XWIKI-12160 and XWIKI-11993. So listing them in red at the very top may be too much, or confusing IMO. This does not mean the the could not list them somewhere in the RN, maybe in a {{warning}} macro, below the possible {{error}} we do manually. This could also help us think about doing a red one, when looking at the RN. What afraid me in the end, is that we do less blockers just because we know they will appear in RN and they are so technical that nobody will get it. So the next question is, does all of them represent what you wanted at the top, compare to other issues ? Is those blocker more significant ? Should we change the way we use blocker ? I am not sure we should change anything in our current usage of blocker, we may want to have them enhanced in RN, but it does not mean all the information will be so significant. Thanks, -- Denis Gervalle SOFTEC sa - CEO

On Sun, Nov 15, 2015 at 1:02 PM, vincent(a)massol.net <vincent(a)massol.net> wrote: * Proposal 2 (Denis, Edy): This is what we do now. Continue doing this I do not know for Edy, but for the above definition does not really translate what I have said so far ! What I said, is that we cannot simply list blockers at the top to replace the actual manual warnings because JIRA tickets are often unintelligible for end users, and that all blockers (as we used to do them so far) are not at the same level, and does not necessarily need to be enhanced at the same level. That if we go that way, it means we need to rethink the way we use blocker in JIRA, and that I do not believe we should. If this is really intelligible from the simple JIRA title, I would be +1, but I doubt we can really achieve that. Again, I am not sure this is so simple. Marking issue as blocker is promising issues to be fixed for the release, and if this does not really happen, be sure we care a lot about them, and not simply push them to the next release without an agreement. This does not necessarily means that the issue affect a large amount of users, and that it is so important that it should prevent many users to try that release. As I have explained earlier, if we do not change our current usage of blocker (and I like this idea), and if I look at your auto-generated list of blockers, many of them are unintelligible for the end users, and I do not see what would be the benefit to list them, all it will do, is make users confused or scared. So, the manual decision is difficult to avoid. Maybe we could use a manual tag to exclude (or include) some blocker from the list, meaning that we would go for a show them by default (or explicitly), and we have a way to explicitly make them not listed (or listed) while we still consider them for the next release. But, I am not sure this is fine, since anyone (not just committers) could create a blocker JIRA, and cause a change of the RN… is this acceptable to list unconfirmed blockers ? I do not know exactly what happened on Friday, but I would say that like any manual process, we cannot be fully error safe, but I am sure all of us will do their best to ensure we care about this in the future. Don’t you trust we could do that ? -- Denis Gervalle SOFTEC sa - CEO

I see there’s been no reply to this last email. Are we all ok for this last proposal? Thanks -Vincent On 16 Nov 2015 at 08:43:30, vincent(a)massol.net (vincent@massol.net(mailto:vincent@massol.net)) wrote:

+1 Thanks, Eduard On Thu, Dec 31, 2015 at 10:00 AM, Thomas Mortagne <thomas.mortagne(a)xwiki.com > ok to continue what we were doing > > On Wed, Dec 30, 2015 at 5:16 PM, vincent(a)massol.net <vincent(a)massol.net> > > I see there’s been no reply to this last email. > > > > Are we all ok for this last proposal? > > > > Thanks > > -Vincent > > > > > > On 16 Nov 2015 at 08:43:30, vincent(a)massol.net (vincent(a)massol.net > (mailto:vincent@massol.net)) wrote: > > > >> Ok. I propose that we simply agree on this best practice for now and we > try it without any automation and see how it goes: > >> > >> > >> Proposal text to add to our best practices on xwiki.org: > >> > >> " > >> When someone reports or notices a blocker issue that will affect end > users in a serious way (the definition of “serious” is left to the > discretion of everyone), he should add it in the error block at the top of > the release notes in which the issue exists. > >> > >> The error block should have the following format: > >> > >> {{error}} > >> The following important issues were found after this version was > released. You should verify if you’re using or need the affected features > and decide whether to use a newer version that has it fixed or continue > with this release: > >> > >> * > >> * … > >> * > >> {{/error}} > >> " > >> > >> > >> Thanks > >> -Vincent > >> > >> > >> On 16 Nov 2015 at 02:08:00, Denis Gervalle (dgl(a)softec.lu) wrote: > >> > >> On Sun, Nov 15, 2015 at 1:02 PM, vincent(a)massol.net > >> >> > >> > Hi Denis, > >> > > >> > Thanks for your feedback, see below. > >> > > >> > On 15 Nov 2015 at 12:30:13, Denis Gervalle (dgl(a)softec.lu(mailto: > >> > dgl(a)softec.lu)) wrote: > >> > > >> > > On Fri, Nov 13, 2015 at 9:48 PM, vincent(a)massol.net > >> > > >> > > > >> > > > > >> > > > > >> > > > On 13 Nov 2015 at 19:35:56, Eduard Moraru (enygma2002(a)gmail.com > >> > (mailto: > >> > > > enygma2002(a)gmail.com)) wrote: > >> > > > > >> > > > > I am +1 to keep doing what we have been doing so far, which is, > on a > >> > > > > case-by-case basis and depending on the importance of the > blocker, to > >> > > > > manually add a notice (/error macro) in the release notes, > informing > >> > > > users. > >> > > > > If we want to document this as a best practice, I`m ok with it. > >> > > > > > >> > > > > I`m not a fan of increasing maintainance/work load in this > aspect, > >> > but > >> > > > > that`s just my opinion. > >> > > > > >> > > > I agree that low maintenance when possible is always better. That > was > >> > the > >> > > > point of the automated approach BTW. Even though automated has > >> > limitation > >> > > > don’t you think it’s better than what we’re doing ATM (i.e. adding > >> > stuff > >> > > > when we think about it, i.e. missing 80% of what we should do)? > >> > > > > >> > > > About this, I don’t agree that what we’ve been doing is good > because we > >> > > > almost never do it. AFAIR I’ve been almost the only one doing it > (I > >> > could > >> > > > be wrong please correct me if that’s the case) and pushing others > to > >> > do it > >> > > > and I would prefer not to have to > >> > > > >> > > > >> > > I can only speak for myself, but I do as well. Now it depends of the > >> > nature > >> > > of the blocker. All regression are blockers, but the regression > could > >> > still > >> > > be minor and not so annoying for most users. In that case, I do > not. Up > >> > to > >> > > now, what we put at the top in error box were blocker that we think > make > >> > > the release unrecommended for most users. And IMO, we should > continue > >> > doing > >> > > this manually at least. > >> > > > >> > > > >> > > > continue doing this all the time. An example was later today, we > >> > created a > >> > > > very important blocker and fixed it and yet we didn’t add it to > the RN > >> > of > >> > > > 7.3 until I raised it and added it myself. I’d rather not be the > one > >> > having > >> > > > to think about this and pestering others about it... > >> > > > > >> > > > I’d like a common agreement on whether we want to add blockers to > RN or > >> > > > not. If we think it’s not a good idea then I’m fine and we > shouldn't > >> > add > >> > > > them. > >> > > > > >> > > > >> > > We already add know issue we know about to the RN, so adding > blockers at > >> > > the top is not really adding them to the RN, but making them more > >> > visible. > >> > > This could be a good idea but not in replacement to our current > practice, > >> > > since it is less understandable, and more common then our current > >> > practice, > >> > > making the information less meaningful for users. This could even > cause > >> > > more confusion, if those blocker are minor regression on specific > areas. > >> > > > >> > > > >> > > > > >> > > > What I’m not fine about is saying that we think we should add > blockers > >> > and > >> > > > then not to do it, that doesn’t make sense. > >> > > > > >> > > > Regarding importance of blockers, for me a blocker is a blocker, > >> > otherwise > >> > > > it’s not named correctly and we should fix this :) > >> > > > > >> > > > >> > > This is not so true, blocker means we don’t want this in the next > >> > release, > >> > > and as I said, it is generally true for any regression. > >> > > >> > This is what I was trying to say with “for me a blocker is a > blocker”. I think > >> > we’re saying the same thing here: > >> > * We need a way to mark (in JIRA) very important issues that affect > some > >> > user-feature of xwiki (since RN are for users) > >> > * I agree that regressions don’t have to be blockers (and they’re not > all, > >> > there are several regressions we don’t mark as blockers because > they’re > >> > not…). You should know since the Mail API has had a few regressions > you > >> > introduced and they’re marked as regressions but not blockers ;) > >> > > >> > > But the actual > >> > > blocker could have several level of importance for different kind of > >> > user, > >> > > and in the end only affect very few of them but so hardly that it is > >> > still > >> > > blocker. If you look at your sample, I am even afraid by what users > will > >> > > understand of them. Either they will be afraid so much, that they > will > >> > not > >> > > upgrade, or they will not understand and consider they are not > affected. > >> > > See XWIKI-12502, XWIKI-12342, XWIKI-12251, what users will think of > them > >> > ? > >> > > >> > Yes that’s the risk and that’s the reason we have created manual > release > >> > notes indeed. Because just listing jira issues is not user-friendly > enough. > >> > > >> > > And on the other side, XWIKI-12218, while we want it in the next > release, > >> > > was it really so blocker for end users ? > >> > > >> > Again, there’s only a global process which is to separate real > blockers > >> > from a user POV (which we want highlighted in the RN) from important > issues > >> > that we want fixed but that are not really blockers for users. > >> > > >> > The only question is when do we do this separation: > >> > > >> > * Proposal 1 (Vincent): Do this sorting in JIRA and have a generic > query > >> > in the RN for listing those issues > >> > > >> * Proposal 2 (Denis, Edy): This is what we do now. Continue doing this > >> > sorting at random, by random people when they think about it. In most > cases > >> > it’s forgotten and not added to RN. > >> > > >> > >> I do not know for Edy, but for the above definition does not really > >> translate what I have said so far ! > >> What I said, is that we cannot simply list blockers at the top to > replace > >> the actual manual warnings because JIRA tickets are often unintelligible > >> for end users, and that all blockers (as we used to do them so far) are > not > >> at the same level, and does not necessarily need to be enhanced at the > same > >> level. That if we go that way, it means we need to rethink the way we > use > >> blocker in JIRA, and that I do not believe we should. > >> > >> > >> > > >> > I’m in favor of proposal 1, ie improve our JIRA tagging so that we > >> > identify real user blockers and list them automatically in the RN. > This > >> > would be the same process as we have now, ie we review issues being > created > >> > every day > >> > > >> > I’d be also ok for proposal 2 but only if we can define a process so > that > >> > we don’t forget about them (and that it’s not me doing it most of the > time > >> > and being the bad guy reminding everyone). > >> > > >> > > In your example above, those that > >> > > could be interesting and understandable warnings for some users are > >> > > XWIKI-12612, XWIKI-12160 and XWIKI-11993. > >> > > > >> > > So listing them in red at the very top may be too much, or > confusing IMO. > >> > > This does not mean the the could not list them somewhere in the RN, > maybe > >> > > in a {{warning}} macro, below the possible {{error}} we do > manually. This > >> > > could also help us think about doing a red one, when looking at the > RN. > >> > > >> > I think listing in red at the top is ok for really serious issues (ie > real > >> > blockers from user POV), i.e. to tell users to NOT use this version > if they > >> > used the feature mentioned. > >> > > >> > >> If this is really intelligible from the simple JIRA title, I would be > +1, > >> but I doubt we can really achieve that. > >> > >> > >> > > >> > > What afraid me in the end, is that we do less blockers just because > we > >> > know > >> > > they will appear in RN and they are so technical that nobody will > get it. > >> > > >> > That would be fine IMO because it would mean they’re not real > blockers and > >> > that releasing without them is ok. In the end what should be blocking > us > >> > from a release is the real end user blockers. > >> > > >> > >> Again, I am not sure this is so simple. Marking issue as blocker is > >> promising issues to be fixed for the release, and if this does not > really > >> happen, be sure we care a lot about them, and not simply push them to > the > >> next release without an agreement. This does not necessarily means that > the > >> issue affect a large amount of users, and that it is so important that > it > >> should prevent many users to try that release. > >> > >> > >> > > So the next question is, does all of them represent what you wanted > at > >> > the > >> > > top, compare to other issues ? Is those blocker more significant ? > Should > >> > > we change the way we use blocker ? > >> > > >> > Yep I think this is the real question. > >> > > >> > > I am not sure we should change anything in our current usage of > blocker, > >> > we > >> > > may want to have them enhanced in RN, but it does not mean all the > >> > > information will be so significant. > >> > > >> > I’m ok to not change our current usage of blockers but I don’t > understand > >> > what you’re suggesting for RN. You’re not addressing the reason for > this > >> > thread in the first place, which is that I feel that we just add > warning at > >> > random and we forget a lot and that it’s mostly me doing it. How do we > >> > prevent what happened Friday (ie. Marius not adding the blocker to > the top > >> > of the 7.3 RN)? > >> > > >> > >> As I have explained earlier, if we do not change our current usage of > >> blocker (and I like this idea), and if I look at your auto-generated > list > >> of blockers, many of them are unintelligible for the end users, and I do > >> not see what would be the benefit to list them, all it will do, is make > >> users confused or scared. > >> So, the manual decision is difficult to avoid. Maybe we could use a > manual > >> tag to exclude (or include) some blocker from the list, meaning that we > >> would go for a show them by default (or explicitly), and we have a way > to > >> explicitly make them not listed (or listed) while we still consider them > >> for the next release. But, I am not sure this is fine, since anyone (not > >> just committers) could create a blocker JIRA, and cause a change of the > RN… > >> is this acceptable to list unconfirmed blockers ? > >> > >> I do not know exactly what happened on Friday, but I would say that like > >> any manual process, we cannot be fully error safe, but I am sure all of > us > >> will do their best to ensure we care about this in the future. Don’t you > >> trust we could do that ? > >> > >> > >> > > >> > Thanks > >> > -Vincent > >> > > >> > > Thanks, > >> > > > >> > > > >> > > > > >> > > > Thanks for your feedback Edy. I’m curious to know what the others > >> > think at > >> > > > this point! :) > >> > > > > >> > > > Thanks > >> > > > -Vincent > >> > > > > >> > > > > Thanks, > >> > > > > Eduard > >> > > > > > >> > > > > On Fri, Nov 13, 2015 at 8:21 PM, vincent(a)massol.net > >> > > > > >> > > > > > >> > > > > > > >> > > > > > > >> > > > > > > >> > > > > > > >> > > > > > > >> > > > > > On 13 Nov 2015 at 19:14:11, Eduard Moraru ( > enygma2002(a)gmail.com > >> > > > (mailto: > >> > > > > > enygma2002(a)gmail.com)) wrote: > >> > > > > > > >> > > > > > > Hi, > >> > > > > > > > >> > > > > > > Another problem with automatic is that we don`t always tag > >> > > > > > affects-version > >> > > > > > > on the actual version when it was introduced, but the > version we > >> > > > actually > >> > > > > > > tested with. This might lead to displaying blockers on the > >> > release > >> > > > notes > >> > > > > > of > >> > > > > > > versions that were not responsible with introducing the > actual > >> > > > problem. > >> > > > > > > > >> > > > > > > Until now, we haven`t had that many cases and the 7.2, 7.3 > >> > releases > >> > > > could > >> > > > > > > be considered (from my POV) exceptions which had multiple > issues > >> > due > >> > > > to > >> > > > > > the > >> > > > > > > nature/complexity of the changes they introduced. > >> > > > > > > > >> > > > > > > So, in the end, I believe I`m +1 to stick to manual. > >> > > > > > > >> > > > > > Whether manual or automatic, are you +1 that we do this as a > best > >> > > > practice > >> > > > > > (ie always add blockers to RN, at the top and using an error > >> > macro)? > >> > > > > > > >> > > > > > Thanks > >> > > > > > -Vincent > >> > > > > > > >> > > > > > > > >> > > > > > > Thanks, > >> > > > > > > Eduard > >> > > > > > > > >> > > > > > > On Fri, Nov 13, 2015 at 7:00 PM, vincent(a)massol.net > >> > > > > > > >> > > > > > > > >> > > > > > > > To summarize: > >> > > > > > > > > >> > > > > > > > Pros and cons of automatic: > >> > > > > > > > + Not missing any > >> > > > > > > > - Technical descriptions > >> > > > > > > > > >> > > > > > > > Pros and cons of manual: > >> > > > > > > > + Nice hand-made messages > >> > > > > > > > - Usually missing some, unless we add a process (like > have the > >> > RM > >> > > > > > ensure > >> > > > > > > > that none are missing the previous release notes) > >> > > > > > > > > >> > > > > > > > WDYT? > >> > > > > > > > > >> > > > > > > > Thanks > >> > > > > > > > -Vincent > >> > > > > > > > On 13 Nov 2015 at 17:56:00, vincent(a)massol.net ( > >> > vincent(a)massol.net > >> > > > ) > >> > > > > > >> > > > > > > > > >> > > > > > > > OTOH if we do it automatically we won’t have as nice > >> > description as > >> > > > > > what > >> > > > > > > > we can have when we hand-make them. For example on > >> > > > > > > > > >> > > > > http://www.xwiki.org/xwiki/bin/view/ReleaseNotes/ReleaseNotesXWiki71 > >> > > > > > we > >> > > > > > > > have: > >> > > > > > > > > >> > > > > > > > “ > >> > > > > > > > This release introduces a bug concerning the upgrade of > the > >> > > > subwikis > >> > > > > > > > ([[XWIKI-12208>> > http://jira.xwiki.org/browse/XWIKI-12208]]). > >> > You > >> > > > can > >> > > > > > > > still upgrade them via Distribution Wizard but only at > the same > >> > > > time > >> > > > > > you > >> > > > > > > > upgrade the main wiki. You can also upgrade your > subwiki's UI > >> > like > >> > > > any > >> > > > > > > > other extensions, by clicking on "Check for updates". > >> > > > > > > > > >> > > > > > > > The best is to wait for the release of 7.1.1 which will > fix > >> > this > >> > > > > > problem > >> > > > > > > > and should be ready really soon. > >> > > > > > > > " > >> > > > > > > > > >> > > > > > > > And if we use the strategy below we get: > >> > > > > > > > > https://www.evernote.com/l/AHfEQXsj4mNH4pjXgxuiL4uZiomR5kUpkpA > >> > > > > > > > > >> > > > > > > > As you can see on the screenshot if we do it manually > we’re > >> > > > missing a > >> > > > > > lot > >> > > > > > > > of blocker issues. > >> > > > > > > > > >> > > > > > > > WDYT? > >> > > > > > > > > >> > > > > > > > Thanks > >> > > > > > > > -Vincent > >> > > > > > > > > >> > > > > > > > > >> > > > > > > > On 13 Nov 2015 at 17:51:50, vincent(a)massol.net ( > >> > vincent(a)massol.net > >> > > > ) > >> > > > > > >> > > > > > > > > >> > > > > > > > Hi devs, > >> > > > > > > > > >> > > > > > > > I’d like to suggest a new best practice which would > consist in > >> > > > > > > > systematically adding blockers issues in the release notes > >> > > > > > corresponding to > >> > > > > > > > the affects versions, at the top, using an error macro. > For > >> > example > >> > > > > > I’ve > >> > > > > > > > updated the release notes for 7.2 and 7.3: > >> > > > > > > > - > >> > > > > http://www.xwiki.org/xwiki/bin/view/ReleaseNotes/ReleaseNotesXWiki72 > >> > > > > > > > - > >> > > > > http://www.xwiki.org/xwiki/bin/view/ReleaseNotes/ReleaseNotesXWiki73 > >> > > > > > > > > >> > > > > > > > The idea would be to update our Release Notes template to > >> > > > automatically > >> > > > > > > > list them using this template snippet (example for XWiki > 7.2): > >> > > > > > > > > >> > > > > > > > " > >> > > > > > > > {{error}} > >> > > > > > > > The following blocking issues were found after this > version was > >> > > > > > released. > >> > > > > > > > You should verify if you're using the affected features > and if > >> > so, > >> > > > you > >> > > > > > can > >> > > > > > > > click on them to see in which version they are fixed): > >> > > > > > > > > >> > > > > > > > {{jira url="http://jira.xwiki.org" style="list" > source="jql"}} > >> > > > > > > > category = "Top Level Projects" and affectedVersion in > >> > > > > > > > ("7.2-milestone-1", "7.2-milestone-2", "7.2-milestone-3", > >> > > > "7.2-rc-1", > >> > > > > > > > "7.2") and fixVersion > "7.2" and priority = Blocker and > >> > > > resolution = > >> > > > > > Fixed > >> > > > > > > > {{/jira}} > >> > > > > > > > {{/error}} > >> > > > > > > > “ > >> > > > > > > > > >> > > > > > > > The goal is to make it easy for our end users to see > blocking > >> > > > issues > >> > > > > > in a > >> > > > > > > > given release. The goal is also to make it visible to us > how > >> > many > >> > > > > > blockers > >> > > > > > > > we introduce in each release and work on reducing this > number > >> > as > >> > > > much > >> > > > > > as > >> > > > > > > > possible. > >> > > > > > > > > >> > > > > > > > WDYT? > >> > > > > > > > > >> > > > > > > > Thanks > >> > > > > > > > -Vincent > >> > > >> > >> > >> > >> -- > >> Denis Gervalle > >> SOFTEC sa - CEO > >> _______________________________________________ > >> devs mailing list > >> devs(a)xwiki.org > >> http://lists.xwiki.org/mailman/listinfo/devs > >> _______________________________________________ > >> devs mailing list > >> devs(a)xwiki.org > >> http://lists.xwiki.org/mailman/listinfo/devs > > _______________________________________________ > > devs mailing list > > devs(a)xwiki.org > > http://lists.xwiki.org/mailman/listinfo/devs > > > > -- > Thomas Mortagne > _______________________________________________ > devs mailing list > devs(a)xwiki.org > http://lists.xwiki.org/mailman/listinfo/devs >