From 213d4c7b4c13d77cb6effe9a0988616901aa832f Mon Sep 17 00:00:00 2001
From: "Alex Pooley (@zuedev)" <zuedev@gmail.com>
Date: Thu, 5 Feb 2026 15:45:28 +0000
Subject: add contribution guidance

---
 CONTRIBUTING.md | 72 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 72 insertions(+)
 create mode 100644 CONTRIBUTING.md

(limited to 'CONTRIBUTING.md')

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..c49f61c
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,72 @@
+# Contributing to gitinfo
+
+Thank you for your interest in improving the `.gitinfo` specification!
+
+## Proposing Changes
+
+### For Minor Clarifications
+
+- Open an issue describing the ambiguity or unclear wording
+- Suggest specific text improvements
+- Reference relevant sections of the README
+
+### For New Fields
+
+Before proposing a new field:
+
+1. **Check existing issues** to avoid duplicates
+2. **Describe the use case** — what problem does this field solve?
+3. **Show compatibility** — how does it interact with existing fields?
+4. **Provide examples** — include sample `.gitinfo` snippets
+
+Open an issue with the following template:
+
+````markdown
+## Proposed Field: `fieldName`
+
+**Type:** string | array | object
+
+**Description:** Brief description of the field's purpose.
+
+**Use Case:** Why is this field needed? What problem does it solve?
+
+**Example:**
+
+```jsonc
+{
+  "fieldName": "example value",
+}
+```
+````
+
+**Compatibility:** How does this interact with existing fields?
+
+```
+
+### For Breaking Changes
+
+Breaking changes require strong justification:
+
+- Explain why the change cannot be made backward-compatible
+- Propose a migration path for existing `.gitinfo` files
+- Consider versioning implications
+
+## Pull Requests
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/new-field`)
+3. Update both `README.md` and `gitinfo.schema.json`
+4. Ensure the schema validates your examples
+5. Submit a pull request with a clear description
+
+## Style Guidelines
+
+- Keep descriptions concise
+- Use consistent terminology with existing documentation
+- Follow JSONC conventions (trailing commas are allowed)
+- Use SPDX identifiers for license references
+
+## Questions?
+
+Open an issue for discussion before investing significant effort in a proposal.
+```
-- 
cgit v1.2.3