Hello all,
Since 18.0.0RC1 we are publishing npm packages to www.npmjs.com.
Consequently, people can access a page for each published package (for instance, www.npmjs.com/package/@xwiki/platform-uniast-api).
Currently, visitors are welcomed with a This package does not have a README. Add a README to your package so that users know how to get started. message, which is not really friendly.
Therefore, I propose to make sure to have a README.md file included at the root of each package.
Options
Option 1: minimal technical content
The README.md is always the same, with a short sentence and a link to xwiki.org.
Pros:
- less developer work
Cons: - low value in the content
- harder to automate (fwiu, we’d need to have a pre-publication step where we copy a common README.md file at the root of the packages).
Option 2: template based
When publishing extensions to an XWiki extension store, we have to provide:
- an extension name
- an extension description
- a category
Therefore, it makes sense to provide the same details for npm packages, this would mean maintaining manually a README.md file at the root of each package, following a template the would coarsly look like
# ${EXTENSION_NAME}
${EXTENSION_DESCRIPTION}
[Documentation](${EXTENSION_DOCUMENTATION_URL})
Pro:
- Nicer package page content
- Easier to automate (nothing to do except remembering to have this README).
Cons: - More developer work (but not more than for any other extension)
Conclusion
I’m +1 for option 2 as it seems to be the best approach while not asking for more work that what we have to do for other artifacts we publish publicly.
If agreed on, I volunteer to:
- Document the rule
- Apply it on existing packages
WDYT? Thanks