Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
185 lines (129 loc) · 5.38 KB

CONTRIBUTING.md

File metadata and controls

185 lines (129 loc) · 5.38 KB
Raw

Contributing to AntennaSim

Thank you for your interest in contributing to AntennaSim! This guide will help you get started.

Development Setup

Prerequisites

Getting Started

  1. Fork the repository and clone your fork:
git clone https://github.com/YOUR_USERNAME/AntennaSim.git
cd AntennaSim
  1. Create the environment file:
cp .env.example .env
  1. Start the development environment:
./scripts/dev.sh

Or manually:

docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build
  1. Access the application:
Service URL
Frontend http://localhost:5173
Backend API http://localhost:8000
API Docs (Swagger) http://localhost:8000/docs

Source directories are volume-mounted, so changes are reflected immediately via hot-reload.

Branch Naming

Create branches from main using the following prefixes:

Prefix Use for
feat/ New features
fix/ Bug fixes
docs/ Documentation changes
chore/ Maintenance, CI, tooling
refactor/ Code refactoring

Example: feat/horizontal-delta-loop, fix/simulation-timeout

Commit Messages

This project follows the Conventional Commits specification:

type(optional-scope): description

Types

Type Description
feat A new feature
fix A bug fix
docs Documentation changes
style Code style (formatting, semicolons, etc.)
refactor Code refactoring (no feature or fix)
perf Performance improvement
test Adding or updating tests
build Build system or dependencies
ci CI/CD configuration
chore Maintenance tasks

Examples

feat: add horizontal delta loop template
fix: resolve simulation timeout on large models
docs: update README with new screenshots
feat(templates): add EFHW antenna template

Important: PR titles must follow this format. When we squash-merge your PR, the title becomes the commit message on main.

Pull Request Guidelines

Before Opening a PR

  1. Sync your branch with the latest main. Rebasing is preferred to keep the PR history clean, but merging is also fine since we squash-merge all PRs:
# Preferred: rebase
git fetch origin
git rebase origin/main

# Also acceptable: merge
git fetch origin
git merge origin/main
  1. Run the checks locally:
cd frontend
npm run type-check    # tsc --noEmit
npm run lint          # eslint
npm run build         # tsc -b && vite build
  1. Make sure all three pass before opening the PR.

PR Description

Include the following in your PR description:

  • Summary -- What changed and why (1-3 bullet points)
  • Testing -- How you verified the changes work
  • Screenshots -- If the PR includes UI changes

Review Process

  • All PRs are reviewed by a maintainer before merging.
  • CI checks (type-check, lint, build) must pass.
  • PR title must follow Conventional Commits format.
  • PRs are squash-merged to keep main history clean.

Common Contributions

Adding a New Antenna Template

The most common contribution. See existing templates in frontend/src/templates/ for reference (e.g., delta-loop.ts, dipole.ts).

  1. Create frontend/src/templates/your-antenna.ts implementing the AntennaTemplate interface
  2. Register it in frontend/src/templates/index.ts (import + add to the templates array) -- this automatically makes it available in the Simulator, Editor, and Library
  3. Add your template ID to relatedTemplates arrays of related existing templates
  4. Update README.md -- increment the template count and add to the templates table
  5. Run npm run type-check && npm run build and test manually

Frontend Features

  • Components -- frontend/src/components/ (charts, 3D viewport, panels, common UI)
  • Pages -- frontend/src/pages/ (Simulator, Editor, Library, Learn, About)
  • State management -- frontend/src/stores/ (Zustand stores for antenna, simulation, editor, UI)
  • Routing -- React Router in frontend/src/App.tsx

Follow existing component patterns. Use TypeScript strict mode and type-only imports where possible.

Backend Features

  • API endpoints -- backend/src/ (FastAPI)
  • Simulation engine -- NEC2 runner, parsers, and result processing
  • The backend runs inside Docker -- use ./scripts/dev.sh for hot-reload development
  • Test API changes via Swagger at http://localhost:8000/docs

Bug Fixes

  • Open an issue first describing the bug (unless one already exists)
  • Reference the issue number in your PR (e.g., "Fixes #12")
  • Include steps to reproduce in the PR description

Code Style

  • TypeScript -- All frontend code is TypeScript with strict mode
  • ESLint -- Run npm run lint to check for issues
  • Formatting -- Follow the existing code style in the project
  • Imports -- Use type-only imports where possible (import type { ... })
  • NEC2 conventions -- Coordinates follow NEC2: X=east, Y=north, Z=up
  • Segmentation -- Use autoSegment() from ../engine/segmentation for wire segments

Questions?

If you have questions about contributing, feel free to open an issue with the question label or start a discussion on the repository.