Add in definition of terms like "synchronize" for Github Action Activity types

[logankilpatrick]

What article on docs.github.com is affected?

https://docs.github.com/en/free-pro-team@latest/actions/reference/events-that-trigger-workflows#pull_request

What part(s) of the article would you like to see updated?

This page references activity types like: "synchronize" but does not provide a definition of what this means. To my understanding, it means that a commit has been made to a pull request branch but it's not clear based on the docs if this is correct.

Additional information

It may be worth considering adding a definition for all of the "Activity Types" given it may not be fair to assume every user will know of the full GitHub functionality when reading the docs.

[janiceilene]

@logankilpatrick Thanks for opening an issue! I'll triage this so the right team can take a look 👀

[logankilpatrick]

Thank you @janiceilene!

[0xdevalias]

In a recent GitHub support ticket, I was told the following about the synchronize event:

A synchronize pull_request event it’s only triggered when the pull request’s tracking branch is synchronized with the source branch for the pull request, and that happens when the source branch is updated.

So every time someone pushes to the source branch of the pull request, the workflow will kick off again.

According to the following docs, I am assuming that the 'tracking branch' refers to the 'base branch' (eg. main), and the 'head branch' refers to the branch for the PR you currently have open:

• https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-branches

  • Once you're satisfied with your work, you can open a pull request to merge the changes in the current branch (the head branch) into another branch (the base branch).

---

Further, in more support request, I asked the following:

For my future knowledge/reference, is that aspect of synchronize described anywhere in the docs? I've read through the following page/similar (see link below), but I didn't see anything that specifically talked about when various events would be fired.

• https://docs.github.com/en/actions/reference/events-that-trigger-workflows

I'm not sure if it currently exists (so if not, this might be a documentation request), but is there anywhere in the docs that describes the specifics of each 'event type' we can 'react to', and when/under what circumstances they'll be 'fired'?

I did find this community post that describes it, but it would be good to have it all in the main docs somewhere:

• https://github.community/t/what-is-a-pull-request-synchronize-event/14784

Since this issue title mentions 'definitions of terms like', I figured that this was an appropriate place to include this. Ideally, there would be a clear section in the docs that describes when/under what circumstances all of these various event types will be fired.

[janiceilene]

Thanks so much for that additional information and context @0xdevalias!

[skedwards88]

Regarding the specific question about the synchronize activity, I think this doc should give you more info: https://docs.github.com/en/desktop/contributing-and-collaborating-using-github-desktop/syncing-your-branch

Currently, the Events that trigger workflows article and the Webhook events and payloads article (which is linked to from the former article) are both quite long, so we are going to avoid defining all of the activity types for now to keep the article from becoming too bloated.

Although we won't make a change immediately, it is really helpful to have feedback about this! 💖 I hope we continue to hear feedback from you about how we can improve the docs!

[0xdevalias]

@skedwards88 I may just have missed it, as I only quickly skimmed through the article, but I don’t feel like it satisfies the needs/request of this issue in being clear about when the ‘synchronise’ event is fired within GitHub actions, and specifically ensuring that that information is linked from/easily findable from the actions docs sections.

The link you provided feels more like a high level ‘how to use git’ sort of article.

---

While those articles may be long, they are also designed as basically reference docs for developers. We don’t need them to be perfectly short/succinct, but we do need them to be accurate and feature complete. So not sure that the decision here is a good one.

[polarathene]

I came across this which seems to clarify what synchronize covers. The current docs mention and link about Pull Request docs elsewhere, but neither really covered this event either.

Deeming the present docs page as too long is totally understandable as a concern. But this shouldn't mean these events should not be documented properly anywhere else since they're presumably Github API specific? If they are clearly explained somewhere in Github docs, perhaps there should be a link to those for users to visit when they need additional clarification of what each event entails, especially when something like synchronize isn't immediately clear where that applies.

---

EDIT: Someone wrote a blog article to give a more thorough documentation of the pull_request events in general. Though I'm not sure if Github docs are ok deferring to external third-party content.