search

q-shift / backstage-plugins

Apache License 2.0
3 stars 7 forks source link

Improve how we manage the plugins README.md and the parent README.md #60

Closed cmoulliard closed 7 months ago

cmoulliard commented 8 months ago

TODO

Improve how we manage the plugins README.md and the parent README.md

Description

Do you see a trick to merge the content of a README.md from subfolders into the parent README.md ?

Why ? To be able to see the README page of a backstage plugin: front, console or backend (= subfolder of a git repository) on npmjs.org BUT also to see the whole documentation here on main

jacobdotcosta commented 8 months ago

Would it do to implement a template/macro based solution?

The solution could be to have a markdown template with the main README.md contents and includes to the different sub-folder README.md files. Generating the final README.md file could either be done locally using with a PR or during the release process.

Something like what's proposed on this stackoverflow comment that uses the GNU M4 macro processor.

cmoulliard commented 8 months ago

Can you create a small prototype using m4 tool ? Is m4 available part of the ubuntu image used by the github jobs ? @jacobdotcosta

jacobdotcosta commented 7 months ago

@cmoulliard , I created a sample using the GNU M4 macro processor.

On the jacobdotcosta/github-workflow-test project there is a template file named README.m4.template.md that generates the README.m4.result.md markdown. The includes are implemented at the bottom of the template to add the 3 README of the plugins to the file.

include(""""./plugins/quarkus/README.md""")
include(""""./plugins/quarkus-backend/README.md""")
include(""""./plugins/quarkus-console/README.md""")

The command used to generate the result markdown was the following.

$ m4 README.m4.template.md > README.m4.result.md
cmoulliard commented 7 months ago

Can you then add enhance our existing flow(s) to include a step to executed when the commit or PR includes *.md changes to generate the new root md file and push it as change ?

jacobdotcosta commented 7 months ago

I was wondering, should the main README.md file be updated only when the PR is merged?

@cmoulliard

cmoulliard commented 7 months ago

I was wondering, should the main README.md file be updated only when the PR is merged?

If we don't push a commit directly but we use only PR, then I'm fine to make the change when merged