Contributing to Dicom

Copy Markdown View Source

Thank you for your interest in contributing. This guide covers the process for submitting changes.

Development Setup

Prerequisites

  • Elixir >= 1.16
  • Erlang/OTP >= 26

Getting Started

git clone https://github.com/Balneario-de-Cofrentes/dicom.git
cd dicom
mix deps.get
mix test

Common Commands

mix test                         # Run all tests
mix test --cover                 # Run with coverage report
mix format                       # Format code
mix format --check-formatted     # Check formatting (CI)
mix docs                         # Generate documentation

Submitting Changes

  1. Fork the repository and create a branch from master
  2. Make your changes
  3. Ensure all tests pass: mix test
  4. Ensure code is formatted: mix format --check-formatted
  5. Ensure coverage does not regress materially in the areas you changed
  6. Open a pull request against master

Pull Request Guidelines

  • Keep PRs focused on a single change
  • Include tests for new functionality
  • Update documentation for public API changes
  • Follow existing code style and conventions

Code Conventions

  • All public functions return {:ok, result} or {:error, reason}
  • Tags are {group, element} tuples: {0x0010, 0x0010}
  • VR types are atoms: :PN, :DA, :UI, :OB, etc.
  • Binary parsing uses Elixir pattern matching -- no external parsers
  • Use @spec on all public functions
  • Use @moduledoc and @doc on all public modules and functions
  • Reference specific DICOM standard sections in documentation (e.g., "PS3.5 Section 6.2")

DICOM Domain Notes

If you are new to DICOM, these concepts are essential:

  • P10 -- the DICOM file format (PS3.10): 128-byte preamble + "DICM" + File Meta Info + Data Set
  • Data Element -- a single attribute: tag + VR + value
  • Tag -- (group, element) pair identifying an attribute, e.g., (0010,0010) = Patient Name
  • VR -- Value Representation, the data type (PN = Person Name, DA = Date, UI = UID)
  • Transfer Syntax -- encoding rules: byte order, VR explicit/implicit, pixel compression

The DICOM standard is freely available online.

AI-Assisted Contributions

We welcome AI-assisted contributions under the following conditions:

  1. You are the author. You are fully responsible for every line you submit, regardless of what tools produced it.

  2. Review your changes. Read and understand all code before submitting. You must be able to explain your changes in your own words during review.

  3. Write in your own words. PR descriptions, issue comments, and review responses should be your own writing, not raw AI output.

  4. Meet the same quality bar. AI-assisted code must compile, pass all tests, maintain coverage, and follow project conventions.

See AGENTS.md for instructions that AI coding assistants can use to work with this codebase.

Reporting Issues

  • Use GitHub Issues for bug reports and feature requests
  • Include the Elixir and OTP versions you are using
  • For DICOM parsing issues, include (or describe) the transfer syntax and the relevant data element tags

Code of Conduct

This project follows a Code of Conduct. By participating, you are expected to uphold this code.

License

By contributing, you agree that your contributions will be licensed under the MIT License.