Contributing to Reflaxe.Elixir

Thank you for your interest in contributing to Reflaxe.Elixir! This document provides guidelines and instructions for contributing to the project.

Code of Conduct
Getting Started
Development Setup
Making Changes
Commit Guidelines
Testing
Releasing
Pull Request Process
Project Structure

Code of Conduct

Please be respectful and considerate in all interactions. We aim to maintain a welcoming and inclusive environment for all contributors.

Getting Started

Fork the repository
Clone your fork locally
Set up the development environment (see below)
Create a new branch for your changes
Make your changes following our guidelines
Submit a pull request

Development Setup

Prerequisites

Node.js 16+ (for lix package management)
Elixir 1.14+ (for Phoenix/Ecto ecosystem)
Git

Installation

# Clone the repository
git clone https://github.com/fullofcaffeine/reflaxe.elixir.git
cd reflaxe.elixir

# Install dependencies (both ecosystems)
npm install       # Installs lix + Haxe dependencies
npx lix download  # Downloads project-specific Haxe libraries
mix deps.get      # Installs Elixir dependencies
npm run hooks:install # Installs repo pre-commit checks

# Run tests to verify setup
npm test          # Run Haxe compiler tests
npm run test:mix  # Run Elixir runtime tests

If you use bd git hooks, install them in chained mode so repo checks stay active:

bd hooks install --chain
npm run hooks:install

Making Changes

Branch Naming

feat/ - New features
fix/ - Bug fixes
docs/ - Documentation changes
refactor/ - Code refactoring
test/ - Test additions or changes
chore/ - Maintenance tasks

Releasing

See: RELEASING.md.

Example: feat/add-supervisor-support

Code Style

Follow existing code patterns in the codebase
Use meaningful variable and function names
Add comments for complex logic
Keep functions focused and small
Ensure no compilation warnings

Adding Features

Create a helper compiler in src/reflaxe/elixir/helpers/
Add annotation support to ElixirCompiler.hx if needed
Write comprehensive tests
Update documentation
Add examples if applicable

Commit Guidelines

We use Conventional Commits for automated versioning and changelog generation.

Commit Message Format

<type>(<scope>): <subject>

<body>

<footer>

Types

feat: A new feature (triggers minor version bump)
fix: A bug fix (triggers patch version bump)
docs: Documentation only changes
style: Code style changes (formatting, etc.)
refactor: Code change that neither fixes a bug nor adds a feature
perf: Performance improvements
test: Adding or updating tests
chore: Maintenance tasks, dependency updates
ci: CI/CD configuration changes

Breaking Changes

Add BREAKING CHANGE: in the footer or ! after the type for major version bumps:

feat!: redesign annotation system

BREAKING CHANGE: @:module annotation renamed to @:elixir_module

Examples

# Feature
git commit -m "feat(liveview): add support for live components"

# Bug fix
git commit -m "fix(compiler): handle null values in pattern matching"

# Documentation
git commit -m "docs(readme): add installation troubleshooting section"

# Breaking change
git commit -m "feat(api)!: change compiler initialization API

BREAKING CHANGE: ElixirCompiler.init() now requires config parameter"

Scope Examples

compiler - Core compiler changes
liveview - Phoenix LiveView features
ecto - Ecto integration
otp - OTP/GenServer features
types - Type system changes
docs - Documentation
tests - Test infrastructure

Testing

Running Tests

# Run all tests
npm test          # Haxe compiler tests
npm run test:mix  # Elixir runtime tests
npm run test:all  # Both test suites

# Update test snapshots
npm run test:update

# Run specific test
haxe test/SpecificTest.hxml

Understanding Test Output

Expected vs Unexpected Errors

Reflaxe.Elixir's test suite distinguishes between expected test behavior and real errors:

✅ Expected Test Warnings (Normal)

[warning] Haxe compilation failed (expected in test): Library reflaxe.elixir is not installed

These are normal - tests run in isolated environments
No ❌ symbol - indicates expected behavior
Don't fix these - they're part of the test design

❌ Real Errors (Need Attention)

[error] ❌ Haxe compilation failed: src_haxe/Main.hx:5: Type not found : MyClass

These need fixing - indicate actual compilation problems
Show ❌ symbol - signals real issues
Should cause test failure - if tests pass with these, that's a bug

CI Behavior

When running in GitHub Actions:

Green checkmarks mean all tests passed (warnings are OK)
Red X marks mean tests failed (real errors occurred)
Expected warnings don't fail CI - only real errors do

For Pull Requests

Your PR should:

