Imports Validation Schemas into the Examples README during CI

[JBBianchi]

Many thanks for submitting your Pull Request ❤️!

Please specify parts of this PR update:

• Specification
• Schema
• Examples
• Extensions
• Roadmap
• Use Cases
• Community
• TCK
• Other (CI workflows)

Discussion or Issue link:
#801

What this PR does / why we need it:
At the moment, examples are located both in the README and in files for the verification pipeline of the CI.
This means one change needs to be applied to 3 locations: the README json sample, the README yaml sample and the example json file.

This PR adds the possibility to reference external files thanks to an include tag.

When a pull request is merged and at least an example file has been modified, a script will render README_TEMPLATE.md and replace README.md with the output (in the example folder).

This means modifications should not be applied manually to README.md anymore but to the TEMPLATE instead. To try and prevent users from modifying the README directly, a disclaimer header is added to the file and a specific CI check is run when a pull request is opened and the README has been modified.

For the template, the include tag have two attributes:

• file (string) the file to render in place of the tag
• format (string: json | yaml) if the file should be rendered as JSON or YAML

e.g.: <include file="event-based-greeting.json" format="json" />

When the CI workflow is run, a bot will push a signed commit to a branch and open a PR. To do so, the owners of this repository have to:

• Create a (bot) account
• Add the bot to the repository (and organization ?) collaborators
• Validate the invite with the bot account
• Create a signing key for the bot and add the public key in the bot account settings
• Generate a Personal Access Token for the bot
• Add some secrets in the repository:
  • BOT_USERNAME - The GH username of the bot
  • BOT_EMAIL - The email associated to the GH account of the bot
  • BOT_PAT - The personal access token of the bot
  • BOT_GPG_PRIVATE_KEY - The private key used to sign commits

Special notes for reviewers:

Additional information:

[ricardozanini]

@JBBianchi I guess for this first PR it's expected that Check examples.... would fail, correct? Since you must edit it anyway.

Maybe we can add a boolean check in the commit message to skip this check? So on a time when we need to edit this file we won't get this big red flag 🤔

EDIT: as we discussed in the meeting, the PR will be red now since we must edit the README file for the first commit. Upcoming changes will be at README_TEMPLATE.md

[cdavernas]

Rock n Roll

[github-actions]

This pull request has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[ricardozanini]

@cdavernas I think we can merge this, it's passed more than 2 weeks :)