[FEATURE] Improve documentation for working with change files only

[BernieWhite]

Your suggestion

Provide a more detailed walkthrough for basic and advanced cases working with change files only. i.e. What happens and how to configure expanding the change set with interlinked files.

See: #2771 (comment)

Alternatives

n/a

Additional context

See #2771

[ReneRebsdorf]

A few things from your reply in: #2771 (comment)

The below may come across as quire 'opinionated', I hope that it is read as feedback and perspective to this request, I share my take and desired use case, but understand if it does not align with your product design decisions, or if it may be a very time consuming task.

---

You mention that this is not a bug, as the purpose of the ignoreUnchangedPath is to improve performance, and that git does not know the relation between two files.
To that I do not agree entirely, which I guess is also why this issue is raised? The design choice of using git to determine changed file is not a requirement, although I agree it is the best tool for the job, it just can't do it "by itself". The purpoes of better performance using ignoreUnchangedPath should not come as at a consequence that a PR can then make untested code modifications which breaks, that defeats the entire purpoes of the linter in my opinion.

My suggestion is to investigate what files are changed using git diff (as done currently), but based on the provided files, a further analysis is needed, such as by checking if the file being modified is a parameter file, and if it is, the template file (as per the template.metadata property) should be scanned as well.

Same goes for bicep files, it should be discovered which files has reference to that file, and that should cause a recursive test.

for bicep files with referenced files, it is probably more difficult, although he syntax is very specific and 'unforgiving' for Bicep, so I guess that helps.

I am also not a fan of the workaround provided by using conventions in #2771 (comment) as it puts the responsibility of ensuring correct testing on the users (in this case me), which is a responsibility of the linter, I think it is great we can use a convention as a workaround, but it should not be a requirement for this use case, which I guess is very standard (only test changes + using template parameter file expansion).

[BernieWhite]

@ReneRebsdorf Thanks for your plain feedback. It's not something scoped for the current planning cycle, but we'll investigate it.

I've raised another issue #2780 to keep track of scoping out this as an improvement to the feature since improving the docs and the feature may be tackled separately.

---

Anyone finding this issue if the future please jump to #2780 and vote up this feature if it is important to you to help us prioritise the issue.

[ReneRebsdorf]

Cheers @BernieWhite , great to create a separate item for this.
For now we will not use git diff for psrule as we are not interested in duping the Convention workaround, especially due to #2723
Jikes many of these issues are intertwined.