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
   

3. Install dependencies and set up pre-commit hooks:

   ⧉

   just install
   

4. Run tests to ensure everything works:

   ⧉

   just test
   

5. 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
   

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

3. Add tests for new functionality:

   ⧉

   just test
   

4. Run benchmarks if modifying parser performance:

   ⧉

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

5. Run linting:

   ⧉

   just lint
   

6. 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:

   • Ensure just ci-check passes (pre-commit hooks + lint + tests)
   • Update documentation if needed
   • Include tests for new functionality

2. PR Description:

   • Clearly describe what changes were made
   • Reference any related issues
   • Include examples of new functionality
   • Note any breaking changes

3. Review process:

   • All PRs require at least one review (human or CodeRabbit)
   • CI must pass (golangci-lint, gofumpt, tests, govulncheck, CodeQL, Trivy)
   • 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!