What's New Feature
Description
Requirements
Main goal: bring XWiki news to the XWiki users, right into the XWiki product.
Requirements for MVP
UC1: Display a "What's New" entry in the UI to let users see what's new in XWiki
UC2: Allow several sources of information to be displayed and make it configurable
UC3: Make it possible to opt-out and remove "what's new" from the UI
UC4: Bundled by default in XS (as otherwise it would defeat the main goal of pushing information to users)
UC6: Allow for curated news content (only display curated news content and not all news from the news source)
UC7: Automatically refresh news regularly (and make the refresh schedule configurable)
UC8: Default sources. By default, enable xwiki.org community news and paid apps news from XWiki SAS (as the top sponsoring company)
Advanced requirements (future versions)
UC5: Pagination for the news displayed
UC100: Allow admins to choose the news sources to display in the wiki
UC101: Ability to filter out news so that only news compatible with the current XWiki version are displayed (Admin UI option)
UC102: Ability to filter news automatically depending on the user type (simple, advanced, admin) (Admin UI option)
UC103: Ability to filter news depending on defined categories (e.g. development, admin, advanced, extension, paying, upgrades, etc) (Admin UI options)
UC104: Ability for users to filter the displayed news (i.e. filter based on selected categories)
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)
UC106: When new news is available, make them visible in the UI so that users can see what they have not read/seen yet
UC107: Add the ability to contribute new News sources dynamically (without requiring a new version of the What's New extension)
UC108: When new News sources are available, notify the wiki admins
UC109: Multilingual sources. Ability to display news in the language of the current logged-in user
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)
- 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.
- An idea would be to add links to the documentation on xwiki.org in that help menu
- Vincent: my preference goes to option 1 FTM (for version 1), because it's simpler
- When clicking on "what's new", close the menu and open a new drawer to display the news as it's done in gitlab
- What to display: title, content, published date, categories, author, origin URL, and an optional image
UC2
- Technical: Create a Component Role for that.
- Allows customizations to add custom sources (e.g. XWiki SAS could add their own blog as a source for their clients using XWiki)
- 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.
- 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.
- 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.
- 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.
UC3
- At the minimum we need to implement the feature as an extension, bundled by default but optional, and that can be uninstalled
- At most, add an Admin UI to disable it
- 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.
- For the MVP the idea (also allows implementing UC2) is to define a configuration at the level of xwiki.properties. For example:whatsnew.sources = xwikiorg = xwikiblog
whatsnew.source.xwikiorg.rssURL = https://extensions.xwiki.org/news
whatsnew.sources = xwikisas = xwikiblog
whatsnew.sources.xwikisas.rssURL = https://xwiki.com/newsThe format is:
- whatsnew.sources = <some id to identify the source>:<source type, component hint>
- whatsnew.sources.<some id to identify the source>.<parameter key> = <parameter value>
The parameter keys and values depend on the source type. For a xwikiblog type, it's:
- rssURL = <url to get the RSS feed>
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):
whatsnew.sources =
UC4
- Needs a proposal/vote on the forum
UC5
- Option 1: Display N news and then more button to load N more news.
- 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
- For example for the xwiki.org Blog source, only retrieve news published in the "what's news for XWiki" category
- Control who can publish news
- The xwiki.org blog is not open to everyone (only committers and special users).
- If some non-committers want to publish news, they could ask for it and we could add them as special users
RSS 2.0 supports everything we need to hold our metadata:
- language:
language channel tag
- origin URL:
link item tag
- publication date:
pubDate item tag
- author:
author item tag
- image:
category item tag (e.g. <category domain="http://www.fool.com/cusips">MSFT</category>)
- xwiki version:
category item tag
- categories:
category item tag
- 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.
- Check how https://validator.w3.org/feed/docs/rss2.html#ltcloudgtSubelementOfLtchannelgt works
- 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
Source 2: "what's new" category of the forum at https://forum.xwiki.org/c/news/11--- 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.
- Discussed at https://forum.xwiki.org/t/forum-vs-blog-for-news/11669
- Source 3: store.xwiki.com blog
- 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.
- 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.
- Specifications:
- The format is RSS (the same format as the XWiki Blog Application)
- The categories returned in the RSS must be:
- What's New for XS
- What's New for XS:Admin User
- What's New for XS:Simple User
- What's New for XS:Advanced User
- What's New for XS:Extension
- The RSS URL must support the following filtering criteria:
- category. Can be specified multiple times to specify filtering on several categories
- xwikiVersion. The version of XWiki for which to return news for
- targetUser. The reference of the target user for which to return news for
- count. Number of news items to return
UC110
- See https://github.com/xwiki/xwiki-platform/commit/e4e31d85f75f7168c82c664ea7fc5a1958fa195b#r99804578
UI
See Design of What's new feature.
New Ideas to decide
- Adding a link to the news sources at the bottom of the what's new page. Suggested by Michael.