Add EXPERIMENTAL disclaimer to experimental packages and apps `README.md`s

stevepiercy commented 4 months ago

See https://github.com/plone/volto/pull/6069#issuecomment-2150557525

The following is a list of all apps and packages in the monorepo. I don't know which are experimental. @sneridagh can you indicate which are experimental or not?

Apps with README.md

[x] apps/nextjs/README.md
[x] apps/plone/README.md
[x] apps/remix/README.md
[x] apps/vite/README.md
[x] apps/vite-ssr/README.md

Packages with README.md

[x] packages/blocks/README.md
[ ] packages/client/README.md
[ ] packages/components/README.md
[x] packages/coresandbox
[ ] packages/generator-volto/README.md
[x] packages/helpers/README.md
[x] packages/providers/README.md
[ ] packages/registry/README.md
[ ] packages/scripts/README.md
[x] packages/slots/README.md
[x] packages/tsconfig/README.md
[ ] packages/types/README.md
[ ] packages/volto-slate/README.md

Packages with no README.md

[ ] packages/volto # We use /README.md for this. Not experimental.
[ ] packages/volto-guillotina
[ ] packages/volto-testing

After determining which items are experimental, we need to create or update its README.md to explicitly state something to the following effect.

## EXPERIMENTAL

This package or app is experimental.
The community offers no support whatsoever for it.
Breaking changes may occur without notice.

sneridagh commented 1 week ago

@stevepiercy I'm adding the experimental note to all of them I marked the experimental ones. I did it in here, as I was doing a bit of housekeeping too. https://github.com/plone/volto/pull/6069

stevepiercy commented 1 week ago

@sneridagh I found that GitHub has special markdown for admonitions.

https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts

> [!WARNING]
> This package or app is experimental.
> The community offers no support whatsoever for it.
> Breaking changes may occur without notice.

That should be the standard going forward.

sneridagh commented 1 week ago

Changed to the GH admonitions in https://github.com/plone/volto/pull/6069

stevepiercy commented 1 week ago

@sneridagh are any of the remaining unchecked items above "experimental"?

sneridagh commented 1 week ago

No, they are not. Some are in alpha (types, client) but not experimental. The other are "stable".

stevepiercy commented 1 week ago

Should the alpha ones be designated as such in their readmes?

sneridagh commented 1 week ago

@stevepiercy probably, it would be good to do that. If the intent is not clear, also state it. If feedback from the alpha is needed, as well...

plone / volto