Add support for generating READMEs too

[AadithyaSai]

The existing automatic wiki generation feature is great, but having an option to generate READMEs for released modules will be a great addition. This is handy for situations where you may want to maintain READMEs separately or keep wikis disabled (such as for private repos under the free plan).

[virgofx]

Thanks for the feature request! This would be a valuable addition, especially for users with private repos on free plans or those who prefer to keep wikis disabled.

I want to make sure I understand what you're looking for, especially since this is related to #275 (CHANGELOG.md generation).

Key question: How should the README.md be delivered?

I see a few possible approaches:

1. Auto-commit to module directories after PR merge (e.g., aws/vpc/README.md)

   • Automatically committed to the merged branch as a separate commit
   • Would require bypassing branch protections (need to see if this is possible from the github-bot -- it may not be and thus require a PAT to be used)
   • Most automated but least flexible

2. Provide as action output

   • README content available as a workflow output (similar to our existing changed-modules-map output)
   • You handle the commit in your own workflow step
   • More flexible but requires additional setup

3. Commit during the PR (before merge)

   • README changes become part of the PR itself
   • Subject to normal review process
   • Would require pushing to the PR branch
   • I think this may be the best approach but curious to your thoughts?

Also curious about:

• Should the README mirror the wiki structure (usage, terraform-docs, changelog), or would you prefer different content?
• If a module already has a README.md, should we overwrite it, update specific sections, or skip it?
• Should both wiki and README generation be enabled simultaneously, or is this meant to replace wikis?

The same delivery mechanism questions apply to #275 as well, so understanding your preferred approach here would help guide both features.

What are your thoughts on these options?

[AadithyaSai]

Key question: How should the README.md be delivered?

I beleive approach 3 would be the most ideal. 2 certainly has the most flexibility but adds an unnecessary level of complexity in my opinion. 3 would be idiomatically the most similar to what the github action currently does.

I believe, for 3 to work, however, the action would need to generate READMEs every time the PR is opened, reopened or synced instead of before the merge as i don't believe github provides any triggers that occur before the merge.

• Should the README mirror the wiki structure (usage, terraform-docs, changelog), or would you prefer different content?

For the most part, mirroring the wiki content works just fine for README files. Having the ability to create a template README file would be very handy too.

• If a module already has a README.md, should we overwrite it, update specific sections, or skip it?

As READMEs can contain other miscellaneous details about the module, I think allowing for README templates (such as how terraform-docs uses the inject feature) would be the best way to implement it, but keeping options to overwrite or skip it can be helpful too. It would add a layer of complexity for development though.

• Should both wiki and README generation be enabled simultaneously, or is this meant to replace wikis?

I don't believe it can replace wikis, after all wikis have a more robust sidebar and navigation experience compared to READMEs. There would be a fair degree of redundancy of information as well with both wikis and READMEs enabled so i think it is best to keep it as a feature flag that can be optionally disabled/enabled.

[virgofx]

Super helpful, thanks for the response @AadithyaSai. There's a reason I never implemented this originally. Lots of considerations.

The ONLY downside I see is that if you end up working on a branch to do work in Terraform and then you push your branch, create a PR, and then the action automatically adds a new commit to update the README.md, and then you realized you missed something in your branch, one would then need to merge/rebase the latest changes before committing new local changes and pushing again (Since the origin would have a new github[bot] based commit on top).

That's the benefit of doing option # 1 - the downside, I don't think it's possible with github[bot] (requires PAT from another service account/user to handle issues where most repositories use branch protection/rulesets to block commits directly to default branch - which is what would have to happen in this case)

I'm wondering if there's any other way to do this cleanly

---

Edit: Another thought I had , we could do a hybrid of # 3 option as well where we create the commit in a new/temporary branch and on merge, a new PR get's created. This solves the issue of keeping ones local branch history clean; but introduces 2 PRs now for each terraform module change.

Maybe we provide both as separate options?

[AadithyaSai]

You're right, the remote will have commits that are not in local, and will need to be synced again. I feel like the solution works fine though as ideally, devs wouldn't be editing the README manually and hence create conflicts.

method 1 works fine however if we can securely bypass the branch protection rules. Aside from PATs, it appears we could also use GitHub Apps or Deploy Tokens for bypassing branch protection as mentioned here.

The hybrid approach would create a lot of unnecessary PRs, which might trigger the Pull Request event and run the releaser pipeline unnecessarily, wasting action minutes on it. We'd need to implement a way to differentiate the automatically generated PRs from real PRs devs create.