Update expect list

Prior to v0.0.18, the action reports a comment which includes a posix(ish) shell command to update the expect list.

It would be much nicer if one could click something and have the action update the expect list.

As of v0.0.18, you can enable this with:

    with:
      experimental_apply_changes_via_bot: 1

Implementation

Comment handling

This is implemented today in prerelease:

🤖 posts a comment (as it does today)
🤖 gets its url (🌟 implemented in prerelease)
🤖 update the comment with the url and instructions saying roughly "reply quoting this line" (🌟 implemented in prerelease)
🤺 user performs the action above
🤖 responds to the action by retrieving the comment (based on the url which is encoded in the reply)
➡ proceed to work

Commit implementation

Retrieve the shell script from the comment, run its equivalent, git add -u, commit.
The command (which used to be posix shell) is now Perl
With the command retrieved from the comment
Perform the command equivalent (the command is refactored so that the same code can be shared between the two code paths)
I don't intend to delete empty files, as they represent structure even if they're temporarily empty.
Record the changes (git add -u)
Create a commit:
- Committer will be the bot
- Author will be the user who commented (need to get username + email address)
- Date will be the comment's date
- Message will be something like:
```
Applying automated check-spelling metadata updates

Commands as per <bot-comment-url>
Accepted in <user-comment-url>
```
Git push

Constraints

Commit Credentials

One can push to GitHub using two mechanisms:

HTTPS tokens
SSH keys

HTTPS tokens

Historically HTTPS tokens could have been a user's password, but support for that was removed a while back.

HTTPS tokens can be a personal access token with various arbitrary permissions or the GITHUB_TOKEN.

`GITHUB_TOKEN`

The GITHUB_TOKEN. can allow pushes, but when used, it doesn't trigger other workflows, which means it's problematic for automatic updates.

This mode will trigger a Disclaimer about missing status.

To enable a smoother approach, the repository can be configured to use a read-write deploy key.

SSH keys

SSH keys can be user keys, or deploy keys.

Deploy keys can be read-only or read-write.

⚠️ Note that if you use ssh-key, it should be a valid private key file (not a PAT/GITHUB_TOKEN). As of v0.0.21, check-spelling won't actively complain/warn if you pass a PAT, but it doesn't guarantee that it will work either. A future version may use ssh-keygen -y -f file to validate the input...

read-write deploy key

Using a read-write deploy key should allow @check-spelling-bot to update your PR and also trigger workflows. This will be the recommended approach as of v0.0.20 or thereabouts.

Essentially, this involves:

Creating an encrypted secret -- be mindful of the secret naming constraints, e.g., CHECK_SPELLING.
Changing the workflow for the update comment handler's uses: action/checkout step to provide the secret, e.g.:

- name: checkout
  uses: actions/checkout@v3
  with:
    ssh-key: "${{ secrets.CHECK_SPELLING }}"

read-write deploy key limitations

ℹ️ This will only work if the pull request source and destination are in the same repository. If you're reading this and were trying to make a pull request from a fork into a different repository and would like to take advantage of this feature, you can follow these steps:

Go to your fork (your-fork).
If necessary, Enable workflows in your fork
Create a read-write deploy key
Create a secret using the public key for the deploy key using the name of the secret from the check-spelling workflow
Create a pull request in your fork (your-fork) from the same branch (head-branch) as in the upstream pull request, targeting the same base branch (destination-branch) as the upstream (upstream-fork) pull's base branch (destination-branch).
Follow the instructions from the workflow in order to seamlessly update your branch -- doing this will update the branch, and thus should update the branch in the upstream PR and trigger workflows in it.

Comment limit

GitHub returns an error if the comment is too long:

"body is too long (maximum is 65536 characters)"

This functions as a limit on the number of words reported initially.

Also, duplicating the words to expect list is just ugly.

Once the comment is effectively self-aware, the command is able to retrieve the bullet list instead of encoding the words twice.

CheckRunEvent: action

While it seems like it'd be nice to use: GitHub's CheckRunEvent: action which offers a way to implement fix-it functionality.

I'm not sure if that's available for GitHub Actions.

⛈ I couldn't find a way to do this

Reaction handling

It'd be really shiny if someone could click the 😶 and select the 🚀 Reaction to trigger this.

⛈ Unfortunately, the Reactions preview doesn't appear to support this functionality.

Create a PR for the PR / branch

I may need to add fallback code whereby I create / recycle a branch (based on the name of the PR/branch) and then open a PR against the original branch. (I'll revisit this based on feedback)

Downsides

Required checks

If you have set the spell checker check as mandatory, you're going to need to add a dummy commit to the end of the branch, otherwise the spell checker will not run again and validate that it's happy with the branch.

The best dummy change is a blank line in the expect file itself. It will have minimal impact on blame, should be an easy merge conflict to resolve, and another pass of this feature will wipe it out.

I see a lot of people running the commands blindly and missing the fact that there are real misspellings in the output.

Part of this is that they aren't used to looking at the output.

check-spelling-docs

Documentation for check-spelling