Move the SCM macro from xwiki.org to the Documentation Application

Development
,
1

Hi devs,

The {{scm}} macro, which builds a link to a file in an XWiki GitHub repository, is currently a wiki macro defined in a page of xwiki.org: https://www.xwiki.org/xwiki/bin/view/Macros/SCM

I’d like to propose moving it into the xwiki.org-specific module of the Documentation Application (GitHub - xwiki-contrib/documentation: Documentation Application used on xwiki.org · GitHub), for these reasons:

  • Documentation Application 1.15 adds a gitHubSCMLink check. It reports links to files of the xwiki and xwiki-contrib GitHub organizations that are written as URLs, and asks writers to use the SCM macro instead. So the app recommends a macro it doesn’t provide.
  • The macro would get versioned sources, tests and reviews, and could be documented in the new documentation tree, next to the Image and Deprecated macros.
  • We could modernize it while doing so: for example, it currently generates http://www.github.com and http://raw.github.com URLs.

Once the app version with the macro is installed on xwiki.org, the Macros.SCM page would be deleted, so that two macros don’t share the scm id. Existing usages wouldn’t change, since the macro id and parameters would stay the same.

WDYT?

Thanks

2

I’ve created DA-101: Move the SCM macro from xwiki.org to the Documentation Application by vmassol · Pull Request #47 · xwiki-contrib/documentation · GitHub and am ready to merge it.

3

+1 thanks

4

+1

5

I went through the macros used in the documentation, and this is the full list: image, gallery, display, include, code, plantuml, version, deprecated, embed and scm.

version, deprecated and image already live in the Documentation Application. scm is the only one left defined in a wiki page and not coming from XWiki/e. Makes sense to move to DocApp, thanks! I don’t think there is another one left to move.

6

Implemented thx.

TODO when v1.6 lands: