Create a "How to handle errored changesets” doc page

Created by: mrnugget

We talked about this in Slack, where Christine asked:

If a user runs a campaign which only partially completes due to permission issues, then updates their permissions on the previously failing repos, what is the best next step? Can they reapply the campaign if there are no changes to the spec? Do they have to close the campaign and start again?

I replied:

You can reapply and the errored changesets will be retried. (Reapply by using src campaign [preview|apply], not by using the old preview URL and clicking the “apply” button again)

Most errors are also automatically retried, except “non retryable” errors, such as these: executor.go

Generally speaking: src campaign [apply|preview] should be idempotent, so you can run it as often as you want and if you didn’t change anything in your spec, nothing should happen, except when there’s a failing changeset, that will be retried.

And, in case you didn’t know this, we also try to be Smart ™️ in src-cli and if we have to rerun something, we try to do the minimum amount of work. Example: you ran steps over 10 repositories, created the changesets on the code hosts, now you want to update the changesetTemplate.title. src-cli will try to leverage the local cache in that case and not rerun the steps, but instead use the cached results to only update the changeset spec (= the rendered version of diff + changesetTemplate) attributes that have changed.

Oh and big exception that is worth mentioning: if the repositoriesMatchingQuery return repositories with updated base branches, we do rerun the steps (because if someone pushed something to, say, main, we don’t know that our steps will produce the same result as before). That could be a problem on super busy repositories (mental note for monorepo work!), but so far it wasn’t.

We should put this into a docs page.