Maven documentation example leads to cached settings.xml

I am a happy user of the cache action and it works great, but it took me basically a whole day to locate the reason for a failing build. I have added settings to the setup-java step that currently runs before the caching step.

The new settings led to changes in the generated ~/.m2/settings.xml file but they had no effect and I almost went crazy because the settings were the same as for a different repo that did not had the same problem.

It turned out that the settings.xml was overwritten by a cached version...

Currently the caching examples suggest to use something like:

  - name: Cache Maven packages
     uses: actions/cache@v3
     with:
       path: ~/.m2
       key: ${{ runner.os }}-m2-${{ hashFiles('**/pom.xml') }}
       restore-keys: ${{ runner.os }}-m2

It would be better to be able to exclude the settings.xml easily, but I haven't found a simple solution for that, but at least we could bust the cache when the settings.xml changes, so I'd suggest to update the documentation to something like:

    - name: Cache Maven packages
      uses: actions/cache@v3
      with:
        path: ~/.m2
        key: ${{ runner.os }}-m2-${{ hashFiles('~/.m2/settings.xml') }}-${{ hashFiles('**/pom.xml') }}
        restore-keys: ${{ runner.os }}-m2-${{ hashFiles('~/.m2/settings.xml') }}

Is that approach ok or are there better solutions?

Review the Maven caching example in the repository documentation and verify how settings.xml is handled by the shown ~/.m2 cache. Confirm whether the proposed hashFiles inputs produce the intended cache invalidation, then update the example only if the behavior is supported and document what should happen when settings.xml changes.