Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
368 lines (274 loc) · 15.5 KB

CONTRIBUTING.md

File metadata and controls

368 lines (274 loc) · 15.5 KB
Raw

Contributing to Developer Tools Directory

Thank you for your interest in contributing. This guide covers everything you need to get started.

Getting Started

  1. Fork the repository
  2. Clone your fork: 
    git clone https://github.com/YOUR_USERNAME/Developer-Tools-Directory.git
cd Developer-Tools-Directory
  3. Install dependencies: 
    pip install -r requirements.txt
  4. Create a feature branch: 
    git checkout -b feat/your-feature-name

Repository Structure

Developer-Tools-Directory/
  registry.json              # Tool catalog (source of truth)
  standards/                 # Convention documentation (see standards/README.md)
  scaffold/
    create-tool.py           # Repo generator script
    templates/               # Jinja2 templates for new repos
  site-template/
    build_site.py            # Shared GitHub Pages build for tool repos
    template.html.j2         # HTML template with configurable branding
    fonts/                   # Self-hosted Inter + JetBrains Mono woff2
  docs/                      # GitHub Pages catalog site
  assets/                    # Logo image
  .github/workflows/         # CI/CD automation

How to Add a New Tool to the Registry

  1. Open registry.json and add a new entry at the end of the array:
{
  "name": "Your Tool Name",
  "repo": "TMHSDigital/Your-Tool-Repo",
  "slug": "your-tool-repo",
  "description": "One-line description of the tool",
  "type": "cursor-plugin",
  "category": "developer-tooling",
  "homepage": "https://tmhsdigital.github.io/Your-Tool-Repo/",
  "skills": 0,
  "rules": 0,
  "mcpTools": 0,
  "extras": {},
  "topics": ["topic-1", "topic-2"],
  "status": "active",
  "language": "Python",
  "license": "CC-BY-NC-ND-4.0",
  "pagesType": "static",
  "hasCI": true
}

  1. Run the sync script - it regenerates every derived artifact (README tables and stats, CLAUDE.md, embedded registry in docs/index.html):

    python scripts/sync_from_registry.py

  2. Verify the sync is clean:

    python scripts/sync_from_registry.py --check

  3. Commit with feat: add <tool-name> to registry. Remember to sign off your commit (see DCO section below).

For a full end-to-end walkthrough including scaffolding the tool repo, see docs/contributors/adding-a-tool.md.

Required fields

Field Type Constraints
name string Display name
repo string Owner/RepoName format
slug string Kebab-case, matches repo name
description string One line, no em dashes
type string cursor-plugin or mcp-server
homepage string URL or empty string
skills int >= 0
rules int >= 0
mcpTools int >= 0
extras object Optional counts (snippets, templates, etc.)
topics string[] Discovery tags
status string active, beta, or deprecated
version string Semver
language string Primary language
license string SPDX identifier
pagesType string static, mkdocs, or none
hasCI bool Whether repo has CI workflows

How to Write a New Standard

  1. Create a new Markdown file in standards/:

    # Example: standards/testing.md

  2. Structure the document:

    • Start with an H1 title
    • Include a brief overview paragraph
    • Use H2 sections for major topics
    • Include concrete examples and code blocks
    • Write for public readership - no internal references

  3. Add the standard to two index locations:

    • standards/README.md - add a row to the table
    • README.md - add a row to the Standards table

  4. If the standard affects scaffold output, update the corresponding .j2 template in scaffold/templates/.

  5. Commit with feat: add <standard-name> standard

Drift checker

