Generated Artifact Churn Rules for Registry Repositories

Purpose

Use these rules when reviewing a registry repository where raw source entries produce many derived files. Examples include public data feeds, category indexes, search manifests, README sections, Raycast or plugin exports, package bundles, generated previews, and static-site data.

Generated artifacts are useful, but they are a poor place to review contributor intent. The source entry should explain what changed. Generated output should be reproducible from that source and rebuilt by the trusted path the project expects.

Artifact Classification

Classify a changed file before reviewing content.

1. Source file. The human-authored entry, config, rules, guide, command, or source document that reviewers should inspect for intent.
2. Generator code. The script, package, workflow, or template that turns source files into derived artifacts.
3. Generated artifact. A file rebuilt from source or generator code, such as indexes, feeds, bundles, generated docs, snapshots, registry JSON, or README sections.
4. Build cache or transient output. Local output that should not be committed unless the repository explicitly tracks it.

When the category is unclear, ask the contributor or maintainer to identify the source of truth before approving the diff.

Source-Only Rules

• Contributor content PRs should add or update exactly the raw source files the issue asks for.
• Generated artifacts should stay out of contributor PRs unless the repository explicitly requires them.
• A generated file change without a source input change is a merge blocker until the generator or source explanation is found.
• A source file change that causes massive generated churn should be reviewed as a source change first, then rebuilt in maintainer automation.
• Do not accept "I ran the build" as enough evidence when the repository policy says generated output is maintainer-owned.

Generated File Marking

Generated files should be easy for reviewers and platforms to recognize.

• Use .gitattributes or repository conventions to mark generated paths when appropriate.
• Keep generated paths predictable, such as public/data/**, dist/**, generated/**, snapshots/**, or repository-specific output directories.
• Add a short generated-file header only when the file format and project policy support it.
• Keep source and generated files in separate paths so reviewers can filter noisy output.
• Update file classification when a generated path becomes hand-authored source or vice versa.

Reproducibility Rules

Generated artifacts are reviewable only when their provenance is clear.

• Name the command, workflow, or build job that regenerates the artifact.
• Record the source input path or generator code path that explains the output.
• Avoid machine-local timestamps, absolute paths, random ordering, host-specific metadata, and environment-dependent output when possible.
• Pin or document generator versions when output format matters.
• If generation is intentionally non-deterministic, keep it out of routine contributor PRs and let maintainers publish it through a controlled path.

Reviewer Rules

• Review raw source first, generated output second.
• Compare generated artifact changes against the source input that produced them.
• Ask for a source-only resubmission when generated churn hides a small content change.
• Treat generator or workflow changes as code changes, not content-only submissions.
• Confirm that generated artifacts do not include private metadata, local paths, credentials, timestamps, or stale source URLs.
• Do not merge broad generated rewrites to fix unrelated lint, formatting, ordering, or timestamp changes in a content PR.

Do Not Merge When

• the PR includes README output, registry feeds, search data, package bundles, previews, or generated JSON when the issue asks for one source file;
• generated artifacts changed but the source entry, generator code, or command is missing;
• generated output includes local paths, private identifiers, secret-like values, prompt excerpts, internal reviewer notes, or stale source metadata;
• the generated diff is mostly timestamp, ordering, formatting, or checksum churn that reviewers cannot reproduce;
• the contributor changed generator code and content in one PR without explicit maintainer approval;
• a closed one-shot submission is retried by force-pushing generated fixes instead of opening a clean source-only PR.

Review Checklist

• {"task": "Source changed", "description": "The PR changes the raw source entry or source input requested by the issue"}
• {"task": "Generated output excluded", "description": "Generated feeds, indexes, README output, previews, bundles, and snapshots are absent unless project policy requires them"}
• {"task": "Generator known", "description": "Any generated artifact has a named command, workflow, or generator path"}
• {"task": "Diff is reproducible", "description": "Generated output avoids unexplained timestamps, random ordering, local paths, and environment-specific metadata"}
• {"task": "Files are classified", "description": "Generated paths are marked or conventionally separated so reviewers can filter churn"}
• {"task": "Privacy checked", "description": "Generated files do not expose secrets, private paths, prompts, logs, account IDs, or reviewer notes"}

Troubleshooting

• The project requires generated files: include the generation command, source input, generator version, and a note that repository policy requires the artifacts.
• The generated diff is huge: split source changes from generator changes, then let maintainers rebuild artifacts in a separate automation run.
• The source entry looks correct but generated data is stale: merge the source-only PR only if project policy says generated data is rebuilt after merge.
• The artifact order changes every run: stabilize sorting or keep the output out of contributor PRs until the generator is deterministic.
• A generated file contains private data: stop normal review, remove the value at the source, rebuild, and check secondary artifacts before publishing.

Marking Generated Artifacts in .gitattributes

Tell Git how to treat generated paths so reviewers see less churn. The binary macro is defined as [attr]binary -diff -merge -text, so it unsets diff, merge, and text in one attribute.

# Suppress diffs for a generated path (still tracked, just no textual diff)
*.ps -diff

# Treat a generated bundle as binary (unsets diff, merge, and text)
*.ps binary

# Built-in binary macro definition (for reference)
[attr]binary -diff -merge -text

Duplicate Check

Checked existing rules, guides, collections, hooks, skills, commands, registry quality code, submission gate code, open PRs, and closed PR history for generated artifact churn, source-only PRs, generated file review, registry artifact policy, large generated diffs, README refresh output, and source-backed content submissions.

Adjacent content includes a source-backed content PR guide, documentation freshness rules, generated-diff hooks, and submission gate code that enforces single-source-file shape. This rules entry is distinct because it gives portable do/don't behavior for reviewers and contributors deciding when generated artifact churn should block or be moved to maintainer automation.

References

• Git gitattributes documentation: https://git-scm.com/docs/gitattributes
• GitHub Linguist overrides: https://github.com/github-linguist/linguist/blob/main/docs/overrides.md
• GitHub changed-file display customization: https://docs.github.com/en/repositories/working-with-files/managing-files/customizing-how-changed-files-appear-on-github
• Reproducible Builds definition: https://reproducible-builds.org/docs/definition/

• Source repositorygithub.com 2026-07-20T09:33:29+00:00
• Documentationgit-scm.com
• Submitted by MkDev112026-06-04