Troubleshooting WAI Pull Request Previews

Generated PRs falling out of sync

This issue is being tracked in wai-aria-practices#219: PRs triggered by aria-practices falling out of sync. The issue is the following:

If there are breaking changes introduced to the main branch during the lifetime of a generated preview PR, there is a chance it may fail to build on subsequent updates because it does not include the changes required for it to operate as expected, which would be coming from main.

How to fix

This can be addressed in 2 different ways:

1. Updating the generated PR branch and re-run the preview link update

1. For the aria-practices pull request, find the matching generated wai-aria-practices pull request to then determine the branch to update. This can be found in any of the following ways:
   1. You can check the url of the generated preview, where it will be https://deploy-preview-xxx--aria-practices.netlify.app. xxx here would also be the matching generated PR number in w3c/wai-aria-practices list of Pull Requests, so https://github.com/w3c/wai-aria-practices/pull/xxx. The generated branch will be shown for you to then checkout that branch.
   2. The wai-aria-practices branch names are generated based on the triggering aria-practices PR's branch name that triggered it, with a apg/ prepended to the name. So if the aria-practices branch's name is testing, the wai-aria-practices branch's name would be apg/testing. You can confirm the matching branch has generated a pull request that's being used in aria-practices and then checkout that branch.
2. You will then need to merge in the latest changes from wai-aria-practices default branch, main. If there are conflicts, you can opt to just take all the changes from either the generated PR branch or main, as the preview build will have to be re-ran. You just want to ensure any breaking preview build changes are captured from main.
   • There is no expectation that there are preview build changes on a generated PR branch as it should only be for serving updated content from the aria-practices pull request.
3. After updating the generated PR's branch, the preview link has to be regenerated. This can be done in several ways:
   1. Check the aria-practices pull request's Checks tab and select Trigger PR update for WAI-APG site. Re-run the job if you have the appropriate permissions to do so.
   2. Pushing an actual commit or simply pushing an empty commit to the aria-practices pull request to trigger a rebuild with the following git command: git commit --allow-empty -m "Trigger rebuild".
4. Wait for the new build to complete and it will update the aria-practices top comment as before. Confirm that the expected changes are now present in the generated preview link.

2. Removing the generated PR branch and re-run the generation

1. For the aria-practices pull request, find the matching generated wai-aria-practices pull request to then determine the branch to remove. This can be found in any of the following ways:
   1. You can check the url of the generated preview, where it will be https://deploy-preview-xxx--aria-practices.netlify.app. xxx here would also be the matching generated PR number in w3c/wai-aria-practices list of Pull Requests, so https://github.com/w3c/wai-aria-practices/pull/xxx. The generated branch will be shown. You can then remove that branch once you have the correct permissions to do so.
   2. The wai-aria-practices branch names are generated based on the triggering aria-practices PR's branch name that triggered it, with a apg/ prepended to the name. So if the aria-practices branch's name is testing, the wai-aria-practices branch's name would be apg/testing. You can confirm the matching branch has generated a pull request that's being used in aria-practices and then remove that branch.
2. After removing the generated branch, the preview link has to be regenerated. This can also be done in several ways:
   1. Check the aria-practices pull request's Checks tab and select Trigger PR update for WAI-APG site. Re-run the job if you have the appropriate permissions to do so.
   2. Pushing an actual commit or simply pushing an empty commit to the aria-practices pull request to trigger a rebuild with the following git command: git commit --allow-empty -m "Trigger rebuild".
3. Wait for the new build to complete and it will update the aria-practices top comment as before. Note that the preview link's url will now be different. Confirm that the expected changes are now present in the generated preview link.