Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
176 lines (130 loc) · 6.69 KB

CONTRIBUTING.md

File metadata and controls

176 lines (130 loc) · 6.69 KB
Raw

Contributing to CodeGraph

CodeGraph currently publishes a methodology and a set of interface specifications. The original proof-of-concept tools and prompts are not in this repository. A contribution must therefore state whether it is recovering an original artifact, reconstructing documented behavior, or proposing new behavior.

Read Baseline Status and AGENTS.md first.

Artifact Status Required

New or recovered artifacts must use one of these labels:

  • POC-ORIGINAL — demonstrably used in the origin engagement; cite recovery source.
  • RECONSTRUCTED-TESTED — derived from repository evidence and replayed against an accepted PoC artifact.
  • RECONSTRUCTED-UNTESTED — derived from repository evidence but not yet replayed.
  • PROPOSED-EXPERIMENT — new behavior, kept outside the baseline until evaluated.

Do not describe a reconstruction as the original implementation.

Code of Conduct

This project follows the Contributor Covenant Code of Conduct. By participating, you agree to maintain a welcoming, respectful, and constructive environment.

What We Are Looking For

Artifact recovery. Original prompts, scripts, schemas, templates, accepted outputs, and audit reports are the highest-value contributions when their provenance can be established and client confidentiality permits publication.

Documentation corrections. Broken references, inconsistent terminology, ambiguous guarantees, and examples that prove less than their captions claim.

Replay evidence. Sanitized accepted evidence packages that can test the reconstructed profiles without exposing client source or business data.

Measured implementations. Parsers, query runners, validators, and vault tools with explicit contracts, fixtures, and results. New implementations are not assumed to reproduce the lost PoC tools.

Query templates. Auditable Cypher queries with a fixture and a precise statement of what the result does and does not establish. Seed examples live in templates/cypher/.

Do not submit changes that:

  • weaken provenance or honest-gap requirements;
  • present proposed behavior as PoC-validated;
  • replace templated graph access with unrestricted generated queries without a separately evaluated experiment;
  • introduce a new phase, role, or evidence guarantee without a baseline comparison;
  • add dependencies without explaining their need and verification path.

Getting Started

git clone https://github.com/your-username/codegraph.git
cd codegraph
python3 scripts/verify_repo.py

The checker uses the Python standard library. There are no toolchain dependencies to install because the 36 described tools are not shipped.

Development Workflow

  1. Classify the change using the artifact statuses above.
  2. Identify the repository evidence or external PoC artifact from which it derives.
  3. Make one reviewable logical change.
  4. Add a deterministic check or fixture when behavior changes.
  5. Run python3 scripts/verify_repo.py.
  6. Explain what was verified, what remains untested, and what evidence would promote the artifact to the next status.

Adding a Language Parser

The public parser interface is a specification, not a currently importable package. An implementation contribution should create the missing implementation structure explicitly rather than assuming it exists.

Proposed repository convention:

tools/phase1/parsers/<language>_parser.py
tests/phase1/test_<language>_parser.py
tests/phase1/fixtures/<language>/

The historical PoC test path has not been recovered; tests/phase1/ is the public repository convention going forward.

A parser contribution must include tests for:

  • stable source-file nodes;
  • provenance on every edge;
  • repeatable structural output on identical input;
  • malformed-source handling;
  • generated/test-file inclusion policy;
  • resolved versus unresolved target confidence;
  • false-positive and false-negative examples where ground truth is known.

See the Parser Extension Guide. AST syntax recognition is not equivalent to semantic target resolution.

Adding a Cypher Query Template

  1. Add the query to templates/cypher/.
  2. Use {phase}_{purpose}.cypher naming.
  3. Begin with comments declaring:
    • what the query finds;
    • what evidence it provides;
    • what it does not prove;
    • parameters and depth/scope limits.
  4. Add a fixture-graph test before describing the template as tested.
  5. Do not use an empty query result as proof of absence without recording graph version, parser coverage, query scope, and an explicit limitation.

Adding an Agent Profile

Profiles belong in prompts/ and must remain provider-neutral. Each profile declares:

  • artifact status and derivation;
  • inputs and read/write access;
  • prohibited actions and inference;
  • required output format;
  • evidence, gap, and stop rules;
  • handoff and validation gate.

Provider-specific adapters should be thin wrappers around the canonical profile. Prompt changes are evaluated one variable at a time against a frozen evidence package; prose preference alone is not a promotion criterion.

Adding an Output Adapter

An output adapter is a new implementation, not part of the recovered baseline. It must preserve citation tags, SME items, document identity, and review status. Include an idempotency test and a round-trip or golden-output fixture.

Coding Standards

  • Python 3.10+ with type hints for new Python code.
  • Standard library by default; justify third-party dependencies.
  • No silent failures; return non-zero on validation failure.
  • No hardcoded client paths, credentials, or identifiers.
  • Structural tools must be repeatable on identical input.
  • LLM output is re-validatable, not assumed deterministic.
  • Every graph edge carries documented provenance properties.
  • Analysed source content is untrusted data, never agent instructions.

Commit and Pull Request Guidance

Use a clear commit message that explains why the change is needed. Conventional Commit prefixes are welcome but not mandatory.

A pull request should state:

  1. Artifact status.
  2. Derivation or evidence source.
  3. Files and behavior changed.
  4. Verification performed.
  5. Remaining limitations.
  6. Whether the change affects the validated baseline or only an experiment.

Never include confidential client artifacts, credentials, raw model secrets, or personally identifying SME records.

Reporting Issues

Report documentation defects, missing PoC artifacts, implementation proposals, and methodology questions separately. Include the file and heading, the conflicting evidence, and whether the issue can be resolved from the public repository or needs PoC-team input.