Automatically update/deploy periodically or when there're doc changes upstream

[molant]

Problem

We need a way to automatically ingest changes in the documentation into the website.
There are 2 scenarios @erickzhao and I have identified:

• New documentation: A new PR should be opened with sidebars.js reflecting the new file. Human intervention is expected to approve the PR and/or update the file to the right locations. Alternatively, we could add default categories and improve the logic to move files around to automate this even more and auto-merge.
• Changes to existing docs: There are no real changes in the code of the repo but a new deployment should be triggered.

Proposed solution

The idea is to add a push webhook event from electron/electron to a new endpoint. This endpoint will check if:

• The changes are in the stable branch
• Modify the /docs folder

If so, it will trigger a respository_dispatch event with the type doc_changes and the SHA of the commit as part of the payload.

The GitHub action will do the following for the doc_changes type:

1. Update the SHA to the new one (we will store it in package.json)
2. Run npm run build
3. Creates a commit chore: update ref to docs (🤖)
4. Checks if there are changes in the markdown:
   • No changes (just package.json is modified) ➡ Pushes the commit directly to main
   • More changes (i.e.: sidebars.js is modified as well) ➡ Pushes the commit to the branch chore/docs-updates (it gets created if it does not exist). Then checks if there is an open PR for that branch and if not it creates it. Human intervention is expected to merge this PR

The following diagram should help better visualize the above:

Questions?

How to force a deploy in Heroku?

Because we are changing the SHA in package.json there is no need to force a deploy, it will be automatically kicked by Heroku.

What happens when there's a new major release?

We could configure the webhook to receive also the release event. The fields to validate are:

{
  "action": "published",
  "release": {
    "draft": false
    },
    "prerelease": false
  }
}

And release.tag_name should be >= than the current available version on npm (there could be a 30second-2min delay between GitHub and npm releases). The reason is that there could be a minor release from a previous version.
Because the fiddle prebuilt steps requires the latest version available we should probably wait until it is available (and add a timeout of a few minutes).
Another problem is that the payload of release does not seem to have the commit SHA (at least in the example) so we will need a way to find it.

[molant]

After talking with @MarshallOfSound the plan has slightly changed:

• instead of using a GA to deliver the payload, there will be a webhook. e/e will send the webhook to a new endpoint, and the endpoint will kick the GA in this repo via a repository_dispatch event
• we will pin to a particular SHA version upstream so Heroku can be triggered if there are any changes in the docs (new files, or markdown changes).

There's the question on how to automatically merge PRs if needed (i.e.: when there's only markdown content changes). There are a couple alternatives we need to investigate (like triggering another repository_dispatch event)

I've updated the initial issue to reflect this changes and added a diagram that hopefully makes things easier to understand.