📚 How to handle generated GitHub workflow files

[ckunki]

Summary

I observed a list of GitHub workflow files that PTB did create in repository python-extension-common. I am wondering whether we should mark these files as "generated" in a file .gitattributes with potential content

.github/workflows/build-and-publish.yml linguist-generated=true
.github/workflows/check-release-tag.yml linguist-generated=true
.github/workflows/checks.yml            linguist-generated=true
.github/workflows/ci-cd.yml             linguist-generated=true
.github/workflows/ci.yml                linguist-generated=true
.github/workflows/gh-pages.yml          linguist-generated=true
.github/workflows/pr-merge.yml          linguist-generated=true
.github/workflows/report.yml            linguist-generated=true

Details

The effect of marking files as "generated" is that during code review, GitHub will initially hide the files with a comment "This file is generated". So human reviewers can skip this file during review as it is generated anyway and hence does not need to be reviewed. By that human reviewers can save time and focus on manual changes the should of course be subject to review.

See PK PR #562 for example:

Background & Context

I created this ticket based on observations in repository python-extension-common recently adopting the PTB.

Please also see the project-keeper for Java implementing all the tasks named below.

References

• Repository python-extension-common recently adopted the PTB.
• Solution for java developers implemented in project-keeper

Task(s)

1. We could think of first potentially enhancing the PTBs documentation and giving a recommendation about how to deal with these workflow files, whether they should be marked as "generated" and how to update the PTB.
2. Second, PTB could be enhanced to even create and populate the file .gitattributes.
3. We could define a strategy for PTB to update these files when a repo switches to a newer version of the PTB, potentially containing updated versions of some of the workflow files?
4. Third, there could be options enabling a user to deliberately exclude one or multiple of the workflow files to prevent manual changes from being overwritten when updating the PTB.