29 Sep
2011
29 Sep
'11
3:10 a.m.
On 09/28/2011 07:27 AM, Vincent Massol wrote:
On Sep 28, 2011, at 12:57 PM, Eduard Moraru wrote:
I second Vincent, making crappy release notes automatically is easy,
just list all the closed issue titles and you're done. But the result
won't make any sense at all, and only the core developers would be able
to understand what they mean. The release notes are supposed to be
clear, simple, and pretty, to attract users that don't care about what
version of the reflections library is used internally, or where does
aether store its cache, but care that we introduced the message stream
feature in 3.0.
The problem with the release notes is that they take a lot of time to
prepare, and this delays the release too much.
First part of the release is usually smooth, and can be done in two
hours (most of the time waiting for the permutations of the WYSIWYG
editor to compile).
Then comes the second part, which involves posting a lot of
announcements summarizing the release. This too shouldn't take that
much, and a well organized person can do it in half an hour. But it
requires that the release notes are ready, and the major features are
listed in a few words (Freshmeat for example limits us to 600 chars).
And it's hard to go over more than 100 issues one by one and check if
they are worth mentioning, trying to summarize the selected ones in a
few words ("New implementation of the sheet system", "Named parameters
for the event stream", "Office Document Export"), then write some text
to describe the feature in more detail, make up some screenshots of the
feature in use, etc. Then comes the part about migration and backwards
compatibility, and this requires even more detail when going over the
closed issues to determine if some obscure issue that you didn't follow
and have no idea what it's about is going to cause trouble or not.
So, between the first and the second part of the release there's a big
break. I usually end up doing the second part one day after the first
part, and for 3.2M1 I even screwed it up completely because I didn't
know what to put in the release notes.
On Wed, Sep 28, 2011 at 1:42 PM, Vincent
Massol<vincent(a)massol.net> wrote:
We have to use a lot more tools than that to close a bug:
- an IDE
- maven
- git
- a web browser to do searches on the web
- etc
I don't see what's the problem of using several tools.
>>
>>> Why don`t we use Jira's ability to comment on an issue when actually
>> closing
>>> it? We could then make a script to automatically round up all such
>> comments
>>> for the release process. At least it would be a single application and it
>>> would be no major breaking of the flow.
>>
>> If what you suggest is automated releases notes, I've been trying to do
>> that for about 12 years now and it has never worked to a satisfactory level
>> ;)
On Sep 28, 2011, at 12:30 PM, Eduard Moraru wrote:
1. Jira
2. XWiki.org Hi,
On Wed, Sep 28, 2011 at 8:28 AM, Vincent Massol<vincent(a)massol.net>
wrote:
> Hi devs,
>
> Sergiu has started a script to fully automate a release (more to come -
> Sergiu will document what it does soon). The only part not automated are
the
> Release Notes.
>
> IMO we can "automate" it by a process which I propose to be:
>
> * An issue can only be closed if it's documented on xwiki.org and on
the
> release notes page for the upcoming release.
>
I`m not very keen of such an approach. This adds paperwork to N people
(devs) that have already completed a job
I definitely don't agree here. A dev job is not complete if
* tests are not written
* documentation has not been added
, multiplied by M issues (which can
be more than 1 each day) done by each person... instead of just 1 person
(release manager) in charge of a task that is repeated once every couple
of
weeks (low frequency).
I'm not sure I understand what you're saying. Are you also suggesting that
committers should not do code reviews and any of all the other tasks they're
suppose to do because it takes too much time and would be better done by a
single individual? I hope not… :)
Side note: You should try to be a release manager to see what it takes
(although with Sergiu's script it should be much easier now).
Plus, the N devs have to use 2 tools to close one
single bug.
What tools?
>> What you suggest is also not very good IMO
because it duplicates work
>> effort since the devs will need to document the stuff on xwiki.org anyway.
>>
>
> Please be more clear (preferably with an example) about what you expect for
> each developer to document on xwiki.org for each issue closed.
OK, Vincent was a bit wrong. It's not about *every* issue, but about
every issue that is worth documenting.
Bugs like http://jira.xwiki.org/browse/XWIKI-6925 are too technical and
shouldn't even affect 99.9% of the users, even if they are marked as
Critical, since it's only about upgrades to the previous milestone
(3.2M2) and only for a certain configuration.
OTOH, trivial tasks like http://jira.xwiki.org/browse/XWIKI-6920 should
be mentioned in the release notes in the Upgrades section.
Big changes like http://jira.xwiki.org/browse/XWIKI-6974 deserve not
just a mention in the release notes, but a full documentation page, with
lots of screenshots and explanations. If the developer doesn't feel that
he's up to the task, which does require more people/communication/design
skills, they should ask for help from the marketing department (XWiki
SAS) and work together with them. The marketing department alone doesn't
know how to use a new feature that's fresh out of development, so the
developer has to participate as well, even if only to indicate what
should be mentioned.
For example:
* Marius add a new sheet module. This needs to be documented on extensions.xwiki.org as a
Module type.
* Sergiu added changes to the search so the search extension needs to be reviewed to see
if it still matches the changes.
* "support for OpenOffice 3.3 as the backend of the office importer". We need
to check the doc of the office importer and see if there's any mention of supported
version and update it
* For ex I updated the component archetype to use the new injection annotation and I
modified http://platform.xwiki.org/xwiki/bin/view/DevGuide/WritingComponents as a
consequence (I also have some backlogs to do, for ex when I added support for JSR330 I
haven't modified
http://extensions.xwiki.org/xwiki/bin/view/Extension/Component+Module, which is bad and I
need to catch up now).
* etc
>>>> * We collectively enforce this by reopening issues if someone doesn't
do
>>>> the first point, asking him/her to do it
>>>>
>>>
>>> Not sure how things work on Jira, but maybe we could do a very simple
>> Jira
>>> extension/plugin that does not allow closing an issue without commenting
>> on
>>> the chosen solution or whatever it is that we would want in the release
>>> notes.
>>
>> I don't see how that would help xwiki.org be more up to date. Remember
>> that release notes should point to documentation not duplicate it.
>>
>
> For instance, in
> http://www.xwiki.org/xwiki/bin/ReleaseNotes/ReleaseNotesXWikiEnterprise32M3I
> see no link to the list of fixed Jira issues, grouped by issue type.
> What
> I see there is a "resume" rather than a full, bullet list (maybe with
> expandable sections to say 2 words about the stuff done for the particular
> issue) of things done. While I agree that the resume is more user friendly
> (for users that have the attention span to read full paragraphs), I also
> think that we should include (prefferably), or at least link to, the Jira
> generated issue list. You can`t have people guess that they have to go to
> Jira and make 3-5 clicks to get the list of fixed issues.
A list of 164 issues will hide the real improvements that users care about.
Yes we need to do both. We absolutely need the user
friendly summary and it's good to have the full list too.
What I've done in the past (and I've already prepared it for 3.2 final) is a link
to a filter in JIRA that shows the full list.
My idea is then to use a JIRA macro that takes this filter and displays them on the RN
page (although a link might be just enough too).
I prefer a link. The full list is going to be too long and too technical
to fit nicely in the release notes.
For ex for 3.1 final:
http://jira.xwiki.org/secure/IssueNavigator.jspa?mode=hide&requestId=10…
http://jira.xwiki.org/secure/Dashboard.jspa?selectPageId=10580
http://jira.xwiki.org/secure/Dashboard.jspa?selectPageId=10581
We could do this for each release. It's easy to
do.
Already did, and the link towards them should be placed in the Roadmap
and in the ReleaseNotes.
Thanks
-Vincent
> Thanks,
> Eduard
>
>
>>
>> Thanks
>> -Vincent
>>
>>> Thanks,
>>> Eduard
>>>
>>>>
>>>> This will have some nice effects:
>>>> * xwiki.org will be more up to date than it is now
>>>> * it's up to the developer to document what they do (I don't
think it's
>>>> good to push this to someone else) which is good since they have the
>> most
>>>> knowledge (side note: it doesn't mean we don't need a technical
writer
>> to
>>>> improve on the documentation done by developers but it would be about
>> style
>>>> and not about content)
>>>> * the release notes will be ready for the release, as we progress and
>> the
>>>> burden of writing the release notes will not fall on the shoulders of
>> the
>>>> Release Manager (there's no reason it should)
>>>> * the whole release process will almost be a joy to do
>>>> * with a fully automated release process it means we'll be able to
>> perform
>>>> a lot more bugfix releases which is good for our users
>>>>
>>>> Here's my +1
>>>>
>>>> Thanks
>>>> -Vincent
--
Sergiu Dumitriu
http://purl.org/net/sergiu/