Skip to content

Contributing to Alnoms

Thank you for your interest in contributing to Alnoms, the Performance Intelligence Engine developed by Arprax Lab.
Alnoms is an open, research-driven project focused on deterministic performance governance, empirical analysis, and high‑quality engineering standards.

We welcome contributions from engineers, researchers, educators, and practitioners who share our mission of making performance predictable, measurable, and enforceable.

🧩 What You Can Contribute

Alnoms is a multi‑layered system. Contributions are welcome across several domains:

1. Pattern Registry

Add new structural anti‑patterns or improve existing AST detection logic.

2. Fixers

Implement prescriptive, code‑level remediation strategies with before/after snippets.

3. DSA Metadata

Expand the metadata registry with new data structures, performance guarantees, or domain‑specific notes.

4. Analyzer Improvements

Enhance profiling, static analysis, empirical testing, or governance logic.

5. Documentation

Improve clarity, add examples, or contribute case studies (“Performance Proofs”).

6. Tutorials

Submit practical walkthroughs demonstrating Alnoms in real engineering environments.

🛠️ Development Setup

To contribute code, you’ll need:

  • Python 3.10+
  • A virtual environment
  • The Alnoms repository cloned locally

Install dependencies:

pip install -r requirements.txt
Run tests: 
pytest
Ensure all changes pass linting and type checks: 
ruff check .
mypy alnoms

🔍 Contribution Workflow

1. Fork the Repository

Create your own fork of the Alnoms repository on GitHub.
This gives you a personal workspace to experiment, prototype, and refine your changes before submitting them upstream.

2. Create a Feature Branch

Use a descriptive, purpose‑driven branch name.
This helps maintainers understand the intent of your contribution at a glance.

Examples:

feature/add-membership-in-loop-pattern
fix/loop-depth-edge-case
docs/add-case-study-bioinformatics

3. Make Your Changes

Implement your feature, fix, or documentation update.
Follow the project’s style, architectural conventions, and the core principles of the Alnoms Performance Intelligence Engine.

4. Add or Update Tests

Every contribution must include tests that validate behavior and prevent regressions.
All new logic should be covered by unit tests or integration tests where appropriate.

5. Submit a Pull Request

Open a PR against the main branch and include:

  • a clear description of the change
  • motivation and context
  • before/after examples (if applicable)
  • links to related issues

A maintainer will review your PR and provide feedback.

🧪 Performance Proofs (Case Studies)

If you’ve used Alnoms to optimize a real system, we encourage you to contribute a Performance Proof:

  • describe the original bottleneck
  • include the Analyzer report
  • show the applied fix
  • provide empirical results before/after

Submit via:

  • GitHub Issues, or
  • a PR to the tutorials/case-studies directory

These case studies help the community learn from real-world scenarios.

🧭 Code Style & Principles

Alnoms follows these engineering principles:

  • Determinism: No randomness, no side effects.
  • Transparency: Every decision must be explainable.
  • Empirical Grounding: Claims must be backed by measurement.
  • Governance First: Performance regressions must be detectable.
  • OSS‑Tier Clarity: Code should be readable, documented, and testable.

Please ensure your contributions align with these principles.

🛡️ Security & Responsible Disclosure

If you discover a security issue or vulnerability in the Analyzer pipeline,
do not open a public issue.

Instead, email:

[email protected]

We will respond promptly.

🤝 Join the Community

  • GitHub Issues: Report bugs or request features
  • Discussions: Share ideas and ask questions
  • Arprax Academy: Learn the engineering principles behind Alnoms
  • Case Studies: Contribute real-world performance audits

We’re excited to build the future of Performance Intelligence with you.