Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
166 lines (118 loc) · 3.7 KB

CONTRIBUTING.md

File metadata and controls

166 lines (118 loc) · 3.7 KB

Contributing to EdgeFEM

Thank you for your interest in contributing to EdgeFEM! This document provides guidelines for contributing to the project.

Getting Started

  1. Fork the repository on GitHub
  2. Clone your fork locally: 
    git clone https://github.com/YOUR-USERNAME/EdgeFEM.git
cd EdgeFEM
  3. Build the project following the README instructions
  4. Run tests to ensure everything works: 
    ctest --test-dir build -j

Development Workflow

Branch Naming

  • feature/description - New features
  • fix/description - Bug fixes
  • docs/description - Documentation updates
  • refactor/description - Code refactoring

Making Changes

  1. Create a feature branch from main:

    git checkout -b feature/your-feature-name

  2. Make your changes, following the code style guidelines below

  3. Run formatting and linting:

    bash tools/lint.sh build

  4. Run tests:

    ctest --test-dir build -j

  5. Commit with clear messages:

    git commit -m "Add eigenmode solver for circular waveguides"

Code Style

C++

  • Standard: C++20
  • Formatting: clang-format (configuration in .clang-format)
  • Static Analysis: clang-tidy (configuration in .clang-tidy)
  • Namespace: All code in namespace edgefem

Run formatting before committing:

clang-format -i src/*.cpp include/edgefem/*.hpp

Python

  • Version: Python 3.9+
  • Style: PEP 8
  • Type Hints: Encouraged for public APIs

General Guidelines

  • Keep functions focused and under 50 lines when possible
  • Use descriptive variable names
  • Add comments for non-obvious algorithms
  • Prefer const correctness in C++

Testing

Writing Tests

  • Tests use simple assert() macros (no external framework)
  • Place tests in tests/ directory
  • Name test files test_*.cpp
  • Add appropriate CTest labels (smoke, pml, abc, etc.)

Running Tests

# All tests
ctest --test-dir build -j

# Quick smoke tests
ctest --test-dir build -L smoke

# Specific test
./build/tests/test_maxwell

Pull Request Process

Before Submitting

  1. Rebase on latest main:

    git fetch origin
git rebase origin/main

  2. Ensure CI will pass:

    • All tests pass
    • Code is formatted
    • clang-tidy has no warnings

  3. Update documentation if needed:

    • Update README.md for user-facing changes
    • Update API docs for new functions
    • Add/update tutorials for new features

PR Requirements

  • Green CI: All GitHub Actions checks must pass
  • Description: Clear explanation of what and why
  • Tests: New features need tests; bug fixes need regression tests
  • Docs: User-facing changes need documentation updates

Review Process

  1. Submit PR against main branch
  2. Address reviewer feedback
  3. Maintainer merges after approval

Architecture Decisions

Large features or architectural changes require an Architecture Decision Record (ADR):

  1. Create docs/adr/NNNN-title.md
  2. Describe context, decision, and consequences
  3. Get approval before implementation

Reporting Issues

Bug Reports

Include:

  • EdgeFEM version (git commit hash)
  • Operating system and compiler version
  • Minimal reproducing example
  • Expected vs actual behavior

Feature Requests

Include:

  • Use case description
  • Proposed API (if applicable)
  • Alternative approaches considered

Questions?

License

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