What's New Feature (Proposal.WhatsNewFeature)

1

= Requirements =

2

3

Main goal: bring XWiki news to the XWiki users, right into the XWiki product.

4

5

== Requirements for MVP ==

6

7

UC1: Display a "What's New" entry in the UI to let users see what's new in XWiki

8

UC2: Allow several sources of information to be displayed and make it configurable

9

UC3: Make it possible to opt-out and remove "what's new" from the UI

10

UC4: Bundled by default in XS (as otherwise it would defeat the main goal of pushing information to users)

11

UC6: Allow for curated news content (only display curated news content and not all news from the news source)

12

UC7: Automatically refresh news regularly (and make the refresh schedule configurable)

13

UC8: Default sources. By default, enable xwiki.org community news and paid apps news from XWiki SAS (as the top sponsoring company)

14

15

== Advanced requirements (future versions) ==

16

17

UC5: Pagination for the news displayed

18

UC100: Allow admins to choose the news sources to display in the wiki

19

UC101: Ability to filter out news so that only news compatible with the current XWiki version are displayed (Admin UI option)

20

UC102: Ability to filter news automatically depending on the user type (simple, advanced, admin) (Admin UI option)

21

UC103: Ability to filter news depending on defined categories (e.g. development, admin, advanced, extension, paying, upgrades, etc) (Admin UI options)

22

UC104: Ability for users to filter the displayed news (i.e. filter based on selected categories)

23

UC105: For "upgrade" news, only display them if the current XWiki instance has the extension installed and its version is lower than the version targeted by the news (Admin UI option)

24

UC106: When new news is available, make them visible in the UI so that users can see what they have not read/seen yet

25

UC107: Add the ability to contribute new News sources dynamically (without requiring a new version of the What's New extension)

26

UC108: When new News sources are available, notify the wiki admins

27

UC109: Multilingual sources. Ability to display news in the language of the current logged-in user

28

UC110: For the xwiki.org Blog source, allow changing the mappings of the categories without requiring a new version of XS

= Implementation =

== UC1 ==

* Option 1: As a new menu entry inside the Drawer menu. Pro: less clutter in the UI (since the Drawer menu already exists)

35

* Option 2: As a new menu next to the Alert menu, the Avatar icon and the Drawer menu. For example a menu with a question mark. Cons: More clutter in the UI. Pro: more visible. Would need to contain things other than just this to warrant a new menu.

36

** An idea would be to add links to the documentation on xwiki.org in that help menu

37

* Vincent: my preference goes to option 1 FTM (for version 1), because it's simpler

38

* When clicking on "what's new", close the menu and open a new drawer to display the news as it's done in gitlab

39

* What to display: title, content, published date, categories, author, origin URL, and an optional image

== UC2 ==

* Technical: Create a Component Role for that.

44

* Allows customizations to add custom sources (e.g. XWiki SAS could add their own blog as a source for their clients using XWiki)

45

* Implementation detail: Parse the RSS feed for the blog. The description is in HTML and can be rendered inside XWiki. Make sure to perform proper sanitization of the content to avoid dangerous things (javascript). Done by using the HTML macro.

46

** Michael: This needs a new feature to force-enable restricted cleaning, default cleaning in the HTML macro doesn't remove JavaScript. Alternatively, this could use the RSS macro (which already implements content filtering), possibly with some improvements as the needs seem common for displaying RSS feeds.

47

*** Vincent: The RSS macro currently displays a whole feed. We cannot reuse that since we can have various sources (not based on RSS). We would need a macro to display a single RSS item. The problem is that even that wouldn't work perfectly since we want to control how it's displayed, and give the ability for developers to customize this. I guess this could be implemented as a reusable macro but it feels better as a reusable API that the existing rss macro would call.

== UC3 ==

* At the minimum we need to implement the feature as an extension, bundled by default but optional, and that can be uninstalled

52

* At most, add an Admin UI to disable it

53

* Open question: Make it possible to be disabled per user in their user profile as a new tab. More complex to implement. Not sure it's useful.

54

* For the MVP the idea (also allows implementing UC2) is to define a configuration at the level of ##xwiki.properties##. For example:(((

55

56

whatsnew.sources = xwikiorg = xwikiblog

57

whatsnew.source.xwikiorg.rssURL = https://extensions.xwiki.org/news

58

whatsnew.sources = xwikisas = xwikiblog

59

whatsnew.sources.xwikisas.rssURL = https://xwiki.com/news

The format is:

* ##whatsnew.sources = <some id to identify the source>:<source type, component hint>##

65

* ##whatsnew.sources.<some id to identify the source>.<parameter key> = <parameter value>##

66

67

The parameter keys and values depend on the source type. For a ##xwikiblog## type, it's:

68

69

* ##rssURL = <url to get the RSS feed>##

70

71

To opt-out, it would be enough to add the following to ##xwiki.properties## (i.e. to override the default source configuration and not configure any source):

72

{{code language="properties"}}whatsnew.sources = {{/code}}

)))

