From 5b528cf93193292505454820afa409eef92ec485 Mon Sep 17 00:00:00 2001
From: Gary Jones <gary.jones@automattic.com>
Date: Thu, 8 Oct 2026 19:32:21 +0100
Subject: [PATCH 1/2] docs: add a contributing guide

The develop and main rulesets now reject unsigned commits, so an outside
contributor can open a pull request that can never be merged without
knowing why. The guide states the signing requirement up front, alongside
the setup, checks and workflow that were previously only in AGENTS.md.

It is kept out of the release ZIP and the WordPress.org build, as it is
only useful to people working on the repository.
---
 .distignore     |  1 +
 .gitattributes  |  1 +
 CONTRIBUTING.md | 73 +++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 75 insertions(+)
 create mode 100644 CONTRIBUTING.md

diff --git a/.distignore b/.distignore
index 21b23e1..d6ebd0d 100644
--- a/.distignore
+++ b/.distignore
@@ -18,6 +18,7 @@
 .wp-env.override.json
 AGENTS.md
 CHANGELOG.md
+CONTRIBUTING.md
 composer.json
 composer.lock
 package.json
diff --git a/.gitattributes b/.gitattributes
index dedb4ba..62e76dc 100644
--- a/.gitattributes
+++ b/.gitattributes
@@ -15,6 +15,7 @@
 /.wp-env.override.json export-ignore
 /AGENTS.md             export-ignore
 /CHANGELOG.md          export-ignore
+/CONTRIBUTING.md       export-ignore
 /composer.json         export-ignore
 /composer.lock         export-ignore
 /package.json          export-ignore
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..cd2cbdc
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,73 @@
+# Contributing to Syndication
+
+Thank you for your interest in contributing. This document covers setting up a local environment, running the checks, and proposing a change.
+
+## Code of Conduct
+
+This project follows the [Automattic Code of Conduct](https://automattic.com/code-of-conduct/).
+
+## Development Setup
+
+### Prerequisites
+
+- [Node.js](https://nodejs.org/) LTS or later
+- [Docker Desktop](https://www.docker.com/products/docker-desktop)
+- [Composer](https://getcomposer.org/)
+
+### Setup
+
+1. Clone the repository.
+2. Install dependencies:
+   ```bash
+   composer install
+   npm -g install @wordpress/env
+   ```
+3. Start the WordPress environment:
+   ```bash
+   wp-env start
+   ```
+4. Visit http://localhost:8888 and log in with `admin` / `password`.
+
+### Checks
+
+```bash
+composer lint                # PHP syntax
+composer cs                  # Coding standards
+composer test:unit           # Unit tests (no WordPress needed)
+composer test:integration    # Integration tests (single site, needs wp-env)
+composer test:integration-ms # Integration tests (multisite, needs wp-env)
+```
+
+## Workflow
+
+1. Create a branch from `develop`:
+   ```bash
+   git checkout develop
+   git pull origin develop
+   git checkout -b fix/short-description
+   ```
+2. Make your change, with tests.
+3. Run the checks locally.
+4. Push your branch and open a pull request against `develop`.
+
+## Code Standards
+
+We follow the [WordPress VIP Coding Standards](https://github.com/Automattic/VIP-Coding-Standards), configured in `.phpcs.xml.dist`. Run `composer cs-fix` to fix what PHPCS can fix automatically.
+
+## Tests
+
+Unit tests live in `tests/Unit/` and run without WordPress. Integration tests live in `tests/Integration/` and run inside wp-env.
+
+- New behaviour should come with tests.
+- A bug fix should come with a test that fails without the fix.
+
+## Pull Requests
+
+- Keep each pull request to one change, and explain what it does and why.
+- Reference related issues, for example `Fixes #123`.
+- Make sure CI passes before requesting a review.
+- **Sign your commits.** `develop` and `main` only accept commits with a verified signature, so a pull request with an unsigned commit cannot be merged until it is re-signed and force-pushed. See GitHub's guide to [signing commits](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits).
+
+## Releases
+
+Maintainers cut releases from a `release/x.y.z` branch into `main`. Pushing the version tag publishes a GitHub release with an installable ZIP attached, and stable releases (tags without a hyphen) are deployed to WordPress.org.

From 9dd0c980dd822065ef07d98e8d57c473403fcbdf Mon Sep 17 00:00:00 2001
From: Gary Jones <gary.jones@automattic.com>
Date: Thu, 8 Oct 2026 19:32:21 +0100
Subject: [PATCH 2/2] docs: point the readme at the contributing guide

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index e82048a..a6ab7ad 100644
--- a/README.md
+++ b/README.md
@@ -97,4 +97,4 @@ See [CHANGELOG.md](https://github.com/Automattic/syndication/blob/main/CHANGELOG
 
 ## Contributing
 
-Pull requests are welcome on [GitHub](https://github.com/Automattic/syndication).
+Pull requests are welcome on [GitHub](https://github.com/Automattic/syndication). See [CONTRIBUTING.md](https://github.com/Automattic/syndication/blob/develop/CONTRIBUTING.md) for setup, checks and signed commits.