Contributing to Nebulex

February 20, 2026 ยท View on GitHub

Thanks for your interest in contributing.

This guide defines the expected contribution workflow for the nebulex core repository.

Scope

This repository contains Nebulex core. Adapter projects (for example nebulex_local, nebulex_distributed) are maintained in sibling repositories and have their own contribution rules.

Before You Start

  1. Read README.md.
  2. Read the latest section of CHANGELOG.md.
  3. Read usage-rules/workflow.md (source of coding/review conventions used in this repo).

Issues

Use the issue tracker for bug reports and feature discussions:

When opening a bug report, include:

  • Elixir and OTP versions
  • Nebulex version/branch
  • Minimal reproduction steps
  • Expected vs actual behavior

Feature Requests

Feature proposals are welcome.

For non-trivial features, open an issue first before implementing code so scope and design can be aligned early.

When proposing a feature, include:

  • Problem statement.
  • Real-world use case.
  • Proposed API/behavior.
  • Alternatives considered.

Pull Requests

Open pull requests at:

PR Expectations

  1. Keep changes focused and avoid unrelated commits.
  2. Add or update tests with code changes.
  3. Update documentation when behavior changes.
  4. Do not update CHANGELOG.md directly; include release-note context in the PR description for maintainers.
  5. Reference related issues (for example, Closes #123).

Validation

Run targeted checks during development and run the full CI command before requesting review:

# quick targeted check
mix test path/to/changed_test.exs

# full validation
mix test.ci

Commit Message Convention

Commit messages must follow Conventional Commits:

type(scope): short summary

Examples:

  • feat(cache): add runtime option validation for ttl
  • fix(decorators): handle nested context pop safely
  • docs(workflow): add contribution and review checklist

Documentation Conventions

For @doc, @moduledoc, and @typedoc, keep the first paragraph short and summary-oriented. Add examples when possible, ideally doctest-friendly.

License

By submitting a contribution, you agree that your work is licensed under the project's MIT license.