== UC4 ==

* Needs a proposal/vote on the forum

== UC5 ==

* Option 1: Display N news and then more button to load N more news.

82

* Option 2: A la gitlab, when scrolling down and reaching the last news, auto load N more news

== UC6 ==

* The source should only retrieve a subset of news matching a given criteria

87

** For example for the xwiki.org Blog source, only retrieve news published in the "what's news for XWiki" category

88

* Control who can publish news

89

** The xwiki.org blog is not open to everyone (only committers and special users).

90

** If some non-committers want to publish news, they could ask for it and we could add them as special users

91

92

[[RSS 2.0>>https://validator.w3.org/feed/docs/rss2.html#requiredChannelElements]] supports everything we need to hold our metadata:

93

94

* language: (/) ##language## channel tag

95

* origin URL: (/) ##link## item tag

96

* publication date: (/) ##pubDate## item tag

97

* author: (/) ##author## item tag

98

* image~: (/) ##category## item tag (e.g. ##<category domain="http://www.fool.com/cusips">MSFT</category>##)

99

* xwiki version: (/) ##category## item tag

100

* categories: (/) ##category## item tag

101

* last time the news were updated: (/) ##lastBuildDate## channel tag

== UC7 ==

* Implementation: cache news (in memory for ex) + some low priority thread in charge of checking regularly if there are more news and if so to load them and put them in the cache.

106

* Check how https://validator.w3.org/feed/docs/rss2.html#ltcloudgtSubelementOfLtchannelgt works

107

* Idea: we could honor the ##ttl## metadata for the refresh, see https://validator.w3.org/feed/docs/rss2.html#ltttlgtSubelementOfLtchannelgt

== UC8 ==

* Source 1: xwiki.org blog

112

* --Source 2: "what's new" category of the forum at https://forum.xwiki.org/c/news/11-- --

113

** Problem: we have duplication today between the xwiki.org blog and the forum, we need to solve this first: either drop one of them or synchronize them.

114

** Discussed at https://forum.xwiki.org/t/forum-vs-blog-for-news/11669

115

* Source 3: store.xwiki.com blog

116

** See https://dev.xwiki.org/xwiki/bin/view/Community/Governance. We allow the top sponsoring company to contribute blog posts. We need to vote to decide if we allow it to have its source news configured by default.

117

** Note: https://dev.xwiki.org/xwiki/bin/view/Community/Governance already allows to display the xwiki.org blog in the XWiki runtime

== UC107 ==

* The idea is to support this at the level of each source implementation. For example for the ##xwikiorg## news source, its URL will return all the news, already aggregated.

122

* Specifications:

123

** The format is RSS (the same format as the XWiki Blog Application)

124

** The categories returned in the RSS must be:

125

*** ##What's New for XS##

126

*** ##What's New for XS:Admin User##

127

*** ##What's New for XS:Simple User##