Skip to content

Contributing

Development Environment

The project includes a DevContainer configuration for VS Code:

  • Base image: ghcr.io/netbox-community/netbox:v4.5.3-4.0.0
  • Database: postgis/postgis:16-3.4 (PostgreSQL 16 + PostGIS 3.4)
  • Cache: Redis 7 Alpine
  • Tools: fish shell, oh-my-fish, GitHub CLI

Getting Started

  1. Clone the repository
  2. Open in VS Code with the Dev Containers extension
  3. The container automatically installs the plugin in editable mode

Running the Dev Server

cd /opt/netbox
python manage.py runserver 0.0.0.0:8000

Running Migrations

python manage.py migrate netbox_pathways

Code Style

Python

  • Linter: ruff
  • Line length: 120 characters
  • Target: Python 3.12+
  • Enabled rules: E, F, W, I, N, UP, S, B, A, C4, DJ, PIE

Run the linter:

ruff check netbox_pathways/
ruff check --fix netbox_pathways/  # auto-fix

TypeScript

  • Target: ES2016
  • Strict mode: enabled
  • Build: esbuild (IIFE bundles)

Run type checking:

cd netbox_pathways/static/netbox_pathways
npm run typecheck

Build bundles:

npm run build

Testing

Tests use pytest with pytest-django:

pytest
pytest -v                          # verbose
pytest tests/test_registry.py      # specific file
pytest -k "test_register"          # by name pattern

Coverage report:

pytest --cov=netbox_pathways --cov-report=term-missing

Test Structure

tests/
├── conftest.py           # Shared fixtures
├── test_registry.py      # Map layer registry tests
├── test_external_geo.py  # External GeoJSON endpoint tests
└── ...

Commit Messages

Format: topic(subtopic): description

Topic Use
feat New feature
fix Bug fix
refactor Code restructure (no behavior change)
chore Maintenance, dependencies
docs Documentation
tests Test additions/changes
linting Code style fixes

Examples:

feat(models): add Structure and Pathway models
fix(views): correct conduit bank queryset
chore(deps): update ruff to 0.9.x
docs(map): add interactive map documentation

Warning

A git hook rejects commit messages containing AI attribution lines (Co-Authored-By:, Generated by/with). Do not include these in commit messages.

Pull Requests

  1. Create a feature branch from main
  2. Make your changes with tests
  3. Run linting and tests: ruff check . && pytest
  4. Run Django system checks: python manage.py check --deploy
  5. Push and create a PR

Architecture Notes

  • Follow NetBox plugin conventions for views, forms, tables, and serializers
  • Use the NetBox 4.5 layout system (SimpleLayout + panels) for detail views
  • All geographic fields use PostGIS via django.contrib.gis
  • GeoJSON endpoints use djangorestframework-gis serializers
  • Frontend TypeScript targets ES2016 for browser compatibility
  • Leaflet is loaded from vendor files, not bundled