[xwiki-devs] [VOTE] Improving documentation and automating our Release Notes when doing releases
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. * We collectively enforce this by reopening issues if someone doesn't do the first point, asking him/her to do it 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
On Wed, Sep 28, 2011 at 8:28 AM, Vincent Massol <[email protected]> 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.
What type of issue? I suppose your are referring to new features or improvements. Thanks, Marius
* We collectively enforce this by reopening issues if someone doesn't do the first point, asking him/her to do it
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
_______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
On Sep 28, 2011, at 9:37 AM, Marius Dumitru Florea wrote:
On Wed, Sep 28, 2011 at 8:28 AM, Vincent Massol <[email protected]> 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.
What type of issue? I suppose your are referring to new features or improvements.
Any issue. For example a bug fix will not go in the release notes for a milestone but will go in the release notes for a bug fix release or a RC. A bug issue will also usually not need to be documented elsewhere on xwiki.org, except maybe in an adhoc fashion for very important bug fixes which could be documented in the documentation to say that such feature wasn't working in version such and works after such other version. Thanks -Vincent
Thanks, Marius
* We collectively enforce this by reopening issues if someone doesn't do the first point, asking him/her to do it
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
On 09/28/2011 01:28 AM, Vincent Massol 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. * We collectively enforce this by reopening issues if someone doesn't do the first point, asking him/her to do it
+1 The release manager has to go the extra mile on the enforcement process, since otherwise it will be his duty to gather the release notes.
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/
Hi, On Wed, Sep 28, 2011 at 8:28 AM, Vincent Massol <[email protected]> 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, 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). Plus, the N devs have to use 2 tools to close one single bug. 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.
* 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. 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
_______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
On Sep 28, 2011, at 12:30 PM, Eduard Moraru wrote:
Hi,
On Wed, Sep 28, 2011 at 8:28 AM, Vincent Massol <[email protected]> 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?
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 ;) 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.
* 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. 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
On Wed, Sep 28, 2011 at 1:42 PM, Vincent Massol <[email protected]> wrote:
On Sep 28, 2011, at 12:30 PM, Eduard Moraru wrote:
Hi,
On Wed, Sep 28, 2011 at 8:28 AM, Vincent Massol <[email protected]> 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?
1. Jira 2. XWiki.org
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 ;)
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.
* 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. 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
_______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
On Sep 28, 2011, at 12:57 PM, Eduard Moraru wrote:
On Wed, Sep 28, 2011 at 1:42 PM, Vincent Massol <[email protected]> wrote:
On Sep 28, 2011, at 12:30 PM, Eduard Moraru wrote:
Hi,
On Wed, Sep 28, 2011 at 8:28 AM, Vincent Massol <[email protected]> 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?
1. Jira 2. XWiki.org
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 ;)
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.
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.
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). For ex for 3.1 final: http://jira.xwiki.org/secure/IssueNavigator.jspa?mode=hide&requestId=10990 For 3.2 final: http://jira.xwiki.org/secure/IssueNavigator.jspa?mode=hide&requestId=10991 We could do this for each release. It's easy to do. 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
On 09/28/2011 07:27 AM, Vincent Massol wrote:
On Sep 28, 2011, at 12:57 PM, Eduard Moraru wrote:
On Wed, Sep 28, 2011 at 1:42 PM, Vincent Massol<[email protected]> wrote:
On Sep 28, 2011, at 12:30 PM, Eduard Moraru wrote:
Hi,
On Wed, Sep 28, 2011 at 8:28 AM, Vincent Massol<[email protected]> 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?
1. Jira 2. XWiki.org
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 ;)
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.
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=10990
http://jira.xwiki.org/secure/Dashboard.jspa?selectPageId=10580
For 3.2 final: http://jira.xwiki.org/secure/IssueNavigator.jspa?mode=hide&requestId=10991
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/
On Thu, Sep 29, 2011 at 4:10 AM, Sergiu Dumitriu <[email protected]> wrote:
On 09/28/2011 07:27 AM, Vincent Massol wrote:
On Sep 28, 2011, at 12:57 PM, Eduard Moraru wrote:
On Wed, Sep 28, 2011 at 1:42 PM, Vincent Massol<[email protected]>
On Sep 28, 2011, at 12:30 PM, Eduard Moraru wrote:
Hi,
On Wed, Sep 28, 2011 at 8:28 AM, Vincent Massol<[email protected]> wrote:
Hi devs,
Sergiu has started a script to fully automate a release (more to come
wrote: -
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?
1. Jira 2. XWiki.org
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 ;)
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.
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.organyway.
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
Ok, now this makes sense. So the release notes page for the current upcoming release is created as soon as the previous release was launched and it's in a blank state. Then, devs fill it up collaboratively, as soon as they add changes worth mentioning in the release notes. Here's my +1, with the mention that we should add some structure to the release notes (object with sheet instead of blank page) to help the collaborative editing. The release manager will now have to level out the differences in writing styles of the various devs that contributed to the page :) Thanks, Eduard
* 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=10990
http://jira.xwiki.org/secure/Dashboard.jspa?selectPageId=10580
For 3.2 final:
http://jira.xwiki.org/secure/IssueNavigator.jspa?mode=hide&requestId=10991
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.
+1 for the link.
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/ _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
+1 On Wed, Sep 28, 2011 at 7:28 AM, Vincent Massol <[email protected]> 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. * We collectively enforce this by reopening issues if someone doesn't do the first point, asking him/her to do it
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
_______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Thomas Mortagne
+1 for me A few minor advantages which I have found for myself: When I write documentation, I tend to find out about bugs and usability issues because I'm forced to see things through the user's eyes. I am proud of my work so I tend to do a much better job of explaining it as the developer who wrote it than could an RM. Obviously as an RM, I want to have all of the material at hand so release is trivial. Caleb On 09/28/2011 01:28 AM, Vincent Massol 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. * We collectively enforce this by reopening issues if someone doesn't do the first point, asking him/her to do it
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
_______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
On Wed, Sep 28, 2011 at 8:28 AM, Vincent Massol <[email protected]> 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. * We collectively enforce this by reopening issues if someone doesn't do the first point, asking him/her to do it
I'm not convinced this is enough. If each of us documents everything we work on on the release notes we'll probably end up with a huge page with mixed technical and non-technical content marking it harder for different types of users to find the relevant information. I think we still need a "filter" (the release manager IMO) to decide what's worth mentioning (leave it or not in the release notes) and in which quantity (maybe a single phrase is enough and not 3 paragraphs). +0, I'm entirely for documenting my own work on the release notes but I don't believe this will "automatically" create the release notes. Thanks, Marius
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
_______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
On 05/18/2012 03:45 AM, Marius Dumitru Florea wrote:
On Wed, Sep 28, 2011 at 8:28 AM, Vincent Massol <[email protected]> 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. * We collectively enforce this by reopening issues if someone doesn't do the first point, asking him/her to do it
I'm not convinced this is enough. If each of us documents everything we work on on the release notes we'll probably end up with a huge page with mixed technical and non-technical content marking it harder for different types of users to find the relevant information. I think we still need a "filter" (the release manager IMO) to decide what's worth mentioning (leave it or not in the release notes) and in which quantity (maybe a single phrase is enough and not 3 paragraphs).
+0, I'm entirely for documenting my own work on the release notes but I don't believe this will "automatically" create the release notes.
This is a very good point, I agree that the developer's notes need to be proof read by someone (the RM?) and unimportant changes which "seemed important at the time" should be paired out. It might be nice to foster a competitive spirit to see whose features make the final cut of the release notes since I, as much as anyone, need to work on making my patches more relevant to the user. Caleb
Thanks, Marius
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
_______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
_______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
So here are the results of this vote: 4 +1, 1 0, no -1 The vote is passed. In order to remind committers to do this systematically I've configured JIRA by adding 2 custom fields to both the default scree and the close screen: * Documentation (text field) - Should contain the link to the doc on xwiki.org. IMPORTANT: If you think there's no need to have any doc for it on xwiki.org, use "N/A" as the value. * Added to Release Notes (radio button) - Set the status The idea is that when closing issues we do both, i.e. add documentation on xwiki.org and add it to the release notes for the version in development. Of course this should be done discriminatorily (use your judgment to decide). It's also everyone's duty to remind others when they notice that someone has forgotten to do so. Last, when doing Releases the RM should use a JIRA report listing all fixed issues having those fields not set. Example of using those fields: http://jira.xwiki.org/browse/XWIKI-7832 I'll document this on xwiki.org in the coming hours/days. Thanks -Vincent On Sep 28, 2011, at 7:28 AM, Vincent Massol 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. * We collectively enforce this by reopening issues if someone doesn't do the first point, asking him/her to do it
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
On May 18, 2012, at 5:31 PM, Vincent Massol wrote:
So here are the results of this vote: 4 +1, 1 0, no -1
The vote is passed.
In order to remind committers to do this systematically I've configured JIRA by adding 2 custom fields to both the default scree and the close screen: * Documentation (text field) - Should contain the link to the doc on xwiki.org. IMPORTANT: If you think there's no need to have any doc for it on xwiki.org, use "N/A" as the value. * Added to Release Notes (radio button) - Set the status
Hmm I'm wondering if we shouldn't use a text field for this too with a field name of "Documented in Release Notes". This would allow two things: 1) Put the link to the release notes (easier to navigate) 2) Ability to add some contents as to why it shouldn't go in the RN for example. WDYT? Thanks -Vincent
The idea is that when closing issues we do both, i.e. add documentation on xwiki.org and add it to the release notes for the version in development. Of course this should be done discriminatorily (use your judgment to decide).
It's also everyone's duty to remind others when they notice that someone has forgotten to do so.
Last, when doing Releases the RM should use a JIRA report listing all fixed issues having those fields not set.
Example of using those fields: http://jira.xwiki.org/browse/XWIKI-7832
I'll document this on xwiki.org in the coming hours/days.
Thanks -Vincent
On Sep 28, 2011, at 7:28 AM, Vincent Massol 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. * We collectively enforce this by reopening issues if someone doesn't do the first point, asking him/her to do it
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
On May 18, 2012, at 5:34 PM, Vincent Massol wrote:
On May 18, 2012, at 5:31 PM, Vincent Massol wrote:
So here are the results of this vote: 4 +1, 1 0, no -1
The vote is passed.
In order to remind committers to do this systematically I've configured JIRA by adding 2 custom fields to both the default scree and the close screen: * Documentation (text field) - Should contain the link to the doc on xwiki.org. IMPORTANT: If you think there's no need to have any doc for it on xwiki.org, use "N/A" as the value. * Added to Release Notes (radio button) - Set the status
Hmm I'm wondering if we shouldn't use a text field for this too with a field name of "Documented in Release Notes". This would allow two things: 1) Put the link to the release notes (easier to navigate) 2) Ability to add some contents as to why it shouldn't go in the RN for example.
WDYT?
I've gone ahead. See: * http://jira.xwiki.org/browse/XWIKI-7832 * http://jira.xwiki.org/browse/XWIKI-7839 It's cool :) Thanks -Vincent
Thanks -Vincent
The idea is that when closing issues we do both, i.e. add documentation on xwiki.org and add it to the release notes for the version in development. Of course this should be done discriminatorily (use your judgment to decide).
It's also everyone's duty to remind others when they notice that someone has forgotten to do so.
Last, when doing Releases the RM should use a JIRA report listing all fixed issues having those fields not set.
Example of using those fields: http://jira.xwiki.org/browse/XWIKI-7832
I'll document this on xwiki.org in the coming hours/days.
Thanks -Vincent
On Sep 28, 2011, at 7:28 AM, Vincent Massol 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. * We collectively enforce this by reopening issues if someone doesn't do the first point, asking him/her to do it
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
FYI we currently have 12 issues closed for 4.1M2 but which don't have Document and Release Notes fields set: http://jira.xwiki.org/secure/IssueNavigator.jspa?mode=hide&requestId=11594 Please fix ASAP. Also, I've set up a jira subscription filter so that xwiki committers will receive every Monday a mail containing this filter as a reminder to fix Documentation/Release notes for closed issues with no documentation/release notes. Reminder: * If an issue doesn't require documentation please use "N/A" or a description as to why it doesn't require doc * If an issue doesn't require documentation in the release notes please use "N/A" or a description as to why it doesn't require to be in the release notes Thanks! Our RM will thank us and the RM job will be nicer! -Vincent On May 19, 2012, at 12:17 PM, Vincent Massol wrote:
On May 18, 2012, at 5:34 PM, Vincent Massol wrote:
On May 18, 2012, at 5:31 PM, Vincent Massol wrote:
So here are the results of this vote: 4 +1, 1 0, no -1
The vote is passed.
In order to remind committers to do this systematically I've configured JIRA by adding 2 custom fields to both the default scree and the close screen: * Documentation (text field) - Should contain the link to the doc on xwiki.org. IMPORTANT: If you think there's no need to have any doc for it on xwiki.org, use "N/A" as the value. * Added to Release Notes (radio button) - Set the status
Hmm I'm wondering if we shouldn't use a text field for this too with a field name of "Documented in Release Notes". This would allow two things: 1) Put the link to the release notes (easier to navigate) 2) Ability to add some contents as to why it shouldn't go in the RN for example.
WDYT?
I've gone ahead. See: * http://jira.xwiki.org/browse/XWIKI-7832 * http://jira.xwiki.org/browse/XWIKI-7839
It's cool :)
Thanks -Vincent
Thanks -Vincent
The idea is that when closing issues we do both, i.e. add documentation on xwiki.org and add it to the release notes for the version in development. Of course this should be done discriminatorily (use your judgment to decide).
It's also everyone's duty to remind others when they notice that someone has forgotten to do so.
Last, when doing Releases the RM should use a JIRA report listing all fixed issues having those fields not set.
Example of using those fields: http://jira.xwiki.org/browse/XWIKI-7832
I'll document this on xwiki.org in the coming hours/days.
Thanks -Vincent
On Sep 28, 2011, at 7:28 AM, Vincent Massol 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. * We collectively enforce this by reopening issues if someone doesn't do the first point, asking him/her to do it
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
On May 20, 2012, at 10:38 AM, Vincent Massol wrote:
FYI we currently have 12 issues closed for 4.1M2 but which don't have Document and Release Notes fields set: http://jira.xwiki.org/secure/IssueNavigator.jspa?mode=hide&requestId=11594
Please fix ASAP.
I've filled the issues not requiring documentation/release notes. There remains 5 issues that require some sort of documentation/release notes. Please check them out. Thanks -Vincent
Also, I've set up a jira subscription filter so that xwiki committers will receive every Monday a mail containing this filter as a reminder to fix Documentation/Release notes for closed issues with no documentation/release notes.
Reminder: * If an issue doesn't require documentation please use "N/A" or a description as to why it doesn't require doc * If an issue doesn't require documentation in the release notes please use "N/A" or a description as to why it doesn't require to be in the release notes
Thanks! Our RM will thank us and the RM job will be nicer! -Vincent
On May 19, 2012, at 12:17 PM, Vincent Massol wrote:
On May 18, 2012, at 5:34 PM, Vincent Massol wrote:
On May 18, 2012, at 5:31 PM, Vincent Massol wrote:
So here are the results of this vote: 4 +1, 1 0, no -1
The vote is passed.
In order to remind committers to do this systematically I've configured JIRA by adding 2 custom fields to both the default scree and the close screen: * Documentation (text field) - Should contain the link to the doc on xwiki.org. IMPORTANT: If you think there's no need to have any doc for it on xwiki.org, use "N/A" as the value. * Added to Release Notes (radio button) - Set the status
Hmm I'm wondering if we shouldn't use a text field for this too with a field name of "Documented in Release Notes". This would allow two things: 1) Put the link to the release notes (easier to navigate) 2) Ability to add some contents as to why it shouldn't go in the RN for example.
WDYT?
I've gone ahead. See: * http://jira.xwiki.org/browse/XWIKI-7832 * http://jira.xwiki.org/browse/XWIKI-7839
It's cool :)
Thanks -Vincent
Thanks -Vincent
The idea is that when closing issues we do both, i.e. add documentation on xwiki.org and add it to the release notes for the version in development. Of course this should be done discriminatorily (use your judgment to decide).
It's also everyone's duty to remind others when they notice that someone has forgotten to do so.
Last, when doing Releases the RM should use a JIRA report listing all fixed issues having those fields not set.
Example of using those fields: http://jira.xwiki.org/browse/XWIKI-7832
I'll document this on xwiki.org in the coming hours/days.
Thanks -Vincent
On Sep 28, 2011, at 7:28 AM, Vincent Massol 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. * We collectively enforce this by reopening issues if someone doesn't do the first point, asking him/her to do it
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
On May 18, 2012, at 5:31 PM, Vincent Massol wrote:
So here are the results of this vote: 4 +1, 1 0, no -1
The vote is passed.
In order to remind committers to do this systematically I've configured JIRA by adding 2 custom fields to both the default scree and the close screen: * Documentation (text field) - Should contain the link to the doc on xwiki.org. IMPORTANT: If you think there's no need to have any doc for it on xwiki.org, use "N/A" as the value. * Added to Release Notes (radio button) - Set the status
The idea is that when closing issues we do both, i.e. add documentation on xwiki.org and add it to the release notes for the version in development. Of course this should be done discriminatorily (use your judgment to decide).
It's also everyone's duty to remind others when they notice that someone has forgotten to do so.
Last, when doing Releases the RM should use a JIRA report listing all fixed issues having those fields not set.
Example of using those fields: http://jira.xwiki.org/browse/XWIKI-7832
I'll document this on xwiki.org in the coming hours/days.
Added here: http://dev.xwiki.org/xwiki/bin/view/Community/DevelopmentPractices#HDocument... Thanks -Vincent
Thanks -Vincent
On Sep 28, 2011, at 7:28 AM, Vincent Massol 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. * We collectively enforce this by reopening issues if someone doesn't do the first point, asking him/her to do it
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
participants (6)
-
Caleb James DeLisle -
Eduard Moraru -
Marius Dumitru Florea -
Sergiu Dumitriu -
Thomas Mortagne -
Vincent Massol