Contributing to AshReports

Thank you for your interest in contributing to AshReports! This document provides guidelines and instructions for contributing.

Getting Started

1. Fork the repository on GitHub
2. Clone your fork locally:

   git clone https://github.com/your-username/ash_reports.git
   cd ash_reports
   

3. Install dependencies:

   mix deps.get
   

4. Run the tests to ensure everything works:

   mix test
   

Development Setup

Prerequisites

• Elixir 1.15 or later
• Erlang/OTP 26 or later
• PostgreSQL (for integration tests)

Running Tests

# Run all tests
mix test

# Run a specific test file
mix test test/path/to/test.exs

# Run a specific test by line number
mix test test/path/to/test.exs:42

Code Quality

Before submitting a PR, ensure your code passes all checks:

# Format code
mix format

# Run Credo for static analysis
mix credo

# Run Dialyzer for type checking
mix dialyzer

How to Contribute

Reporting Bugs

1. Check existing issues to avoid duplicates
2. Create a new issue with:
   • Clear, descriptive title
   • Steps to reproduce
   • Expected vs actual behavior
   • Elixir/OTP versions
   • Relevant code snippets or error messages

Suggesting Features

1. Check the ROADMAP.md for planned features
2. Open a discussion or issue describing:
   • The use case
   • Proposed solution
   • Alternatives considered

Submitting Pull Requests

1. Create a feature branch from develop:

   git checkout develop
   git checkout -b feature/your-feature-name
   

2. Make your changes following our coding standards

3. Add tests for new functionality

4. Update documentation if needed

5. Ensure all tests pass:

   mix test
   

6. Commit with a clear message:

   git commit -m "Add feature: description of what it does"
   

7. Push and create a Pull Request against develop

Coding Standards

General Guidelines

• Follow the Elixir Style Guide
• Use mix format before committing
• Keep functions small and focused
• Write descriptive function and variable names

Documentation

• Document all public functions with @doc
• Include examples in documentation where helpful
• Update guides if adding user-facing features

Testing

• Write tests for all new functionality
• Aim for high test coverage
• Use descriptive test names
• Group related tests with describe blocks

Commit Messages

• Use present tense ("Add feature" not "Added feature")
• Keep the first line under 72 characters
• Reference issues when applicable ("Fix #123")

Project Structure

lib/
  ash_reports/
    charts/          # Chart generation system
    data_loader/     # Data loading pipeline
    layout/          # Layout IR and positioning
    live_view/       # LiveView integration
    renderer/        # Output renderers (HTML, Typst, JSON)
    reports/         # Core report structures
    dsl.ex           # DSL definitions
    runner.ex        # Report execution

Questions?

• Open a discussion on GitHub
• Check existing issues and discussions

License

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