Contributing‐Guide

Contributing Guide

Back to M-COP WIKI | See also: Installation-and-Quickstart | API-Reference

Thank you for advancing the triad. This guide keeps contributions deterministic, auditable, and easy to review.

The repository is a multi-language monorepo: a Next.js 16 / React 19 TypeScript surface, a packages/core/ ESM+CJS distribution, and a Python implementation under mcop_package/.

---

Code of Conduct

All contributors are expected to maintain respectful, constructive interactions. See CODE_OF_CONDUCT.md for full details.

---

Development Setup

1. Fork and clone

git clone https://github.com/<YOUR_USERNAME>/MCOP-Framework-2.0.git
cd MCOP-Framework-2.0

2. Configure Node & pnpm

nvm use              # picks 20.11.0 from .nvmrc
corepack enable
corepack prepare pnpm@9.15.0 --activate

3. Install dependencies

pnpm install         # use plain install (not --frozen-lockfile) for contributor setup

4. Configure environment

cp .env.example .env
# Fill in required API keys and configuration

Daily workflow commands

pnpm dev          # Start dev server
pnpm build        # Production build
pnpm test         # Run Jest tests
pnpm lint         # ESLint + Prettier
pnpm typecheck    # TypeScript strict check

---

Repository Layout

MCOP-Framework-2.0/
├── src/
│   ├── app/          # Next.js 16 App Router routes + server components
│   ├── core/         # Triad kernels: NovaNeoEncoder, StigmergyV5, HolographicEtch
│   └── adapters/     # Universal Adapter Protocol implementations
├── packages/core/    # ESM+CJS TypeScript distribution (@kullailabs/mcop-core)
├── mcop_package/     # Python implementation (mirrors TypeScript core)
├── docs/
│   ├── adapters/     # Adapter specs (UNIVERSAL_ADAPTER_PROTOCOL.md)
│   ├── adr/          # Architecture Decision Records
│   ├── api/          # Generated TypeDoc
│   ├── audits/       # Audit logs
│   ├── benchmarks/   # Performance benchmarks
│   ├── whitepapers/  # Technical whitepapers
│   └── planning/     # Roadmap and planning docs
├── examples/         # Runnable adapter examples
├── config/examples/  # Sample configuration files
├── tests/            # Jest + Cypress test suite
├── scripts/          # Build and validation scripts
└── cypress/          # E2E test configuration and specs

---

Branching Strategy

• Base branch: main
• Branch naming conventions:
  • feature/<short-description> — new features
  • bugfix/<short-description> — bug fixes
  • chore/<short-description> — maintenance, deps, config
  • docs/<short-description> — documentation only
  • refactor/<short-description> — code refactors without behavior changes

---

Coding Standards

TypeScript / React

• Strict TypeScript ("strict": true in tsconfig)
• Explicit return types on all exported functions
• Functional components only (no class components)
• Import order: external packages → @/* path aliases → relative imports
• Component files must remain under 250 lines
• Use path alias @/ instead of deep relative imports

CSS / Tailwind

• Tailwind utility classes by default
• Custom CSS only in globals.css
• Always respect prefers-reduced-motion for animations
• WCAG 2.2 AA accessibility: keyboard focus, aria-live regions, semantic landmarks

Python (mcop_package)

• Linting: ruff with line length 100
• Type checking: mypy --strict
• Style: PEP 8 + PEP 257 (docstrings)

Commit Message Convention

Follows Conventional Commits:

<type>(<scope>): <short summary>

[optional body]

[optional footer]

Types: feat, fix, chore, docs, refactor, test, perf, ci

Examples:

feat(stigmergy): add decay factor to pheromone traces
fix(encoder): correct entropy normalization for empty input
chore(deps): bump @kullailabs/mcop-core to 0.2.1
docs(wiki): add API Reference page

---

Testing Requirements

Every behavior change must ship with a corresponding test.

Test Types

Type	Tool	Command	Blocking?
Unit + integration	Jest (jsdom/node)	pnpm test	Yes
Type checking	TypeScript	pnpm typecheck	Yes
Linting	ESLint + Prettier	pnpm lint	Yes
E2E (exploratory)	Cypress	pnpm cypress:run	No
SSR validation	Custom script	scripts/verify-ssr-lcp.mjs	For LCP changes
Hybrid	Jest + Cypress	pnpm test:hybrid	Yes

Test coverage

• Current coverage: 96.6%
• All new code paths should be covered
• Tests live in tests/ (Jest) and cypress/ (E2E)

---

Pull Request Workflow

Before opening a PR

Ensure all of the following are green:

pnpm lint
pnpm test
pnpm typecheck
pnpm changeset   # document your change for the changelog

PR Description Template

Structure your PR description using these four sections:

1. Context — Why is this change needed? What problem does it solve?
2. Change — What exactly was changed? Which files/components?
3. Validation — How was this tested? Which test suites pass?
4. Risk — Any potential side effects or areas that need careful review?

PR Checklist

• Branch is based on latest main
• pnpm lint, pnpm test, pnpm typecheck all pass
• New behavior is covered by tests
• Changeset added (pnpm changeset)
• PR description follows Context → Change → Validation → Risk format
• For LCP-impacting changes: scripts/verify-ssr-lcp.mjs ran
• Documentation updated if applicable (docs/, wiki, PLAIN_ENGLISH_GLOSSARY.md)

Merge gates

• All CI checks must pass
• Production deployment approval required (maintainer-triggered)
• Merge is blocked until deployment success is recorded

---

Changesets & Release Flow

MCOP uses changesets for versioning and changelog generation.

# After making changes, add a changeset:
pnpm changeset
# Follow the prompt: choose patch/minor/major + describe the change
# Commit the generated .changeset/*.md file with your PR

Releases are managed by maintainers. See docs/releases/ for release notes.

---

Reporting Bugs & Proposing Features

• Bugs: Open an Issue with label bug. Include: steps to reproduce, expected vs actual behavior, environment details.
• Features: Open an Issue with label enhancement. Describe the motivation, proposed API/behavior, and any relevant ADR context.
• Security vulnerabilities: See SECURITY.md for responsible disclosure.

---

Architecture Decision Records (ADRs)

Significant architectural decisions are documented as ADRs in docs/adr/. If your contribution involves a meaningful design decision, consider adding or referencing an ADR.

---

Full details in CONTRIBUTING.md in the repository.