✅ Pass all tests (green CI status)
✅ May show expected warnings (that's normal)
❌ Should not introduce new real errors (❌ symbols)

Docs drift guards (maintainers)

We keep “new user” docs honest with two CI checks:

Markdown link guard: ensures intra-repo links resolve (and catch case-only bugs that fail on Linux).

npm run guard:docs-links

Docs Smoke (Phoenix): generates a fresh Phoenix app via the generator and runs a compile-only smoke (no servers).

This is the same command CI runs:

bash scripts/ci/docs-smoke.sh --verbose

What it does (high level):

installs the Phoenix generator (phx_new) and ensures the repo’s lix toolchain is downloaded
runs reflaxe.elixir create --type phoenix into a temp workspace
inside the generated project: npm install, lix scope create, lix dev reflaxe.elixir <repo>, mix deps.get, mix compile

Runtime boot + browser E2E are intentionally not part of docs smoke; that’s covered by the todo-app QA sentinel.

Separately, a scheduled CI workflow (README Release Smoke (scheduled)) validates the “install from GitHub Release tag” path stays working without making PR CI flaky.

Repo hygiene helpers (contributors)

These are heuristic audits intended to keep the repo tidy. They do not prove that something is unused.

Dead-ish Haxe types + stale commented debug: scripts/repo-dead-code-audit.sh --scope src/reflaxe/elixir --limit 50
JSON report (CI/bd-friendly): scripts/repo-dead-code-audit.sh --scope src/reflaxe/elixir --limit 200 --json > tmp/dead-code-audit.json
Candidate unused scripts: scripts/repo-unused-scripts-audit.sh
Hygiene sweep (includes a bounded --apply mode for safe removals): scripts/repo-hygiene-audit.sh

Writing Tests

Unit Tests: Test individual compiler components
Integration Tests: Test feature combinations
Snapshot Tests: Verify generated Elixir output
Mix Tests: Validate runtime behavior

Example test structure:

package test;

import reflaxe.elixir.helpers.YourHelper;

class YourHelperTest {
    public static function main() {
        testBasicFunctionality();
        testEdgeCases();
        testErrorHandling();
        trace("✅ All YourHelper tests passed!");
    }
    
    static function testBasicFunctionality() {
        // Test implementation
    }
}

Pull Request Process

Before Submitting
- Ensure all tests pass (npm run test:all)
- Update documentation if needed
- Add tests for new features
- Follow commit message guidelines
- Update CHANGELOG.md if making significant changes

PR Description Template

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Testing
- [ ] Tests pass locally
- [ ] Added new tests
- [ ] Updated snapshots if needed

## Checklist
- [ ] Follows code style
- [ ] Self-reviewed code
- [ ] Updated documentation
- [ ] No new warnings

Review Process
- PRs require at least one approval
- Address review feedback promptly
- Keep PRs focused and atomic
- Squash commits if requested

Project Structure

reflaxe.elixir/
├── src/                    # Compiler source code
│   ├── reflaxe/elixir/
│   │   ├── ElixirCompiler.hx    # Main compiler entrypoint
│   │   ├── ast/                 # TypedExpr → ElixirAST pipeline (default)
│   │   ├── macros/              # Macro processors (Phoenix/Ecto/etc.)
│   │   └── helpers/             # Shared compiler helpers
├── std/                    # Standard library externs
│   ├── elixir/            # Elixir stdlib
│   └── phoenix/           # Phoenix framework
├── test/                   # Test files
├── examples/               # Example projects
├── docs/                   # Project documentation
├── haxe_libraries/         # Self-referential haxelib configs
└── lib/                    # Mix integration

Getting Help

Open an issue for bugs or feature requests
Join discussions in GitHub Discussions
Check existing issues before creating new ones
Provide minimal reproducible examples for bugs

Recognition

Contributors will be acknowledged in:

CHANGELOG.md for their contributions
README.md contributors section (for significant contributions)
Release notes when features are shipped

Thank you for contributing to Reflaxe.Elixir! 🎉

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Contributing to Reflaxe.Elixir

Table of Contents

Code of Conduct

Getting Started

Development Setup

Prerequisites

Installation

Making Changes

Branch Naming

Releasing

Code Style

Adding Features

Commit Guidelines

Commit Message Format

Types

Breaking Changes

Examples

Scope Examples

Testing

Running Tests

Understanding Test Output

Expected vs Unexpected Errors

CI Behavior

For Pull Requests

Docs drift guards (maintainers)

Repo hygiene helpers (contributors)

Writing Tests

Pull Request Process

Project Structure

Getting Help

Recognition

FilesExpand file tree

contributing.md

Latest commit

History

contributing.md

File metadata and controls

Contributing to Reflaxe.Elixir

Table of Contents

Code of Conduct

Getting Started

Development Setup

Prerequisites

Installation

Making Changes

Branch Naming

Releasing

Code Style

Adding Features

Commit Guidelines

Commit Message Format

Types

Breaking Changes

Examples

Scope Examples

Testing

Running Tests

Understanding Test Output

Expected vs Unexpected Errors

CI Behavior

For Pull Requests

Docs drift guards (maintainers)

Repo hygiene helpers (contributors)

Writing Tests

Pull Request Process

Project Structure

Getting Help

Recognition