Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
88 lines (70 loc) · 3.83 KB

CONTRIBUTING.md

File metadata and controls

88 lines (70 loc) · 3.83 KB
Raw

Contributing to OpenMed

Thanks for helping improve OpenMed — bug reports, features, docs, and translations are all welcome. By participating you agree to our Code of Conduct.

Important

Security and privacy come first. OpenMed de-identifies PHI. Never open a public issue for a vulnerability, and never include real patient data in an issue, pull request, test, or fixture — see SECURITY.md. Any test data committed to the repository must be synthetic.

This page is a quick start. The full tooling, documentation, and release guide lives in docs/contributing.md.

Development setup

The canonical development environment is managed by uv. From the repository root, run:

uv sync --frozen --extra dev    # create .venv and install from uv.lock
# stack extras as needed, e.g. --extra hf for Hugging Face model work
uv run --frozen --extra dev pre-commit install  # auto-format staged files on commit

Use uv run --frozen --extra dev <command> or the Makefile targets so commands run inside the locked environment. If uv is unavailable, the supported fallback is a regular virtual environment and editable pip install:

python3 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install -e ".[dev]"
.venv/bin/pre-commit install

The pre-commit hooks also run the Gitleaks secret scanner on staged changes. See Secret Scanning for local use, CI behavior, and baseline maintenance.

Run the checks before opening a PR

uv run --frozen --extra dev pytest tests/ -q
make format                              # apply canonical Ruff formatting
make lint                                # lint
make type-check                          # scoped public-module type check
make format-check                        # CI-parity format check

Ruff is the single source of truth for Python lint, import ordering, and formatting; the pinned mypy gate checks the annotated public-module scope. CI runs both gates. Do not run Black, isort, or flake8. For Swift changes under swift/OpenMedKit, run make format-swift and make lint-swift.

make lint, the local pre-commit effect-paths hook and the CI lint job also run python scripts/security/check_effect_paths.py --check. New or removed HTTP/database effect candidates require an explicit review of scripts/security/effect_paths.json; do not regenerate classifications without reviewing the path. Built-in MCP, REST, CLI and Journey dependencies must not reach the legacy FHIR/OpenMRS writers. See the agent boundary limits.

Pull requests

  • Keep each PR focused on a single feature or fix; avoid unrelated formatting churn.
  • Name branches <type>/issue-<number>-<short-kebab-slug>, using a suitable type such as feat, fix, docs, test, chore, or refactor; for example, docs/issue-280-maintainers.
  • Write clear, imperative commit messages (the project uses concise prefixes such as fix:, feat:, and docs:).
  • Reference the issue you are closing and complete the pull request template.
  • Update CHANGELOG.md and the docs when behavior changes.
  • For privacy-sensitive paths, add tests for direct-identifier recall, critical leakage, and span integrity (see docs/contributing.md).

Reporting issues

  • Bugs and features: use the issue templates.
  • Security vulnerabilities (including redaction bypass or PHI/PII leakage): report privately per SECURITY.md — never as a public issue.

For the complete contributor and release workflow, see docs/contributing.md.