Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
101 lines (73 loc) · 2.83 KB

CONTRIBUTING.md

File metadata and controls

101 lines (73 loc) · 2.83 KB
Raw

Contributing to Ethernity

Thanks for contributing.

This project is stable software, so small, focused changes with clear tests and docs are preferred.

Development Setup

Prerequisites

  • Python 3.11+
  • uv
  • Node.js 20+ (for recovery kit build)

Initial Setup

git clone https://github.com/MinorGlitch/ethernity.git
cd ethernity
uv sync --extra dev --extra build
uv run playwright install chromium

Daily Workflow

  1. Fork the repository and branch from master on your fork.
  2. Make one focused change set.
  3. Add or update tests.
  4. Update docs if behavior/UX/output changed.
  5. Run quality gates locally.
  6. Open a PR with clear scope and rationale.

Quality Gates

Run before opening a PR:

uv run pre-commit run --all-files
uv run ruff check src tests
uv run ruff format --check src tests
uv run mypy src
uv run pyright
uv run check-jsonschema --check-metaschema docs/cli_api.schema.json
uv run typos .
uv run pytest tests/unit tests/integration -q

Python Readability

  • Keep ruff format as the only Python formatter.
  • Keep Python line length at 100; readability work should come from code shape, not formatter churn.
  • Use blank lines for real phase boundaries, not as a substitute for extraction.
  • Prefer small helper functions or module imports over long symbol-import lists and dense orchestration blocks.
  • In tests, collapse repeated mock.patch(...) bundles into fixtures or helper context managers when they repeat.
  • Use # fmt: off / # fmt: on only for rare cases where structural refactoring would not help.

Optional, when touching browser kit assets:

cd kit
npm ci
npm run lint
npm run format:check
npm test
# Requires libdeflate-gzip (for example: apt install libdeflate-tools)
node build_kit.mjs
cd ..

This builds both committed recovery kit bundles (lean + scanner variants).

Pull Request Expectations

  • Keep PRs small and reviewable.
  • Include tests for logic changes.
  • Include docs updates for user-facing behavior changes.
  • Avoid mixing unrelated refactors with behavior fixes.
  • Use explicit commit messages that explain intent.

Documentation Expectations

If you change CLI behavior, output contracts, recovery flow, or release artifacts:

  • update README.md where applicable
  • update docs under docs/ when deeper details are required
  • keep command examples aligned with current behavior

Security-Related Changes

For cryptography, recovery integrity, or authentication-path changes, include:

  • explicit threat-model impact summary in PR description
  • regression tests for negative/error paths
  • compatibility notes for existing artifacts, if relevant

See full disclosure guidance in SECURITY.md.

Automation and Agent Conventions

This repository includes automation-specific conventions in AGENTS.md. If you use coding agents, follow AGENTS.md as a required contract.