[xwiki-devs] Release notes strategy for included contrib extensions
Hi devs, We now include a few contrib apps in XE. However, when someone checks the RN for XE, for example http://www.xwiki.org/xwiki/bin/view/ReleaseNotes/ReleaseNotesXWiki83M2 all they see is this: “The following dependencies have been upgraded: * Tour Application 1.0.4” It doesn’t say if there are any substantial things added those deps. I can think of 2 solutions: 1) When something is noticeable, add it to the RN of XE. So for example if CKEditor extension adds something new, users checking the RN of XE can see it immediately. 2) Link to the RN of the extension. However RN of extensions on e.x.o are not nice. They’re just lists of JIRA issues. So for this solution to be a bit satisfactory we would need to improve the RN of extensions, starting with those we bundle in XE. Another possibility is to say that for Recommended Extensions we pay an extra care to write nice Release Notes. But that’s harder to enforce and ensure. Option 1) is my preference. WDYT? Thanks -Vincent
+1 for 1) On Tue, Sep 13, 2016 at 6:23 PM, Vincent Massol <[email protected]> wrote:
Hi devs,
We now include a few contrib apps in XE. However, when someone checks the RN for XE, for example http://www.xwiki.org/xwiki/bin/view/ReleaseNotes/ReleaseNotesXWiki83M2 all they see is this:
“The following dependencies have been upgraded: * Tour Application 1.0.4”
It doesn’t say if there are any substantial things added those deps.
I can think of 2 solutions:
1) When something is noticeable, add it to the RN of XE. So for example if CKEditor extension adds something new, users checking the RN of XE can see it immediately.
2) Link to the RN of the extension. However RN of extensions on e.x.o are not nice. They’re just lists of JIRA issues. So for this solution to be a bit satisfactory we would need to improve the RN of extensions, starting with those we bundle in XE. Another possibility is to say that for Recommended Extensions we pay an extra care to write nice Release Notes. But that’s harder to enforce and ensure.
Option 1) is my preference.
WDYT?
Thanks -Vincent
_______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Thomas Mortagne
+1 for 1) too 2016-09-13 18:26 GMT+02:00 Thomas Mortagne <[email protected]>:
+1 for 1)
On Tue, Sep 13, 2016 at 6:23 PM, Vincent Massol <[email protected]> wrote:
Hi devs,
We now include a few contrib apps in XE. However, when someone checks the RN for XE, for example http://www.xwiki.org/xwiki/ bin/view/ReleaseNotes/ReleaseNotesXWiki83M2 all they see is this:
“The following dependencies have been upgraded: * Tour Application 1.0.4”
It doesn’t say if there are any substantial things added those deps.
I can think of 2 solutions:
1) When something is noticeable, add it to the RN of XE. So for example if CKEditor extension adds something new, users checking the RN of XE can see it immediately.
2) Link to the RN of the extension. However RN of extensions on e.x.o are not nice. They’re just lists of JIRA issues. So for this solution to be a bit satisfactory we would need to improve the RN of extensions, starting with those we bundle in XE. Another possibility is to say that for Recommended Extensions we pay an extra care to write nice Release Notes. But that’s harder to enforce and ensure.
Option 1) is my preference.
WDYT?
Thanks -Vincent
_______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Thomas Mortagne _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Guillaume Delhumeau ([email protected]) Research & Development Engineer at XWiki SAS Committer on the XWiki.org project
+1 for 1) Thanks, Marius On Tue, Sep 13, 2016 at 7:23 PM, Vincent Massol <[email protected]> wrote:
Hi devs,
We now include a few contrib apps in XE. However, when someone checks the RN for XE, for example http://www.xwiki.org/xwiki/bin/view/ReleaseNotes/ ReleaseNotesXWiki83M2 all they see is this:
“The following dependencies have been upgraded: * Tour Application 1.0.4”
It doesn’t say if there are any substantial things added those deps.
I can think of 2 solutions:
1) When something is noticeable, add it to the RN of XE. So for example if CKEditor extension adds something new, users checking the RN of XE can see it immediately.
2) Link to the RN of the extension. However RN of extensions on e.x.o are not nice. They’re just lists of JIRA issues. So for this solution to be a bit satisfactory we would need to improve the RN of extensions, starting with those we bundle in XE. Another possibility is to say that for Recommended Extensions we pay an extra care to write nice Release Notes. But that’s harder to enforce and ensure.
Option 1) is my preference.
WDYT?
Thanks -Vincent
_______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
We could have an "Extensions" section in the RN of XE where we could display noticeable functionalities. So that's your 1) variant. My problem is that we have this discrepancy between RN and Documentation. So this means we would duplicate content to RN and Documentation, instead of reusing it. Usually instead of duplicating it, we just put it in one place and link from the other. Maybe the "News and Worthy" application could improve this. Have some ReleaseNotes objects per version that could be integrated inside XE RN and Extensions documentation, and use them from the XE RN. Thanks, Caty On Mon, Sep 19, 2016 at 4:51 PM, Marius Dumitru Florea < [email protected]> wrote:
+1 for 1)
Thanks, Marius
On Tue, Sep 13, 2016 at 7:23 PM, Vincent Massol <[email protected]> wrote:
Hi devs,
We now include a few contrib apps in XE. However, when someone checks the RN for XE, for example http://www.xwiki.org/xwiki/bin/view/ReleaseNotes/ ReleaseNotesXWiki83M2 all they see is this:
“The following dependencies have been upgraded: * Tour Application 1.0.4”
It doesn’t say if there are any substantial things added those deps.
I can think of 2 solutions:
1) When something is noticeable, add it to the RN of XE. So for example if CKEditor extension adds something new, users checking the RN of XE can see it immediately.
2) Link to the RN of the extension. However RN of extensions on e.x.o are not nice. They’re just lists of JIRA issues. So for this solution to be a bit satisfactory we would need to improve the RN of extensions, starting with those we bundle in XE. Another possibility is to say that for Recommended Extensions we pay an extra care to write nice Release Notes. But that’s harder to enforce and ensure.
Option 1) is my preference.
WDYT?
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
On 19 Sep 2016, at 15:59, Ecaterina Moraru (Valica) <[email protected]> wrote:
We could have an "Extensions" section in the RN of XE where we could display noticeable functionalities. So that's your 1) variant.
My problem is that we have this discrepancy between RN and Documentation. So this means we would duplicate content to RN and Documentation, instead of reusing it.
It’s not duplication. One explains the changes (the RN) and the other explains the features. The RN should not duplicate too much of the ref documentation and it should link to it. Of course there’s always a bit of overlap like screenshots (which btw we don’t link since the screenshots in the ref doc change while they shouldn’t change over time on the RN page!). This could be a key reason that RN and reference doc could not be the same! RN should not change so you can go back to it but reference doc can keep being improved, screenshots updated, etc. Unless you always use a revision number in your links/content and make sure to never loose the history. Thanks -Vincent
Usually instead of duplicating it, we just put it in one place and link from the other. Maybe the "News and Worthy" application could improve this. Have some ReleaseNotes objects per version that could be integrated inside XE RN and Extensions documentation, and use them from the XE RN.
Thanks, Caty
On Mon, Sep 19, 2016 at 4:51 PM, Marius Dumitru Florea < [email protected]> wrote:
+1 for 1)
Thanks, Marius
On Tue, Sep 13, 2016 at 7:23 PM, Vincent Massol <[email protected]> wrote:
Hi devs,
We now include a few contrib apps in XE. However, when someone checks the RN for XE, for example http://www.xwiki.org/xwiki/bin/view/ReleaseNotes/ ReleaseNotesXWiki83M2 all they see is this:
“The following dependencies have been upgraded: * Tour Application 1.0.4”
It doesn’t say if there are any substantial things added those deps.
I can think of 2 solutions:
1) When something is noticeable, add it to the RN of XE. So for example if CKEditor extension adds something new, users checking the RN of XE can see it immediately.
2) Link to the RN of the extension. However RN of extensions on e.x.o are not nice. They’re just lists of JIRA issues. So for this solution to be a bit satisfactory we would need to improve the RN of extensions, starting with those we bundle in XE. Another possibility is to say that for Recommended Extensions we pay an extra care to write nice Release Notes. But that’s harder to enforce and ensure.
Option 1) is my preference.
WDYT?
Thanks -Vincent
Another idea would be to use the extension page`s release notes as the main place where to write changes and then, in the XE RN, aggregate the RN of all the bundled extensions. This would cover both contrib and core extensions and would also make the extension page much nicer, since right now you can only see the documentation but have no clear picture of the changes that the application has gone through. What we are doing now does not make a lot of sense (having the page + doc in one place, and the changes of particular extensions in the RN of some product aggregating them). Otherwise, sure, 1) is the workaround solution to continue doing what we are doing. Thanks, Eduard On Mon, Sep 19, 2016 at 8:21 PM, Vincent Massol <[email protected]> wrote:
On 19 Sep 2016, at 15:59, Ecaterina Moraru (Valica) <[email protected]> wrote:
We could have an "Extensions" section in the RN of XE where we could display noticeable functionalities. So that's your 1) variant.
My problem is that we have this discrepancy between RN and Documentation. So this means we would duplicate content to RN and Documentation, instead of reusing it.
It’s not duplication. One explains the changes (the RN) and the other explains the features.
The RN should not duplicate too much of the ref documentation and it should link to it.
Of course there’s always a bit of overlap like screenshots (which btw we don’t link since the screenshots in the ref doc change while they shouldn’t change over time on the RN page!).
This could be a key reason that RN and reference doc could not be the same! RN should not change so you can go back to it but reference doc can keep being improved, screenshots updated, etc. Unless you always use a revision number in your links/content and make sure to never loose the history.
Thanks -Vincent
Usually instead of duplicating it, we just put it in one place and link from the other. Maybe the "News and Worthy" application could improve this. Have some ReleaseNotes objects per version that could be integrated inside XE RN and Extensions documentation, and use them from the XE RN.
Thanks, Caty
On Mon, Sep 19, 2016 at 4:51 PM, Marius Dumitru Florea < [email protected]> wrote:
+1 for 1)
Thanks, Marius
On Tue, Sep 13, 2016 at 7:23 PM, Vincent Massol <[email protected]> wrote:
Hi devs,
We now include a few contrib apps in XE. However, when someone checks the RN for XE, for example http://www.xwiki.org/xwiki/ bin/view/ReleaseNotes/ ReleaseNotesXWiki83M2 all they see is this:
“The following dependencies have been upgraded: * Tour Application 1.0.4”
It doesn’t say if there are any substantial things added those deps.
I can think of 2 solutions:
1) When something is noticeable, add it to the RN of XE. So for example if CKEditor extension adds something new, users checking the RN of XE can see it immediately.
2) Link to the RN of the extension. However RN of extensions on e.x.o are not nice. They’re just lists of JIRA issues. So for this solution to be a bit satisfactory we would need to improve the RN of extensions, starting with those we bundle in XE. Another possibility is to say that for Recommended Extensions we pay an extra care to write nice Release Notes. But that’s harder to enforce and ensure.
Option 1) is my preference.
WDYT?
Thanks -Vincent
devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
On 12 Oct 2016, at 12:34, Eduard Moraru <[email protected]> wrote:
Another idea would be to use the extension page`s release notes as the main place where to write changes and then, in the XE RN, aggregate the RN of all the bundled extensions. This would cover both contrib and core extensions and would also make the extension page much nicer, since right now you can only see the documentation but have no clear picture of the changes that the application has gone through. What we are doing now does not make a lot of sense (having the page + doc in one place, and the changes of particular extensions in the RN of some product aggregating them).
Otherwise, sure, 1) is the workaround solution to continue doing what we are doing.
Now that we have the RN app on xwiki.org, I think I’d prefer to use that app for all extensions RNs and then to use the {{changes/}} macro in the e.x.o pages. WDYT? Thanks -Vincent
Thanks, Eduard
On Mon, Sep 19, 2016 at 8:21 PM, Vincent Massol <[email protected]> wrote:
On 19 Sep 2016, at 15:59, Ecaterina Moraru (Valica) <[email protected]> wrote:
We could have an "Extensions" section in the RN of XE where we could display noticeable functionalities. So that's your 1) variant.
My problem is that we have this discrepancy between RN and Documentation. So this means we would duplicate content to RN and Documentation, instead of reusing it.
It’s not duplication. One explains the changes (the RN) and the other explains the features.
The RN should not duplicate too much of the ref documentation and it should link to it.
Of course there’s always a bit of overlap like screenshots (which btw we don’t link since the screenshots in the ref doc change while they shouldn’t change over time on the RN page!).
This could be a key reason that RN and reference doc could not be the same! RN should not change so you can go back to it but reference doc can keep being improved, screenshots updated, etc. Unless you always use a revision number in your links/content and make sure to never loose the history.
Thanks -Vincent
Usually instead of duplicating it, we just put it in one place and link from the other. Maybe the "News and Worthy" application could improve this. Have some ReleaseNotes objects per version that could be integrated inside XE RN and Extensions documentation, and use them from the XE RN.
Thanks, Caty
On Mon, Sep 19, 2016 at 4:51 PM, Marius Dumitru Florea < [email protected]> wrote:
+1 for 1)
Thanks, Marius
On Tue, Sep 13, 2016 at 7:23 PM, Vincent Massol <[email protected]> wrote:
Hi devs,
We now include a few contrib apps in XE. However, when someone checks the RN for XE, for example http://www.xwiki.org/xwiki/ bin/view/ReleaseNotes/ ReleaseNotesXWiki83M2 all they see is this:
“The following dependencies have been upgraded: * Tour Application 1.0.4”
It doesn’t say if there are any substantial things added those deps.
I can think of 2 solutions:
1) When something is noticeable, add it to the RN of XE. So for example if CKEditor extension adds something new, users checking the RN of XE can see it immediately.
2) Link to the RN of the extension. However RN of extensions on e.x.o are not nice. They’re just lists of JIRA issues. So for this solution to be a bit satisfactory we would need to improve the RN of extensions, starting with those we bundle in XE. Another possibility is to say that for Recommended Extensions we pay an extra care to write nice Release Notes. But that’s harder to enforce and ensure.
Option 1) is my preference.
WDYT?
Thanks -Vincent
On Mon, Oct 17, 2016 at 8:15 PM, Vincent Massol <[email protected]> wrote:
On 12 Oct 2016, at 12:34, Eduard Moraru <[email protected]> wrote:
Another idea would be to use the extension page`s release notes as the main place where to write changes and then, in the XE RN, aggregate the RN of all the bundled extensions. This would cover both contrib and core extensions and would also make the extension page much nicer, since right now you can only see the documentation but have no clear picture of the changes that the application has gone through. What we are doing now does not make a lot of sense (having the page + doc in one place, and the changes of particular extensions in the RN of some product aggregating them).
Otherwise, sure, 1) is the workaround solution to continue doing what we are doing.
Now that we have the RN app on xwiki.org, I think I’d prefer to use that app for all extensions RNs and then to use the {{changes/}} macro in the e.x.o pages.
WDYT?
Sounds good to me. The result would pretty much be the same (i.e. RN of extensions located in extension pages and XE RN just listing them). However, I`m not sure how this would work exactly with the Repository Application's extension release notes. Would an extension Release Note in the extension page call the {{changes/}} macro as well to list the changes that are stored on the main wiki's ReleaseNotes/Data/extension/version/ChangeXXX? Thanks, Eduard
Thanks -Vincent
Thanks, Eduard
On Mon, Sep 19, 2016 at 8:21 PM, Vincent Massol <[email protected]> wrote:
On 19 Sep 2016, at 15:59, Ecaterina Moraru (Valica) <[email protected]
wrote:
We could have an "Extensions" section in the RN of XE where we could display noticeable functionalities. So that's your 1) variant.
My problem is that we have this discrepancy between RN and
Documentation.
So this means we would duplicate content to RN and Documentation, instead of reusing it.
It’s not duplication. One explains the changes (the RN) and the other explains the features.
The RN should not duplicate too much of the ref documentation and it should link to it.
Of course there’s always a bit of overlap like screenshots (which btw we don’t link since the screenshots in the ref doc change while they shouldn’t change over time on the RN page!).
This could be a key reason that RN and reference doc could not be the same! RN should not change so you can go back to it but reference doc can keep being improved, screenshots updated, etc. Unless you always use a revision number in your links/content and make sure to never loose the history.
Thanks -Vincent
Usually instead of duplicating it, we just put it in one place and link from the other. Maybe the "News and Worthy" application could improve this. Have some ReleaseNotes objects per version that could be integrated inside XE RN and Extensions documentation, and use them from the XE RN.
Thanks, Caty
On Mon, Sep 19, 2016 at 4:51 PM, Marius Dumitru Florea < [email protected]> wrote:
+1 for 1)
Thanks, Marius
On Tue, Sep 13, 2016 at 7:23 PM, Vincent Massol <[email protected]> wrote:
Hi devs,
We now include a few contrib apps in XE. However, when someone checks the RN for XE, for example http://www.xwiki.org/xwiki/ bin/view/ReleaseNotes/ ReleaseNotesXWiki83M2 all they see is this:
“The following dependencies have been upgraded: * Tour Application 1.0.4”
It doesn’t say if there are any substantial things added those deps.
I can think of 2 solutions:
1) When something is noticeable, add it to the RN of XE. So for example if CKEditor extension adds something new, users checking the RN of XE can see it immediately.
2) Link to the RN of the extension. However RN of extensions on e.x.o are not nice. They’re just lists of JIRA issues. So for this solution to be a bit satisfactory we would need to improve the RN of extensions, starting with those we bundle in XE. Another possibility is to say that for Recommended Extensions we pay an extra care to write nice Release Notes. But that’s harder to enforce and ensure.
Option 1) is my preference.
WDYT?
Thanks -Vincent
devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
On 19 Oct 2016, at 13:36, Eduard Moraru <[email protected]> wrote:
On Mon, Oct 17, 2016 at 8:15 PM, Vincent Massol <[email protected]> wrote:
On 12 Oct 2016, at 12:34, Eduard Moraru <[email protected]> wrote:
Another idea would be to use the extension page`s release notes as the main place where to write changes and then, in the XE RN, aggregate the RN of all the bundled extensions. This would cover both contrib and core extensions and would also make the extension page much nicer, since right now you can only see the documentation but have no clear picture of the changes that the application has gone through. What we are doing now does not make a lot of sense (having the page + doc in one place, and the changes of particular extensions in the RN of some product aggregating them).
Otherwise, sure, 1) is the workaround solution to continue doing what we are doing.
Now that we have the RN app on xwiki.org, I think I’d prefer to use that app for all extensions RNs and then to use the {{changes/}} macro in the e.x.o pages.
WDYT?
Sounds good to me. The result would pretty much be the same (i.e. RN of extensions located in extension pages and XE RN just listing them).
However, I`m not sure how this would work exactly with the Repository Application's extension release notes. Would an extension Release Note in the extension page call the {{changes/}} macro as well to list the changes that are stored on the main wiki's ReleaseNotes/Data/extension/version/ChangeXXX?
The {{changes/}} macro’s goal is to list the changes stored in xwiki:ReleaseNotes.Data.<extension name>.<version>/ChangeXXX. So yes you’d call the {{changes/}} macro from the RN xproperty of the proper extension xobject. We could imagine automating this in the future on exo (ie calling automatically the {{changes/}} macro in each RN xproperty). Thanks -Vincent
Thanks, Eduard
Thanks -Vincent
Thanks, Eduard
On Mon, Sep 19, 2016 at 8:21 PM, Vincent Massol <[email protected]> wrote:
On 19 Sep 2016, at 15:59, Ecaterina Moraru (Valica) <[email protected]
wrote:
We could have an "Extensions" section in the RN of XE where we could display noticeable functionalities. So that's your 1) variant.
My problem is that we have this discrepancy between RN and
Documentation.
So this means we would duplicate content to RN and Documentation, instead of reusing it.
It’s not duplication. One explains the changes (the RN) and the other explains the features.
The RN should not duplicate too much of the ref documentation and it should link to it.
Of course there’s always a bit of overlap like screenshots (which btw we don’t link since the screenshots in the ref doc change while they shouldn’t change over time on the RN page!).
This could be a key reason that RN and reference doc could not be the same! RN should not change so you can go back to it but reference doc can keep being improved, screenshots updated, etc. Unless you always use a revision number in your links/content and make sure to never loose the history.
Thanks -Vincent
Usually instead of duplicating it, we just put it in one place and link from the other. Maybe the "News and Worthy" application could improve this. Have some ReleaseNotes objects per version that could be integrated inside XE RN and Extensions documentation, and use them from the XE RN.
Thanks, Caty
On Mon, Sep 19, 2016 at 4:51 PM, Marius Dumitru Florea < [email protected]> wrote:
+1 for 1)
Thanks, Marius
On Tue, Sep 13, 2016 at 7:23 PM, Vincent Massol <[email protected]> wrote:
> Hi devs, > > We now include a few contrib apps in XE. However, when someone checks the > RN for XE, for example http://www.xwiki.org/xwiki/ bin/view/ReleaseNotes/ > ReleaseNotesXWiki83M2 all they see is this: > > “The following dependencies have been upgraded: > * Tour Application 1.0.4” > > It doesn’t say if there are any substantial things added those deps. > > I can think of 2 solutions: > > 1) When something is noticeable, add it to the RN of XE. So for example if > CKEditor extension adds something new, users checking the RN of XE can see > it immediately. > > 2) Link to the RN of the extension. However RN of extensions on e.x.o are > not nice. They’re just lists of JIRA issues. So for this solution to be a > bit satisfactory we would need to improve the RN of extensions, starting > with those we bundle in XE. Another possibility is to say that for > Recommended Extensions we pay an extra care to write nice Release Notes. > But that’s harder to enforce and ensure. > > Option 1) is my preference. > > WDYT? > > 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
participants (6)
-
Ecaterina Moraru (Valica) -
Eduard Moraru -
Guillaume Delhumeau -
Marius Dumitru Florea -
Thomas Mortagne -
Vincent Massol