docs: fixed beforeHook documentation to reflect actual behaviour

[iamacup]

There are various open issues relating to the beforeChange hook as well as statements from payload team about its behaviour that conflict with the docs - this brings the docs in line with the expected behaviour of the hook

Current expected behaviour:

#9714 (comment)

beforeChange open issues:

#12065
#11169
#9714

We should probably acknowledge, as part of this documentation change for discussion, that while this update reflects the current behavior, it raises questions about the efficacy of the hook and whether this is truly the desired behavior.

I suspect users want the behaviour as documented today, not the modified version, but have not realised the true implementation detail through error or external abuse yet. It is hard to detect problems that arise from this when using the admin UI as it obscures them with the validation errors while not making it obvious that the hook still ran.

I would suggest that having the data passed into this hook as strongly typed instead of Partial does not aid developers in understanding how this hook works.

The short version: I think there is a requirement for a hook that runs before the database write but with valid data, and i think people believe this is that hook.

[AlessioGr]

We should revisit this and determine if the behavior of beforeChange hooks should be changed. I think it would make more sense to run it after validation.

However, currently, this docs change is factually correct, so I'm approving it. Thank you!

[github-actions]

🚀 This is included in version v3.41.0