chore: upstream synchronization action for forks

[utilbird]

Description

Adds a workflow action to automatically sync branches with upstream. Synchronization is performed nightly at 12AM, on PR opening/closing, and commits into PR'd branches.

This ensures pull requests based off toth-tech branches can be merged upstream without risk of merge conflicts. Should also slightly reduce repo maintainer workload, as synchronization will be done automatically.

I'll mirror this PR to all the other doubtfire repositories if approved

IMPORTANT

This checks a github workflow variable which is disabled/undefined by default, a repo maintainer/administrator will need to create a github action variable AUTOSYNC_UPSTREAM with the value true to enable this.

Caveat

Ironically, this workflow would temporarily(?) break 1:1 parity with upstream as the script needs to be present in the target branch (currently 10.0.x). All that means is putting up with '1 commit ahead' until this is (hopefully) merged upstream. If this is too much of a concern though, I can try to get it merged upstream first.

Type of change

• New feature
• This change requires a documentation update

How Has This Been Tested?

Actions were ran sucessfully on fork. Functionality can be tested by opening a PR into a branch that contains this workflow (or triggering via cron). Once the action has been triggered once, it's registered in github actions and can be manually dispatched.

Checklist:

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have requested a review from @macite and @jakerenzella on the Pull Request

[mannat2634]

I've tested the workflow on my own set of repos and it works as intended.

But I've few concerns:

• What if the branch is not present in upstream? This can be in case of a new feature branch or few more cases. Then this workflow fails completely as far as I understand. So, either there should be a option to set the upstream branch to sync to or it should default to sync main.

• What is the expected merge conflict behaviour? I think it should provide an error message rather than exiting with an error.

• If this workflow is triggered on every synchronize event then it means it is triggered on every commit to the PR. If a student commits 5 times in an hour in an existing hour then this will consume Action minutes like crazy. There should be a limiter or just keep it to opened, reopened and scheduled.

Also, this needs corresponding documentation updates so contributors know how to set it up.

Thank you,

[SteveDala]

I've tested the workflow against my fork, but the action always skips. I think this is because I was already up to date when the action was run.

I have to agree with @mannat2634 that we should keep the workflow triggers to opened, reopened, and scheduled.

[utilbird]

* What if the branch is not present in upstream? This can be in case of a new feature branch or few more cases. Then this workflow fails completely as far as I understand. So, either there should be a option to set the upstream branch to sync to or it should default to sync main.

There shouldn't be any errors if the branch isn't present upstream with github sync, I wasn't getting any errors in my test, were you getting different results?

* What is the expected merge conflict behaviour? I think it should provide an error message rather than exiting with an error.

It's just supposed to error, I can add a more verbose error message.

* If this workflow is triggered on every `synchronize` event then it means it is triggered on every commit to the PR. If a student commits 5 times in an hour in an existing hour then this will consume Action minutes like crazy. There should be a limiter or just keep it to `opened`, `reopened` and `scheduled`.

This workflow is done very quickly and should be computationally negligible, was this taking more than a second or two in your testing? Something like nodejs-ci should be using (at least) hundreds of times more action minutes.
Also synchronize is triggered when the head branch is updated, not on commit. Although upon further reflection, this should probably be triggered on push instead.

[mannat2634]

There shouldn't be any errors if the branch isn't present upstream with github sync, I wasn't getting any errors in my test, were you getting different results?

By this I meant often we branch off from master or 9.x. Then create a feature branch. Now, that feature branch isn't present in upstream and is new (it only has my changes).

Now, this workflow will sync my branch to an absent branch. But I want this branch to stay in sync with master branch so I don't have to deal with merge conflicts later on merge.

So I was suggesting we could have an option to mention which branch we want to keep in sync with.