idea: add header to file copies that mentions they are auto-generated and links to the original

[kevgo]

This repo helps update files that are used in many repos. As an example, the file ory/prettier-styles/.github/workflows/stale.yml is a copy of the original ory/meta/templates/repository/common/.github/workflows/stale.yml.

Many people aren't aware of this setup and it isn't obvious which files in an Ory repo are copies and which aren't. As a result, too many PRs fix issues in copies. These fixes will get lost. Currently these problems are caught in the manual code review. This is error-prone and doesn't scale.

I propose to prefix copies with a comment that explains that this file is auto-generated and points the developer to the original so that they can make the change there.

This could easily be implemented by introducing a Bash function (let's call it cpr_and_prefix for now) that acts like cp -r (copies the given file or directory to the given target path) and prefixes each file that it copies with a comment pointing to the original. To get super concrete:

Change https://github.com/ory/meta/blob/master/scripts/sync.sh#L34:

-    cp -R "templates/repository/common/CONTRIBUTING.md" "$workdir/CONTRIBUTING.md"
+    cpr_and_prefix "templates/repository/common/CONTRIBUTING.md" "$workdir/CONTRIBUTING.md"

This copies the file as before, but the target file now contains this header:

<!-- This is an auto-generated file, please don't edit it but make changes to https://github.com/ory/meta/blob/master/templates/repository/common/CONTRIBUTING.md. -->

It should be possible to derive the format of the comment (YML or MD format) as well as all paths used in the comment from the available data at the callsite.

This change alone should already help a lot. To make this bulletproof, we could add automation that scans PRs for changed files that contain the header mentioned above. If it finds one, it adds a review comment saying the same thing as the file header and breaks the build.

I wanted to get some feedback from the existing maintainers before implementing this. Thanks!

[aeneasr]

I think that's a great idea! One observation we've made is that people do not read this unless it's very, very visible.

[kevgo]

I hope that at least the senior folks will read it. For the others we have the (to be implemented) CI check that looks for changes to files with this header. If it finds some in a PR, CI adds a PR comment to that file (could be just the header content) and breaks the build to get attention.

[kevgo]

I think I got around to implementing this! Closing.