[xwiki-devs] [Proposal] Changes in Macro Browser
Hi devs, Needs: * We need some “Deprecated” macro category so that users understand when a macro is deprecated and are less tempted to use it * We need to not show “Internal” macros by default to not “pollute” the Macro list by default Proposal: * When the “All Macros” is selected display all macros *except* those from 2 categories: “Deprecated” and “Internal”. * If the user needs/wants to use those macros, he’ll need to explicitly select those categories. * When we want to deprecate a Macro we move it from its category to the “Deprecated” category, before removing it further in the future (when is to be defined on an adhoc basis) Technical details: * Change https://github.com/xwiki-contrib/application-ckeditor/blob/master/plugins/sr... to implement this new behavior WDYT? Thanks -Vincent
That would be really great to have. My big +1 Thanks -- Denis Gervalle SOFTEC sa - CEO On sam., juil. 15, 2017 at 16:06, Vincent Massol <vincent@massol.net> wrote: Hi devs, Needs: * We need some “Deprecated” macro category so that users understand when a macro is deprecated and are less tempted to use it * We need to not show “Internal” macros by default to not “pollute” the Macro list by default Proposal: * When the “All Macros” is selected display all macros *except* those from 2 categories: “Deprecated” and “Internal”. * If the user needs/wants to use those macros, he’ll need to explicitly select those categories. * When we want to deprecate a Macro we move it from its category to the “Deprecated” category, before removing it further in the future (when is to be defined on an adhoc basis) Technical details: * Change https://github.com/xwiki-contrib/application-ckeditor/blob/master/plugins/sr... to implement this new behavior WDYT? Thanks -Vincent
+0. I hope the users won't get confused by the fact that "All macros" doesn't show all macros. The use case I have in mind is when an user upgrades XWiki and is looking for a macro he was using and that is now deprecated. He won't know to select the Deprecated category unless he reads the release notes. Thanks, Marius On Sat, Jul 15, 2017 at 5:06 PM, Vincent Massol <vincent@massol.net> wrote:
Hi devs,
Needs: * We need some “Deprecated” macro category so that users understand when a macro is deprecated and are less tempted to use it * We need to not show “Internal” macros by default to not “pollute” the Macro list by default
Proposal: * When the “All Macros” is selected display all macros *except* those from 2 categories: “Deprecated” and “Internal”. * If the user needs/wants to use those macros, he’ll need to explicitly select those categories. * When we want to deprecate a Macro we move it from its category to the “Deprecated” category, before removing it further in the future (when is to be defined on an adhoc basis)
Technical details: * Change https://github.com/xwiki-contrib/application-ckeditor/ blob/master/plugins/src/main/resources/xwiki-macro/macroSelector.js#L144 to implement this new behavior
WDYT?
Thanks -Vincent
A better UI could be a list of checkboxes and we could have Development, Deprecated and Internal not checked by default. Thanks -Vincent
On 17 Jul 2017, at 11:00, Marius Dumitru Florea <mariusdumitru.florea@xwiki.com> wrote:
+0. I hope the users won't get confused by the fact that "All macros" doesn't show all macros. The use case I have in mind is when an user upgrades XWiki and is looking for a macro he was using and that is now deprecated. He won't know to select the Deprecated category unless he reads the release notes.
Thanks, Marius
On Sat, Jul 15, 2017 at 5:06 PM, Vincent Massol <vincent@massol.net> wrote:
Hi devs,
Needs: * We need some “Deprecated” macro category so that users understand when a macro is deprecated and are less tempted to use it * We need to not show “Internal” macros by default to not “pollute” the Macro list by default
Proposal: * When the “All Macros” is selected display all macros *except* those from 2 categories: “Deprecated” and “Internal”. * If the user needs/wants to use those macros, he’ll need to explicitly select those categories. * When we want to deprecate a Macro we move it from its category to the “Deprecated” category, before removing it further in the future (when is to be defined on an adhoc basis)
Technical details: * Change https://github.com/xwiki-contrib/application-ckeditor/ blob/master/plugins/src/main/resources/xwiki-macro/macroSelector.js#L144 to implement this new behavior
WDYT?
Thanks -Vincent
On Sat, Jul 15, 2017 at 5:06 PM, Vincent Massol <vincent@massol.net> wrote:
Hi devs,
Needs: * We need some “Deprecated” macro category so that users understand when a macro is deprecated and are less tempted to use it
To be honest I would prefer to not have 'Deprecated' macros at all. If someone misses some macro he could install it from EM. We keep listing the Workspace macro for such a long time. When are we going to remove it?
* We need to not show “Internal” macros by default to not “pollute” the Macro list by default
Proposal: * When the “All Macros” is selected display all macros *except* those from 2 categories: “Deprecated” and “Internal”.
Currently in 'Internal' I see just the 'Template' macro. For me that's 'Development'. If it's internal and we don't want people to use it, why are we still displaying / bundling them? Thanks, Caty
* If the user needs/wants to use those macros, he’ll need to explicitly select those categories. * When we want to deprecate a Macro we move it from its category to the “Deprecated” category, before removing it further in the future (when is to be defined on an adhoc basis)
Technical details: * Change https://github.com/xwiki-contrib/application-ckeditor/ blob/master/plugins/src/main/resources/xwiki-macro/macroSelector.js#L144 to implement this new behavior
WDYT?
Thanks -Vincent
-- Denis Gervalle SOFTEC sa - CEO On Mon, Jul 17, 2017 at 13:23, Ecaterina Moraru (Valica) <valicac@gmail.com> wrote: On Sat, Jul 15, 2017 at 5:06 PM, Vincent Massol <vincent@massol.net> wrote:
Hi devs,
Needs: * We need some “Deprecated” macro category so that users understand when a macro is deprecated and are less tempted to use it
To be honest I would prefer to not have 'Deprecated' macros at all. If someone misses some macro he could install it from EM. We keep listing the Workspace macro for such a long time. When are we going to remove it?
* We need to not show “Internal” macros by default to not “pollute” the Macro list by default
Proposal: * When the “All Macros” is selected display all macros *except* those from 2 categories: “Deprecated” and “Internal”.
Currently in 'Internal' I see just the 'Template' macro. For me that's 'Development'. If it's internal and we don't want people to use it, why are we still displaying / bundling them? This is exactly the point. All macros are listed currently, and we might have some of them that are not intended to be used directly from the editor, but only helpful internally. We might also need to keep some because they are still in use by some pages, but we want to deprecate their usage. Vincent's proposal is a way to limit the visibility of these macros in the Macro editor, in order to clean the list and avoid confusion. -- Denis Gervalle SOFTEC sa - CEO Thanks, Caty
* If the user needs/wants to use those macros, he’ll need to explicitly select those categories. * When we want to deprecate a Macro we move it from its category to the “Deprecated” category, before removing it further in the future (when is to be defined on an adhoc basis)
Technical details: * Change https://github.com/xwiki-contrib/application-ckeditor/ blob/master/plugins/src/main/resources/xwiki-macro/macroSelector.js#L144 to implement this new behavior
WDYT?
Thanks -Vincent
On 17 Jul 2017, at 13:23, Ecaterina Moraru (Valica) <valicac@gmail.com> wrote:
On Sat, Jul 15, 2017 at 5:06 PM, Vincent Massol <vincent@massol.net> wrote:
Hi devs,
Needs: * We need some “Deprecated” macro category so that users understand when a macro is deprecated and are less tempted to use it
To be honest I would prefer to not have 'Deprecated' macros at all.
I think you’re missing the use case and that’s why we still have the Spaces Macro in the Standard flavor (for example): * Imagine you have an XWiki 6.x installed * Now imagine you want to upgrade to 8.x * If we remove deprecated macros then suddenly after you upgrade your wiki you’ll get several pages failing with some red errors telling you that the macros are not available in your wiki. It’s the same reason why there are deprecations in Java: to not break users or developers. So yes we’ll be able to remove deprecated macros one day, when we judge that enough users have migrated to a recent versions and are no longer using the deprecated macros. I believe it’s still a bit too early for the Spaces macro for example (it was used by the Space Dashboard template for example). But it’s possible that once we have 9.x be the LTS, we could think about removing it. However there’ll always be use cases for deprecated macros.
If someone misses some macro he could install it from EM. We keep listing the Workspace macro for such a long time. When are we going to remove it?
I agree that we could remove it now. We just need to decide if we go to the extra effort of moving it to contrib or just drop it (I’d be in favor of just dropping it and wait for someone to ask for it - It’s still in the SCM in the history if we need it one day). Thanks -Vincent
* We need to not show “Internal” macros by default to not “pollute” the Macro list by default
Proposal: * When the “All Macros” is selected display all macros *except* those from 2 categories: “Deprecated” and “Internal”.
Currently in 'Internal' I see just the 'Template' macro. For me that's 'Development'.
If it's internal and we don't want people to use it, why are we still displaying / bundling them?
Thanks, Caty
* If the user needs/wants to use those macros, he’ll need to explicitly select those categories. * When we want to deprecate a Macro we move it from its category to the “Deprecated” category, before removing it further in the future (when is to be defined on an adhoc basis)
Technical details: * Change https://github.com/xwiki-contrib/application-ckeditor/ blob/master/plugins/src/main/resources/xwiki-macro/macroSelector.js#L144 to implement this new behavior
WDYT?
Thanks -Vincent
On 17 Jul 2017, at 13:42, Vincent Massol <vincent@massol.net> wrote:
On 17 Jul 2017, at 13:23, Ecaterina Moraru (Valica) <valicac@gmail.com> wrote:
On Sat, Jul 15, 2017 at 5:06 PM, Vincent Massol <vincent@massol.net> wrote:
Hi devs,
Needs: * We need some “Deprecated” macro category so that users understand when a macro is deprecated and are less tempted to use it
To be honest I would prefer to not have 'Deprecated' macros at all.
I think you’re missing the use case and that’s why we still have the Spaces Macro in the Standard flavor (for example):
* Imagine you have an XWiki 6.x installed * Now imagine you want to upgrade to 8.x * If we remove deprecated macros then suddenly after you upgrade your wiki you’ll get several pages failing with some red errors telling you that the macros are not available in your wiki.
It’s the same reason why there are deprecations in Java: to not break users or developers.
So yes we’ll be able to remove deprecated macros one day, when we judge that enough users have migrated to a recent versions and are no longer using the deprecated macros.
I believe it’s still a bit too early for the Spaces macro for example (it was used by the Space Dashboard template for example). But it’s possible that once we have 9.x be the LTS, we could think about removing it.
However there’ll always be use cases for deprecated macros.
FTR and the for the sake of being complete on this discussion, it’s possible to do what you want Caty, but we would need to implement something more complex: * During upgrade, find out if there are macros used (by searching in the wiki for example - but it’s not guaranteed we’ll find all places since the macro usage could be generated by script) that are not bundled anymore and if so propose in the DW UI a step to install them. Thanks -Vincent
If someone misses some macro he could install it from EM. We keep listing the Workspace macro for such a long time. When are we going to remove it?
I agree that we could remove it now. We just need to decide if we go to the extra effort of moving it to contrib or just drop it (I’d be in favor of just dropping it and wait for someone to ask for it - It’s still in the SCM in the history if we need it one day).
Thanks -Vincent
* We need to not show “Internal” macros by default to not “pollute” the Macro list by default
Proposal: * When the “All Macros” is selected display all macros *except* those from 2 categories: “Deprecated” and “Internal”.
Currently in 'Internal' I see just the 'Template' macro. For me that's 'Development'.
If it's internal and we don't want people to use it, why are we still displaying / bundling them?
Thanks, Caty
* If the user needs/wants to use those macros, he’ll need to explicitly select those categories. * When we want to deprecate a Macro we move it from its category to the “Deprecated” category, before removing it further in the future (when is to be defined on an adhoc basis)
Technical details: * Change https://github.com/xwiki-contrib/application-ckeditor/ blob/master/plugins/src/main/resources/xwiki-macro/macroSelector.js#L144 to implement this new behavior
WDYT?
Thanks -Vincent
On Mon, Jul 17, 2017 at 3:03 PM, Vincent Massol <vincent@massol.net> wrote:
On 17 Jul 2017, at 13:42, Vincent Massol <vincent@massol.net> wrote:
On 17 Jul 2017, at 13:23, Ecaterina Moraru (Valica) <valicac@gmail.com>
wrote:
On Sat, Jul 15, 2017 at 5:06 PM, Vincent Massol <vincent@massol.net>
wrote:
Hi devs,
Needs: * We need some “Deprecated” macro category so that users understand
when a
macro is deprecated and are less tempted to use it
To be honest I would prefer to not have 'Deprecated' macros at all.
I think you’re missing the use case and that’s why we still have the Spaces Macro in the Standard flavor (for example):
* Imagine you have an XWiki 6.x installed * Now imagine you want to upgrade to 8.x * If we remove deprecated macros then suddenly after you upgrade your wiki you’ll get several pages failing with some red errors telling you that the macros are not available in your wiki.
It’s the same reason why there are deprecations in Java: to not break users or developers.
So yes we’ll be able to remove deprecated macros one day, when we judge that enough users have migrated to a recent versions and are no longer using the deprecated macros.
I believe it’s still a bit too early for the Spaces macro for example (it was used by the Space Dashboard template for example). But it’s possible that once we have 9.x be the LTS, we could think about removing it.
However there’ll always be use cases for deprecated macros.
FTR and the for the sake of being complete on this discussion, it’s possible to do what you want Caty, but we would need to implement something more complex: * During upgrade, find out if there are macros used (by searching in the wiki for example - but it’s not guaranteed we’ll find all places since the macro usage could be generated by script) that are not bundled anymore and if so propose in the DW UI a step to install them.
yes, interesting :) but as you said more work. So, in this case, we should use just 1 category (not 2) - let's choose 'Deprecated'. This category should not be displayed in the Editor, but kept for backwards compatibility. In the Macros Index, we will display it there and also the macro will be findable with EM in the installed category. Actually I think we need some more generic rule regarding this 'Deprecation' topic, since it applies also on Panels.
From an usage perspective the "(Legacy)" or "Deprecated" wording on warning boxes, increases more the attention I give to that macro/panel instead of doing the exact opposite.
Thanks, Caty
Thanks -Vincent
If someone misses some macro he could install it from EM. We keep listing
the
Workspace macro for such a long time. When are we going to remove it?
I agree that we could remove it now. We just need to decide if we go to the extra effort of moving it to contrib or just drop it (I’d be in favor of just dropping it and wait for someone to ask for it - It’s still in the SCM in the history if we need it one day).
Thanks -Vincent
* We need to not show “Internal” macros by default to not “pollute” the Macro list by default
Proposal: * When the “All Macros” is selected display all macros *except* those
from
2 categories: “Deprecated” and “Internal”.
Currently in 'Internal' I see just the 'Template' macro. For me that's 'Development'.
If it's internal and we don't want people to use it, why are we still displaying / bundling them?
Thanks, Caty
* If the user needs/wants to use those macros, he’ll need to explicitly select those categories. * When we want to deprecate a Macro we move it from its category to the “Deprecated” category, before removing it further in the future (when is to be defined on an adhoc basis)
Technical details: * Change https://github.com/xwiki-contrib/application-ckeditor/ blob/master/plugins/src/main/resources/xwiki-macro/ macroSelector.js#L144 to implement this new behavior
WDYT?
Thanks -Vincent
On 17 Jul 2017, at 14:14, Ecaterina Moraru (Valica) <valicac@gmail.com> wrote:
On Mon, Jul 17, 2017 at 3:03 PM, Vincent Massol <vincent@massol.net> wrote:
On 17 Jul 2017, at 13:42, Vincent Massol <vincent@massol.net> wrote:
On 17 Jul 2017, at 13:23, Ecaterina Moraru (Valica) <valicac@gmail.com>
wrote:
On Sat, Jul 15, 2017 at 5:06 PM, Vincent Massol <vincent@massol.net>
wrote:
Hi devs,
Needs: * We need some “Deprecated” macro category so that users understand
when a
macro is deprecated and are less tempted to use it
To be honest I would prefer to not have 'Deprecated' macros at all.
I think you’re missing the use case and that’s why we still have the Spaces Macro in the Standard flavor (for example):
* Imagine you have an XWiki 6.x installed * Now imagine you want to upgrade to 8.x * If we remove deprecated macros then suddenly after you upgrade your wiki you’ll get several pages failing with some red errors telling you that the macros are not available in your wiki.
It’s the same reason why there are deprecations in Java: to not break users or developers.
So yes we’ll be able to remove deprecated macros one day, when we judge that enough users have migrated to a recent versions and are no longer using the deprecated macros.
I believe it’s still a bit too early for the Spaces macro for example (it was used by the Space Dashboard template for example). But it’s possible that once we have 9.x be the LTS, we could think about removing it.
However there’ll always be use cases for deprecated macros.
FTR and the for the sake of being complete on this discussion, it’s possible to do what you want Caty, but we would need to implement something more complex: * During upgrade, find out if there are macros used (by searching in the wiki for example - but it’s not guaranteed we’ll find all places since the macro usage could be generated by script) that are not bundled anymore and if so propose in the DW UI a step to install them.
yes, interesting :) but as you said more work.
So, in this case, we should use just 1 category (not 2) - let's choose 'Deprecated’.
We still need 2. “Internal” is different from “Development”. “Development” is for end users, while “Internal” are wiki macros that are not public and that we don’t want to expose. In practice I think we should not even list them in the Macro Browser (that would be another jira issue).
This category should not be displayed in the Editor, but kept for backwards compatibility.
I think it’s still interesting for users to see Deprecated macros but that could be argued. Right now I’m leaning towards showing the Deprecated category.
In the Macros Index, we will display it there and also the macro will be findable with EM in the installed category.
Note that EM is only for Admins and the Macros Index is hidden in the Help ATM and not a visible feature (as is Page Index, etc) -And I don’t think it deserves more visibility since we have the Macro Browser.
Actually I think we need some more generic rule regarding this 'Deprecation' topic, since it applies also on Panels.
Sure, what do you propose? Note that I’ve already made up one rule: display the deprecation using a warning box and explain what’s the replacement.
From an usage perspective the "(Legacy)" or "Deprecated" wording on warning boxes, increases more the attention I give to that macro/panel instead of doing the exact opposite.
FTR, I’ve removed “Legacy” from the macro name since it’s now in the Deprecated category. Thanks -Vincent
Thanks, Caty
Thanks -Vincent
If someone misses some macro he could install it from EM. We keep listing
the
Workspace macro for such a long time. When are we going to remove it?
I agree that we could remove it now. We just need to decide if we go to the extra effort of moving it to contrib or just drop it (I’d be in favor of just dropping it and wait for someone to ask for it - It’s still in the SCM in the history if we need it one day).
Thanks -Vincent
* We need to not show “Internal” macros by default to not “pollute” the Macro list by default
Proposal: * When the “All Macros” is selected display all macros *except* those
from
2 categories: “Deprecated” and “Internal”.
Currently in 'Internal' I see just the 'Template' macro. For me that's 'Development'.
If it's internal and we don't want people to use it, why are we still displaying / bundling them?
Thanks, Caty
* If the user needs/wants to use those macros, he’ll need to explicitly select those categories. * When we want to deprecate a Macro we move it from its category to the “Deprecated” category, before removing it further in the future (when is to be defined on an adhoc basis)
Technical details: * Change https://github.com/xwiki-contrib/application-ckeditor/ blob/master/plugins/src/main/resources/xwiki-macro/ macroSelector.js#L144 to implement this new behavior
WDYT?
Thanks -Vincent
Done in: * https://jira.xwiki.org/browse/CKEDITOR-176 * https://jira.xwiki.org/browse/XWIKI-14561 Thanks -Vincent
On 15 Jul 2017, at 16:06, Vincent Massol <vincent@massol.net> wrote:
Hi devs,
Needs: * We need some “Deprecated” macro category so that users understand when a macro is deprecated and are less tempted to use it * We need to not show “Internal” macros by default to not “pollute” the Macro list by default
Proposal: * When the “All Macros” is selected display all macros *except* those from 2 categories: “Deprecated” and “Internal”. * If the user needs/wants to use those macros, he’ll need to explicitly select those categories. * When we want to deprecate a Macro we move it from its category to the “Deprecated” category, before removing it further in the future (when is to be defined on an adhoc basis)
Technical details: * Change https://github.com/xwiki-contrib/application-ckeditor/blob/master/plugins/sr... to implement this new behavior
WDYT?
Thanks -Vincent
participants (4)
-
Denis Gervalle -
Ecaterina Moraru (Valica) -
Marius Dumitru Florea -
Vincent Massol