Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
59 lines (46 loc) · 2.32 KB

CONTRIBUTING.md

File metadata and controls

59 lines (46 loc) · 2.32 KB
Raw

Contributing to seo-ci

Thanks for helping keep SEO regressions out of production. Issues and PRs are welcome.

The bar

  • One sharp theme. Every action is an SEO deploy gate — nothing else. If a change broadens the scope beyond "catch a technical-SEO regression before it ships," it probably belongs in a different tool.
  • A gate must be able to fail. Every gate ships with a good fixture it passes and a broken fixture it fails, exercised by the negative integration job. No exceptions.
  • Self-contained. No proprietary credentials to build, test, or demo.

Local workflow

npm ci
npm run verify   # typecheck + lint + test + build

npm run serve-fixtures serves the fixtures at http://127.0.0.1:8099 for manual URL-mode testing.

Project layout

  • src/lib/ — the shared, dependency-light library (report model, fetch, HTML, robots, XML, URL helpers, and the GitHub Actions wiring). Keep it pure and unit-tested; it is bundled into every action.
  • actions/<name>/ — one gate each: action.yml, src/ (with the pure check logic factored out of index.ts so it is testable without the Actions runtime), tests, a focused README.md, and the committed dist/index.js.
  • fixtures/good + fixtures/broken — the proof the gates work.

Adding a new gate

  1. Scaffold actions/<name>/ mirroring an existing action (e.g. validate-robots). Entry point is void runAction(async () => …) — never top-level await (the CJS bundle forbids it).
  2. Put the decision logic in a pure module and the I/O in index.ts.
  3. Add a good and a broken fixture and wire both into .github/workflows/test.yml (positive + negative jobs).
  4. Write unit tests (and URL-mode tests via tests/helpers/fixture-server.mjs).
  5. npm run build and commit the dist/ — CI fails if it drifts from source.
  6. npm run verify must be green before you open the PR.

Coding notes

  • TypeScript strict; ESM source, CJS bundles.
  • Findings use stable, grep-able UPPER_SNAKE codes prefixed by the gate (ROBOTS_*, SITEMAP_*, CANONICAL_*, REDIRECT_*, JSONLD_*, LH_*, SMOKE_*).
  • Severity: error fails the gate; warning fails only in strict mode; notice is informational.

By contributing you agree your work is licensed under the repository's MIT license.