Documentation: provide information about parallel cache usage using matrix-based Gradle builds

[hiddewie]

I have the following Gradle projects:

- root
  - A
  - B
  - C

The tests for A, B and C are run in parallel, by using a Github Actions matrix strategy.

For Gradle tests, these situations are interesting, because the gradle home directory is populated with the dependencies / gradle cache just for A, B or C within it's specific tests, while the project and source files (and especially the Gradle configuration) is equal for all builds.

Can this be added to the documentation, how parallel builds influence the caching behaviour in parallel tests. How are the keys and context built up for each of the subproject builds?

I noticed https://github.com/gradle/gradle-build-action/blob/main/src/cache-utils.ts#L128-L130 which takes the matrix context into account for building the cache key. This suits my purposes just fine.

It seems the cache keys are overridable as well by environment variables, https://github.com/gradle/gradle-build-action/blob/main/src/cache-utils.ts#L22-L26, which is undocumented.

[bigdaz]

@hiddewie I added a "How caching works" section to the README, which I think addresses the issue you raised here.

It would be great if you could take a look and see if it clarifies things for you. The content needs some restructuring/editing, but for now I was just wanted to get the information in there.

[hiddewie]

Thank you for expanding the documentation. The content is extensive and answers some of my questions. The section Select which jobs should write to the cache in particular answers some of the questions for running Gradle tasks in Github actions in parallel with effective dependency caching 👍🏻.