Merge pull request modelcontextprotocol#2813 from modelcontextprotocol/generated-files-merge-attrs

Mark generated files with -merge and document regeneration on conflicts

Author: dsp-ant

.gitattributes

@@ -1,6 +1,10 @@
 package-lock.json linguist-generated=true
-schema/*/schema.json linguist-generated=true
-docs/specification/*/schema.md linguist-generated=true
-docs/specification/*/schema.mdx linguist-generated=true
-docs/seps/index.mdx linguist-generated=true
-docs/seps/[0-9]*.mdx linguist-generated=true
+
+# Generated files: linguist-generated collapses them in PR diffs; -merge tells
+# git not to attempt a textual merge (keeps the current branch's copy and marks
+# the file conflicted). Resolve by re-running `npm run generate` and committing.
+schema/*/schema.json linguist-generated=true -merge
+docs/specification/*/schema.md linguist-generated=true -merge
+docs/specification/*/schema.mdx linguist-generated=true -merge
+docs/seps/index.mdx linguist-generated=true -merge
+docs/seps/[0-9]*.mdx linguist-generated=true -merge

CONTRIBUTING.md

@@ -53,6 +53,19 @@ npm run check:schema:ts
 npm run generate:schema
 ```
 
+### Resolving merge conflicts in generated files
+
+If your branch conflicts with `main` in generated files (`schema/*/schema.json`, `docs/specification/*/schema.mdx`, `docs/seps/*.mdx`), do not resolve them by hand. Merge `main`, resolve any conflicts in the source files (e.g. `schema/draft/schema.ts`), then regenerate and commit:
+
+```bash
+git merge main
+npm run generate
+git add .
+git commit
+```
+
+These files are marked with `-merge` in `.gitattributes`, so git keeps your branch's copy and flags them as conflicted instead of inserting conflict markers.
+
 ## Documentation changes
 
 Documentation is written in MDX format and in the [`docs`](./docs) directory.