search

DomT4 / homebrew-autoupdate

:tropical_drink: An easy, convenient way to automatically update Homebrew.
BSD 2-Clause "Simplified" License
968 stars 54 forks source link

Generate help command output for readme with github action #114

Closed swissbuechi closed 8 months ago

swissbuechi commented 8 months ago

After adding 2-3 features with new arguments I got to lazy to manually update the usage section in the README.md after every change.

So I've decided to write a simple github action which will handle the generation.

Usage

<!-- HELP-COMMAND-OUTPUT:START -->
...
<!-- HELP-COMMAND-OUTPUT:END -->

Implementation

Action The github action generate-help-output.yml will run on every push. If a change triggers a updates output of the homebrew autoupdate --help command, the action will create a commit and push the updated README.md file.

Script The python 3 script generate-help-output.py will generate the output of the --help command and compare it to the current output in the usage section of the README.md file.

I will add the required start and stop tags after the initial PR creation, so we can see the changes made by the action.

swissbuechi commented 8 months ago

Test

Tag not found

Here you can see what happens when the tag is not found: https://github.com/swissbuechi/homebrew-autoupdate/actions/runs/6829773030/job/18576552522

The same will happen if the content of the usage section is already up-to-date.

Tag found and content is outdated

Here is a run where it found the tag and updated the content of the usage section: https://github.com/swissbuechi/homebrew-autoupdate/actions/runs/6829880297/job/18576856651

This commit was made by the action: https://github.com/Homebrew/homebrew-autoupdate/pull/114/commits/4cf67494bddea1d8e99cd65cf895421d50836a78 Seems like there was already a small offset from the documentation compared to the real execution of the command.

Tag found and content is already up-to-date

I will make a small change on the README.md file to demonstrate this case. https://github.com/swissbuechi/homebrew-autoupdate/actions/runs/6829986114/job/18577163825 The commit and push will be skipped in this case.

Other error handling

Checkout the source code of generate-help-output.py, it should handle most common cases.

Know issues

A commit and push created by a github action will not trigger other actions. If this should be an isse, it can be solved by creating a Github App to do the commit like in this example:

GitHub App

GitHub App. To do this, you'll need to go to >https://github.com/settings/apps/new or https://github.com/organizations/<org>/settings/apps/new and create an app with the following settings:

  1. Uncheck Expire user authorization tokens
  2. Uncheck Webhook Active
  3. Set the following Repository permissions
    • Contents: Read & Write
    • Metadata: Read-only
    • Pull requests: Read & Write
    • Projects: Read-only

Once created, you'll need to generate a private key.

You'll then need to install the app to your account or org and add Action & Dependabot secrets for both the BOT_APP_ID and BOT_PRIVATE_KEY values which correspond to the App ID at the top of the page, and the private key you just created.

MikeMcQuaid commented 8 months ago

manually update the usage section in the README.md after every change.

Instead: remove this and link to https://docs.brew.sh/Manpage#autoupdate-subcommand-interval-options which is automatically updated.

swissbuechi commented 8 months ago

manually update the usage section in the README.md after every change.

Instead: remove this and link to https://docs.brew.sh/Manpage#autoupdate-subcommand-interval-options which is automatically updated.

I did not know this already existed. Thanks a lot!

Still was a lot of fun creating my solution 😀

I will create a new PR.