Contributing

OpenALBA welcomes contributions from the community. This guide explains how to participate.

Ways to contribute

  • Report issues: Found a bug, inconsistency, or unclear documentation? Open a GitHub issue.
  • Suggest enhancements: Have ideas for new detection patterns, signals, or methodology improvements? Submit an RFC.
  • Submit fixes: Typos, clarifications, and small corrections can be submitted directly as pull requests.
  • Write examples: Reference implementations and code samples help others adopt OpenALBA.
  • Review RFCs: Participate in discussions on proposed changes.

Getting started

  1. Fork the repository: Create a fork of openalba/specification
  2. Create a branch: Use a descriptive branch name (e.g., fix/zscore-formula or rfc/new-detection-pattern)
  3. Make your changes: Follow the existing style and conventions
  4. Submit a pull request: Include a clear description of the change and its rationale

RFC process

For significant changes to the specification, submit an RFC (Request for Comments):

  1. Create a new file in /rfcs/ following the template
  2. Include motivation, detailed design, and alternatives considered
  3. Submit as a pull request
  4. Participate in the 14-day review period
  5. Address feedback and iterate

Style guide

Documentation

  • Use sentence case for headings
  • Be concise and precise
  • Include examples where helpful
  • Use RFC 2119 keywords (MUST, SHOULD, MAY) for conformance requirements

Code examples

  • Use YAML for configuration examples
  • Use Python pseudocode for algorithms
  • Include comments explaining non-obvious logic

Security

We take security seriously. If you discover a security vulnerability in the specification or its reference implementations:

Reporting Security Issues

  • Do not open a public GitHub issue for security vulnerabilities
  • Email security@openalba.org with details
  • Include steps to reproduce, affected versions, and potential impact
  • We aim to acknowledge reports within 48 hours
  • Coordinated disclosure after fix is available

See our security.txt for additional security contact information.

Code of conduct

All participants in the OpenALBA community are expected to follow the Contributor Covenant Code of Conduct. We are committed to providing a welcoming and inclusive environment for everyone.

Recognition

Contributors are recognized in the following ways:

  • Listed in the changelog for their contributions
  • Credited in release notes for significant additions
  • Invited to join as maintainers based on sustained contributions

Questions?

If you're unsure about anything, open a GitHub issue or reach out to contact@openalba.org.

Last updated: 2026-01-31