Skip to content

Contributing Guide

Thank you for your interest in contributing to opnDossier! This guide will help you get started with development and understand our contribution process.

Development Environment Setup

Prerequisites

  • Go 1.26+
  • Git with GPG signing configured
  • Just - Task runner (required for CI-equivalent checks)
  • golangci-lint - Go linter (latest version recommended)
  • pre-commit - Git hook framework

Getting Started

  1. Fork the repository on GitHub

  2. Clone your fork locally:

git clone https://github.com/yourusername/opnDossier.git
cd opnDossier
  1. Install dependencies and set up pre-commit hooks:
just install
  1. Run tests to ensure everything works:
just test
  1. Run all quality checks (CI-equivalent):
just ci-check

Development Workflow

Code Organization

The project follows standard Go conventions:

  • cmd/ - CLI commands (Cobra framework)
  • internal/ - Internal packages
  • cfgparser/ - XML parsing and validation
  • config/ - Configuration management (Viper)
  • converter/ - Data conversion and report generation
  • compliance/ - Plugin interfaces
  • plugins/ - Compliance plugin implementations (stig, sans, firewall)
  • audit/ - Audit engine and plugin management
  • display/ - Terminal display formatting
  • export/ - File export functionality
  • logging/ - Structured logging (wraps charmbracelet/log)
  • progress/ - CLI progress indicators
  • validator/ - Configuration validation
  • pkg/ - Public API packages
  • model/ - Platform-agnostic CommonDevice domain model
  • parser/ - Factory + DeviceParser interface
    • opnsense/ - OPNsense parser + schema→CommonDevice converter
  • schema/opnsense/ - Canonical OPNsense XML data model structs
  • docs/ - Documentation
  • testdata/ - Test fixtures and sample configuration files

Making Changes

  1. Create a feature branch:
git checkout -b feature/your-feature-name

  1. Make your changes following our development standards and the coding standards in AGENTS.md

  2. Add tests for new functionality:

just test
  1. Run benchmarks if modifying parser performance:
go test -run=^$ -bench=. ./internal/cfgparser/
  1. Run linting:
just lint
  1. Run all CI-equivalent checks before committing:
just ci-check

Parser Development

When modifying parsing or conversion logic:

  • pkg/parser/ -- Factory and DeviceParser interface (public API)
  • pkg/parser/opnsense/ -- OPNsense parser and schema-to-CommonDevice converter
  • pkg/schema/opnsense/ -- Canonical OPNsense XML schema structs
  • pkg/model/ -- Platform-agnostic CommonDevice domain model
  • internal/cfgparser/ -- Low-level XML parsing and validation
  • Test with sample files in testdata/
  • Add benchmarks for performance-critical changes
  • Preserve backward compatibility in the DeviceParser interface

Testing

We maintain several types of tests:

  • Unit tests: Test individual functions and methods
  • Integration tests: Test complete workflows end-to-end
  • Golden file tests: Snapshot tests using sebdah/goldie/v2
  • Performance tests: Benchmarks for parser memory and speed
  • Error handling tests: Verify proper error reporting

Run specific test suites:

# All tests
just test

# Specific package
go test ./internal/cfgparser/

# Benchmarks only
go test -run=^$ -bench=. ./internal/cfgparser/

# With coverage
go test -cover ./...

# Race detection
just test-race

Commit Standards

Commit Message Format

<type>(<scope>): <description>

Types: feat, fix, docs, style, refactor, perf, test, build, ci, chore

Scopes: (parser), (converter), (audit), (cli), (model), (plugin), (builder), (schema)

DCO Sign-off

All commits must include a DCO sign-off:

git commit -s -m "feat(parser): add support for new XML element"

Pull Request Process

  1. Before submitting:

  2. Ensure just ci-check passes (pre-commit hooks + lint + tests)

  3. Update documentation if needed

  4. Include tests for new functionality

  5. PR Description:

  6. Clearly describe what changes were made

  7. Reference any related issues
  8. Include examples of new functionality

  9. Note any breaking changes

  10. Review process:

  11. All PRs require at least one review (human or CodeRabbit)

  12. CI must pass (golangci-lint, gofumpt, tests, CodeQL, Grype)
  13. Documentation updates may be requested

Coding Standards

Please follow the coding standards documented in AGENTS.md, which covers:

  • Go coding conventions and naming
  • Error handling patterns
  • Logging with charmbracelet/log
  • Thread safety patterns
  • XML element presence detection
  • Testing standards

Performance Considerations

This project processes potentially large XML files, so performance matters:

  • Add benchmarks for significant algorithmic changes
  • Consider memory allocation patterns
  • Test with sample files of varying sizes in testdata/
  • The parser limits input to 10MB by default (DefaultMaxInputSize)

Getting Help

  • Check existing issues and documentation first
  • Open an issue for bugs or feature requests
  • Review AGENTS.md for detailed development standards
  • Review the architecture documentation in docs/development/

License

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

Thank you for contributing to opnDossier!