Tool repos carry a standards-version signal in their agent files (AGENTS.md, CLAUDE.md, skills/*/SKILL.md, rules/*.mdc). The drift checker (scripts/drift_check/) verifies these against the meta-repo VERSION and surfaces other ecosystem-policy mismatches (broken standards links, required references, stale aggregate counts).

The checker runs automatically: on push to main (when checker code or standards change), weekly on schedule, and on demand via workflow_dispatch. See docs/drift-check-token-setup.md for the DRIFT_CHECK_TOKEN configuration that enables cross-repo sparse-checkout.

For local runs:

python scripts/drift_check/cli.py --local /path/to/tool-repo

How to Update the Scaffold

Editing an existing template

  1. Edit the .j2 file in scaffold/templates/
  2. Test locally: 
    python scaffold/create-tool.py \
  --name "Test Plugin" \
  --description "Test description" \
  --mcp-server \
  --skills 2 \
  --rules 1 \
  --no-register \
  --output /tmp/scaffold-test
    --no-register keeps the test repo out of registry.json.
  3. Verify the generated files look correct
  4. Commit with fix: or chore: prefix

Adding a new template

  1. Create the .j2 file in scaffold/templates/
  2. Render it from _render_repo() in scaffold/generator.py via write_file()
  3. Run a test generation and verify the new file appears
  4. Update README.md "What it generates" section if visible to users
  5. Commit with feat: add <template-name> scaffold template

Template syntax

Templates use Jinja2. Available context variables:

Variable Type Description
name string Display name
slug string Kebab-case identifier
description string One-line description
type string cursor-plugin or mcp-server
has_mcp bool Whether MCP server scaffold is included
skills list Skill name strings
rules list Rule name strings
skill_count int Number of skills
rule_count int Number of rules
license_spdx string SPDX license identifier
license_key string License key for template selection
author_name string Author name
author_email string Author email
repo_owner string GitHub org (TMHSDigital)
repo_name string Repository name (same as slug)

How to Update the Catalog Site

The catalog site lives in docs/ and is vanilla HTML/CSS/JS with zero dependencies.

  • docs/index.html - the whole site: markup, inline CSS, and inline JS (search, filters, URL state)
  • Generated regions (tool cards, filter chips, hero stats, embedded registry and search JSON) come from scripts/sync_from_registry.py; do not edit them by hand

The pages.yml workflow copies registry.json and assets/ into docs/ at deploy time, so you don't need to manually copy files.

To test locally, open docs/index.html in a browser. The script falls back to the embedded registry data.

How to Update the Site Template

The unified site template (site-template/) powers GitHub Pages for all tool repos. Changes to the template affect every site at next deploy.

Files

File Purpose
site-template/template.html.j2 Jinja2 HTML template rendered by each tool repo
site-template/build_site.py Build script that reads repo data and renders the template
site-template/fonts/ Self-hosted Inter and JetBrains Mono woff2 files
site-template/SETUP-PROMPT.md Full schema reference for site.json, mcp-tools.json, data flow

Testing locally

python site-template/build_site.py --repo-root /path/to/tool-repo --out /tmp/tool-test

Open the generated index.html in a browser to verify. Repeat for at least one other tool repo to confirm the template works across different data shapes.

Rebuilding all tool repos after a template change

After modifying template.html.j2 or build_site.py, rebuild each affected tool repo locally:

for repo in Docker-Developer-Tools Home-Lab-Developer-Tools Steam-Cursor-Plugin Monday-Cursor-Plugin; do
  python site-template/build_site.py --repo-root "$TOOLS_ROOT/$repo" --out "$TOOLS_ROOT/$repo/docs"
done

Where $TOOLS_ROOT is the parent directory containing your checkouts of each tool repo. Then commit the updated docs/index.html in each repo.

Adding a new site.json field

  1. Add the field to build_site.py - load it from site.json and pass it in the template context
  2. Use the field in template.html.j2 with a Jinja2 conditional so existing repos without the field still render correctly
  3. Document the field in site-template/SETUP-PROMPT.md (schema table, example, and customization guide)
  4. Add a default value to the scaffold's site.json.j2 template if applicable
  5. Test with a repo that uses the field and one that doesn't
  6. Commit with feat: add <field-name> support to site template

Pull Request Process

Branch protection

main is protected by an active ruleset (main protection). All contributions, including from the repo owner, must land through a pull request. Direct pushes, force pushes, and branch deletion are blocked. The bypass-actors list is empty.

  • Required approvals: 0 (solo-maintainer repo).
  • Merge method: squash merge only; merge commits and rebase merges are blocked.
  • All 8 required status checks listed under CI checks must pass before merge is allowed.

Branch naming

Use descriptive branch names with a type prefix:

  • feat/add-tool-name - new registry entries or standards
  • fix/correct-registry-field - corrections
  • chore/update-jinja2 - dependency or CI changes
  • docs/improve-scaffold-docs - documentation improvements

Commit style

Follow Conventional Commits:

feat: add kubernetes developer tools to registry
fix: correct homepage URL for steam-mcp
docs: clarify scaffold --license flag usage
chore: bump Jinja2 to 3.1.5

Versioning

The meta-repo uses a VERSION file at the repo root as the single source of truth for its own version. When your PR lands a user-visible feature or bug fix, bump VERSION in the same PR.

Rules:

  • VERSION contains a single semver line, no v prefix, LF line ending (1.6.1).
  • Any commit whose subject starts with feat: or fix: (including scoped variants like feat(registry):) requires a VERSION bump in the same PR. The version-bump-check CI job enforces this, and it is a required status check in the branch-protection ruleset, so a PR without the bump cannot be merged.
  • chore:, docs:, ci:, refactor:, test:, and style: commits do not require a bump.
  • Bump kind is at your discretion and guided by semver: breaking behavior change to a published contract is major, new capability is minor, correction with no behavior change is patch.
  • Escape hatch: add [skip version] to the commit subject or body for workflow-only changes that slipped into a feat:/fix: subject. Use sparingly.

On merge to main, release.yml compares VERSION against the latest tag. If VERSION is ahead, it creates tag v<VERSION> and a GitHub Release. If they match, the workflow no-ops. If VERSION is lower, the workflow fails and refuses to downgrade.

This model applies to the meta-repo only. Tool repos in the ecosystem use the conventional-commit auto-bump model documented in standards/versioning.md.

Review checklist

Before submitting a PR, verify:

  • registry.json is valid JSON (run python -c "import json; json.load(open('registry.json'))")
  • No em dashes or en dashes in any content (see standards/writing-style.md)
  • No hardcoded credentials, tokens, business emails, or local filesystem paths
  • If registry changed: run python scripts/sync_from_registry.py and commit the result
  • python scripts/sync_from_registry.py --check exits 0
  • If standard added: both standards/README.md and README.md tables are updated
  • If scaffold changed: dry-run test passes
  • If any commit is feat: or fix:: VERSION is bumped in the same PR (see Versioning section)
  • Commit messages follow conventional format and are Signed-off-by: (see DCO section)

CI checks

All PRs must pass these 8 required status checks (enforced by the main protection ruleset, not just advisory):

  • Validate registry.json - JSON schema and required fields
  • Validate docs site - docs/index.html exists
  • Validate scaffold - Python syntax and scaffold dry-run
  • Registry sync check - scripts/sync_from_registry.py --check exits 0
  • Public-repo safety scan - no leaked emails, drive paths, unsafe DOM sinks, or committed secrets
  • feat/fix commits require VERSION bump - enforces the rule in the Versioning section, checking the PR title (the squash commit subject) as well as each commit
  • CodeQL - security scan on Python code
  • Run drift_check tests - the full pytest suite under tests/

release.yml's Check VERSION vs latest tag runs on every push to main and will fail the release if VERSION is behind the latest tag. It is a post-merge guard, not a PR gate, so it is not in the required-contexts list.

Additional (non-required) checks run on most PRs: dependency review, release-drafter preview, Socket Security. These provide signal but do not gate merges.

Style Guidelines

  • No em dashes. Use regular hyphens (-) or rewrite the sentence.
  • No hardcoded credentials. Environment variables or config files only.
  • Concise descriptions. No filler text or marketing language.
  • Public readership. All content should make sense to external contributors.
  • Consistent formatting. Use existing files as reference for Markdown structure.

Developer Certificate of Origin (DCO)

All contributions must be signed off under the Developer Certificate of Origin 1.1. This is a lightweight way to certify that you wrote the contribution or have the right to submit it.

How to sign off

Add Signed-off-by: Your Name <your-email> to the end of every commit message. Git can do this automatically with the -s flag:

git commit -s -m "feat: add new standard"

Your name and email must match your Git identity. Use a real name - pseudonyms are not accepted.

If you forget to sign off, amend the commit:

git commit --amend -s --no-edit
git push --force-with-lease

Inbound license grant

By submitting a contribution to this repository, you certify that you have the right to do so under the Developer Certificate of Origin 1.1, and you grant TMHSDigital a perpetual, worldwide, non-exclusive, royalty-free, irrevocable license to use, reproduce, prepare derivative works of, publicly display, publicly perform, sublicense, and distribute your contribution under the project's current license (CC-BY-NC-ND-4.0) or any successor license chosen by the project.

This grant exists because CC-BY-NC-ND-4.0's "NoDerivatives" clause would otherwise prevent the project from accepting pull requests (every PR is a derivative). See standards/licensing.md for the full rationale.

Enforcement

The preferred enforcement is the built-in GitHub DCO App. Maintainers enable it from repo settings; no workflow is required. PRs with unsigned commits are blocked by the App's status check.

If the App is unavailable, a pinned fallback workflow can be added. Contributors do not need to do anything different - just sign off.

Code of Conduct

This project follows the Contributor Covenant Code of Conduct. By participating, you agree to uphold this code.