Content-Only Submission PR Gate Rules

Purpose

Use these rules before opening a direct content-only pull request. The goal is to make the branch easy for maintainers and automation to classify: one raw source file, reachable source evidence, documented duplicate history, focused validation, and no generated output.

This is not a general contributor tutorial. It is a gate an AI coding assistant or contributor can apply at the moment when a content branch is almost ready to push.

Gate Inputs

Collect these inputs before creating the content file.

1. Slot and category. Name the child issue, requested category, target directory, title, and slug.
2. Source evidence. List official docs, repository files, package pages, standards, or primary project pages that prove the claims in the entry.
3. Nearby content. Search existing rules, guides, hooks, skills, collections, commands, agents, open PRs, and closed PRs for the same workflow or source URL.
4. Risk class. Decide whether the submitted entry describes executable code, install commands, credentialed tools, local file reads, external writes, network calls, telemetry, logs, or generated artifacts.
5. Validation path. Know the category validator and content policy command before opening the PR.

Do not open the PR while any gate input is still unknown.

Scope Rules

• Add or modify exactly one raw MDX source file under the requested content/<category>/ directory.
• Do not edit README output, generated registry data, route files, feeds, downloads, ZIP or MCPB artifacts, package metadata, workflows, scripts, or unrelated content.
• Do not reformat neighboring files, rename existing entries, reorder content directories, or update shared metadata as a side task.
• Keep the branch based on current upstream main so the PR does not open behind the base branch.
• If a rejected one-shot submission is being repaired, create a fresh branch and PR with the actual blocker fixed rather than force-pushing the closed PR.

Source Rules

• Put only reachable public URLs in documentationUrl, repoUrl, and sourceUrls.
• Prefer primary sources: repository files, official docs, standards, package pages, release notes, or the target repository's validation files.
• Verify source URLs with a real HTTP request or browser load before opening the PR.
• Cite the final URL without trailing punctuation, markdown backticks, tracking parameters, local paths, or private redirects.
• Use sources that support the operational claims in the entry, not just the title.
• Replace any source that returns a hard 404, requires private auth, or points to a file that does not exist on the target repository's default branch.

Duplicate Rules

Search and record:

• title, slug, aliases, provider name, package name, docs URL, repository URL, source URL, and source domain;
• same-category entries and adjacent-category entries that solve the same problem;
• open PRs, closed PRs, and merged PR history for the child issue;
• earlier rejection reasons, especially duplicate, source failure, wrong category, generated artifacts, or missing safety/privacy evidence.

The PR body should name the closest related content and explain the difference in one or two concrete sentences.

PR Body Rules

The PR body should include:

• the exact closing reference for the child issue, such as Closes #730;
• a summary that says the PR changes one content file;
• duplicate and closed-PR history;
• source URL verification notes;
• validation commands;
• a statement that generated artifacts, README output, workflows, package files, and scripts were not changed.

GitHub supports linked pull requests that close issues with keywords, and this repository's PR template asks direct content submissions to confirm one-file scope, source/provenance, author attribution, and generated-artifact boundaries.

Validation Rules

Run focused checks before pushing the branch.

git diff --check upstream/main...HEAD
node scripts/validate-content.mjs --category rules
node scripts/ci/validate-content-policy.mjs --files-json /tmp/content-pr-files.json --head-repo <fork-owner>/<repo> --base-repo JSONbored/awesome-claude --head-ref <branch> --pr-author <author>

The files JSON manifest should contain only the intended MDX source file. If a validator reports another file, stop and remove the unrelated change before the PR is opened.

Safety And Privacy Rules

Do not use generic warnings when the submitted content has real runtime risk. Require specific notes when the entry:

• runs shell commands, install commands, hooks, package managers, or build tools;
• reads files, browsers, repositories, databases, tickets, logs, prompts, or screenshots;
• uses credentials, cookies, OAuth, API keys, database URLs, MCP permissions, or cloud accounts;
• writes to external services, sends messages, opens PRs, edits issues, deploys code, or publishes artifacts;
• stores or transmits user data, telemetry, traces, generated output, or validation logs.

If none of those behaviors apply, the safety and privacy notes should say that the rule itself is review-process guidance and explain what public review artifacts still exist.

Merge Blockers

Do not open or approve the PR when:

• more than one content file changed;
• generated output, README sections, workflows, package files, scripts, or downloads changed;
• any sourceUrls value is private, broken, redirected to an error page, or decorated with stray markdown characters;
• the PR body lacks the child issue closure reference;
• the duplicate check ignores an obvious related entry, open PR, or closed PR;
• safety or privacy notes are generic for a tool that can execute code, read local data, use credentials, or write externally;
• local validation was skipped without an explicit reason;
• the branch is already behind upstream main before the PR is opened.

Review Checklist

• {"task": "One file", "description": "The diff contains exactly one raw MDX file under the requested content category"}
• {"task": "Sources reachable", "description": "Every documentation, repository, and source URL loads publicly and supports the entry"}
• {"task": "Issue closes", "description": "The PR body includes the exact child issue closing reference"}
• {"task": "History checked", "description": "Existing content, open PRs, closed PRs, source domains, titles, slugs, and aliases were searched"}
• {"task": "Artifacts excluded", "description": "README output, generated files, workflows, packages, scripts, and downloads were not edited"}
• {"task": "Validation recorded", "description": "Whitespace, category validation, and content policy validation ran against the reviewed branch"}

Troubleshooting

• A source URL returns 404: replace it with the final reachable source, then rerun source verification before opening a new PR.
• The entry overlaps a guide: make the rule enforce a pre-open or pre-merge decision, and explain how it differs from the contributor guide.
• The PR is behind upstream: rebase before opening or immediately after GitHub reports the stale base.
• The closed PR had a private-gate comment: fix the exact blocker in a new branch and name the prior close reason in the PR body.
• The validation command needs a files manifest: write a JSON array with the single intended file path and pass it to the policy validator.

Duplicate And History Check

Checked existing rules, guides, collections, hooks, skills, commands, open PRs, closed PRs, repository templates, and validator scripts for content-only PR hygiene, direct content submissions, source-backed content PRs, generated artifact churn, one-file PR gates, issue-closing keywords, and source URL verification.

Adjacent content includes the source-backed content PR guide and generated artifact churn rules. This entry is distinct because it is an operational gate for AI coding assistants and contributors immediately before opening a direct content-only PR: it blocks stale branches, broken source URLs, missing issue closure, incomplete closed-PR history, and accidental generated-artifact scope.

PR #1135 previously attempted this slot and was closed because source URLs were reported as hard 404 failures. This resubmission uses verified reachable URLs and a new slug while keeping the one-file rules scope.

Sources

• Repository PR template: https://github.com/JSONbored/awesome-claude/blob/main/.github/pull_request_template.md
• Rules example entry: https://github.com/JSONbored/awesome-claude/blob/main/examples/content/rule.example.mdx
• Content validator: https://github.com/JSONbored/awesome-claude/blob/main/scripts/validate-content.mjs
• Content policy validator: https://github.com/JSONbored/awesome-claude/blob/main/scripts/ci/validate-content-policy.mjs
• GitHub linked issue closure documentation: https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue

• Source repositorygithub.com 2026-07-19T11:20:19-07:00
• Documentationgithub.com
• Submitted by MkDev112026-06-04