Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
66 lines (53 loc) · 3.45 KB

CONTRIBUTING.md

File metadata and controls

66 lines (53 loc) · 3.45 KB

Contributing to Harmony Proxy

Thank you for your interest in contributing! This document explains how to propose changes, the development workflow, coding standards, and community expectations.

Code of Conduct

Scope of contributions

  • We welcome bug reports, feature requests, documentation improvements, performance optimizations, and test coverage enhancements.

Getting started

  • Read DEVELOPER.md for local setup, repository layout, commands, and testing guidance.
  • Review the docs index at docs/README.md for architecture, configuration, middleware, and testing references.

Workflow

  • Trunk-based development: use feature branches and open pull requests against main.
  • Keep PRs small and focused. Avoid mixing unrelated refactors, formatting, or lint changes with functional changes.
  • Link issues in PR descriptions when applicable. Describe the problem, approach, and trade-offs.

Commit messages and PR titles

  • Use Conventional Commits and prefer aligning PR titles similarly:
    • feat: add DIMSE store-and-forward support
    • fix: handle JWKS rotation error on startup
    • docs: update configuration examples
    • refactor: extract DICOMweb client
    • test: add pipeline validation cases
    • perf: reduce clone in router
    • ci: enable tests in GitHub Actions
  • Follow Semantic Versioning. Breaking changes should be marked with ! (e.g., feat!: change endpoint config).

Coding standards and gates

  • Format code: cargo fmt --all
  • Lint: cargo clippy --all-targets -- -D warnings
  • Build: cargo build
  • Test: cargo test (add RUST_LOG=harmony=debug and -- --nocapture for verbose output)
  • These gates must pass locally before opening a PR; CI will run them as well.

Tests

  • Prefer focused and deterministic unit/integration tests.
  • Use ./tmp for temporary artifacts; do not rely on /tmp.
  • DIMSE/DCMTK integration tests:
    • Default runs are quiet. Enable verbose logs with HARMONY_TEST_VERBOSE_DCMTK=1.
    • Additional debug behavior: HARMONY_TEST_DEBUG=1.
  • Use the samples/ directory for test inputs where relevant; keep tests hermetic.

Documentation

  • Update docs/ and example directories (examples/*/) when behavior or configuration changes.
  • Each example should have its own README with usage notes and prerequisites.
  • Include security implications where applicable.

Security guidance

  • Do not commit secrets. Use environment variables or secret managers; restrict permissions to least privilege.
  • JWT in production should use RS256 with strict algorithm enforcement and claim validation (exp, nbf, iat, iss, aud).
  • Encryption: where used, AES-256-GCM with ephemeral public key, IV, and authentication tag encoded in base64.
  • Temporary files: prefer ./tmp within the working directory.
  • See docs/security.md for additional guidance.

Licensing of contributions

  • By contributing, you agree your contributions are licensed under the Apache License, Version 2.0, and acknowledge the project’s commercialization restriction described in README.md (hosted resale/embedding requires a commercial licence from Aurabox Pty Ltd).
  • No CLA or DCO is presently required.

Issue triage and labels

  • Use labels such as bug, enhancement, documentation, help wanted, and good first issue where applicable.

Contact