Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
143 lines (113 loc) · 5.62 KB

CONTRIBUTING.md

File metadata and controls

143 lines (113 loc) · 5.62 KB
Raw

Contributing

Thanks for your interest in contributing to Open Workflow Library.

This file is the operational handbook. The project vision lives in docs/vision.md; the current status lives in docs/status.md; the roadmap lives in docs/roadmap.md.

Ground rules

  • No real credentials, tokens, JWTs, API keys, bearer tokens, webhook URLs, customer emails, phone numbers, addresses, or other PII in any tracked file. Placeholders only.
  • No "production-ready", "behaviourally validated", "fully autonomous", "self-healing", "certified", or regulatory-compliance language. If something is true today, the status page says so.
  • No AI attribution in generated files, commit messages, or PR descriptions. Generated artefacts identify the deterministic tool that produced them, not any model.
  • No auto-apply of repair proposals. No auto-promotion of learning events into the curated wiki. Every promotion is a human PR.

Submitting workflows

  1. Place the workflow under the appropriate category directory (workflows/ or automation/).

  2. Use placeholder credentials and placeholder hosts only:

    • Use REPLACE_WITH_YOUR_VALUE, <your-api-key>, or framework-native placeholder syntax such as {{ $secrets.OPENAI_API_KEY }}.
    • Use api.example.com or api.example.invalid for HTTP URLs.

  3. Document required credentials in the workflow's notes field by symbolic name (e.g. slack_credentials), not by value.

  4. Run the audit locally:

    python tools/audit_workflows.py

    Confirm possibleSecretFindings is unchanged (target: 0).

  5. Open a Workflow submission issue first if you want a sanity check before a full PR.

  6. Open the PR using .github/PULL_REQUEST_TEMPLATE.md.

If you imported and executed the workflow in n8n (or the relevant framework) yourself, describe the test environment and outcome in the PR. If you did not, say so. Do not claim behavioural validation that did not happen.

Running validation locally

The full local validation set is:

python tools/audit_workflows.py
python tools/validate_generated_pack.py
python tools/build_unified_catalog.py
python tools/validate_schemas.py
python tools/analyze_duplicates.py
python tools/build_review_queue.py
python tools/audit_public_claims.py
python tools/final_readiness_check.py

final_readiness_check.py orchestrates the hard gates and is the single command to run before pushing.

Adding generated templates

The generated expansion pack is produced by tools/generate_expansion_pack.py. Do not regenerate the pack from a contributor PR unless that is explicitly the change you are making. Regenerating the pack churns 420 files and is a separate, scoped change.

If you are extending the generator:

  • Keep node types restricted to the conservative whitelist used by tools/export_ir_to_n8n.py.
  • Use only placeholder URLs and credentials.
  • Ensure python tools/validate_generated_pack.py reports ALL CHECKS PASSED with secrets=0 and structural=0.

Adding repair proposals

Repair proposals must conform to schemas/repair-proposal.schema.json.

  • Always set requiresHumanReview: true and status: "proposed".
  • Always include diagnosis and proposedFix as plain-English strings a maintainer can act on.
  • Do not modify any workflow file from the same PR that introduces a proposal. Proposals are written to reports/; applying a proposal is a separate, explicit step.

Reviewing learning events

Learning events live under reports/runtime-proof/<slug>/learning-events.json and conform to schemas/learning-event.schema.json.

  • Events stay humanReviewStatus: "pending" and appliedToWiki: false until a maintainer opens a curated-wiki PR that references them.
  • Promotion = a hand-written entry under wiki/repair-rules/, wiki/patterns/, wiki/integrations/, or wiki/failure-cases/. The curated wiki is the authoritative source; the seed files under wiki/generated/ are regenerated by tools and are not promoted directly.

Coding style for tools

  • Python 3.12+, standard library only by default.
  • Optional dependencies (e.g. jsonschema) must be gated behind a try import and a documented fallback mode.
  • Each tool writes to reports/, catalog/, or wiki/generated/; tools must not modify source workflows or curated wiki files.
  • Stable output: rerunning a tool with the same inputs must produce identical (byte-for-byte where possible) outputs.
  • Honest stderr summary on exit (last printed line should describe the outcome).
  • Tools must not call external services and must not read environment variables for credentials.

Docs style

  • Honest first: if something is partial or not implemented, say so.
  • Cross-link rather than restate: README links to docs/status.md and docs/roadmap.md rather than duplicating them.
  • No emoji-heavy section headers. Plain text titles.
  • Code blocks for commands; tables for status; prose for context.

Contributor checklist

Before opening a PR:

  • Audit reports 0 possibleSecretFindings and 0 invalidJsonFiles.
  • Schema validation passes.
  • Generated-pack validation passes (if touched).
  • Final readiness check exits 0.
  • No real credentials or PII anywhere in the diff.
  • No new overclaiming language in README or docs.
  • No AI attribution anywhere in the diff.
  • Status / roadmap pages are updated if the change moves a capability between "not implemented" and "implemented".