How to prevent inconsistent comments in generated project config YAML files

Question

We're using Project Config to enable a decentralised, git-based workflow. One issue we have is that sometimes the generated YAML files will include a specific comment, and sometimes it won't. In particular, in the /config/project/sections/ files, the YAML files for each section have a siteSettings key, with a list of settings per site (currently we're working only with a single site). Now the line with the UUID of the site will sometimes include a comment with the site name, and sometimes it won't. Here's a diff showing the difference:

--- a/config/project/sections/home--12b67b1c-1077-4a7a-8312-c1cba1234567.yaml
+++ b/config/project/sections/home--12b67b1c-1077-4a7a-8312-c1cba1234567.yaml
@@ -3,7 +3,7 @@ handle: home
 name: Home
 propagationMethod: all
 siteSettings:
-  649a64c1-52f1-4463-8a03-bc84c1234567:
+  649a64c1-52f1-4463-8a03-bc84c1234567: # NameOfTheSite
     enabledByDefault: true
     hasUrls: true
     template: entries/home

We want to prevent this from cluttering up our commits. Of course, we can just not commit those files and/or reset them manually, but keeping track of that manually is a bit tedious. I haven't been able to find out why the comment is sometimes there and sometimes it isn't. Sometimes after creating some new fields, sections or similar all YAML files in config/project/sections will show up as changed in git status, and I don't know when they got overwritten. Maybe it's got to do with whether the site name is defined or not? Though that hasn't changed at least on my machine.

Anyway, is there a way to either prevent Craft from including those comments when generating YAML files, OR have them be consistent? Of course, if the comment depends on the local name of the site, that would result in a lot of unnecessary changes if multiple people use a different site name in their local development environment.

I'm open to other solutions. The main problem is that it's cluttering up our commits and it's annoying to manage manually when commiting. Any insight would be appreciated. Thanks!

Answer 1

Comments were added to Project Config files after Craft 3.6.8 referencing GitHub issue 7584.

They shouldn't be appearing and disappearing unless you're committing config files without them over the ones that already do have them in the repo. That being said, from my experience the comments are only applies to NEW fields added after 3.6.8, or at least are not all done at once as soon as you update to 3.6.8. To get around this, I'd do ./craft project-config/rebuild which will regenerate your config files and add comments to EVERYTHING, commit that, then get your developers to pull them.