Contributing

Contributing

Thank you for your interest in contributing to Apotropaios. This guide covers how to participate effectively.

Ways to Contribute

• Bug Reports — File detailed issues with reproduction steps
• Feature Requests — Propose new capabilities with use-case descriptions
• Code Contributions — Submit pull requests for bugs, features, or improvements
• Documentation — Improve wiki pages, add examples, fix errors
• Testing — Run the framework on new distributions, report compatibility issues

Bug Reports

When filing a bug report, include:

1. OS and version: cat /etc/os-release
2. Bash version: bash --version
3. Apotropaios version: ./apotropaios.sh --version
4. Installed firewalls: which iptables nft firewall-cmd ufw ipset
5. Steps to reproduce: Exact commands and menu selections
6. Expected behavior: What should have happened
7. Actual behavior: What happened instead (include full error output)
8. Log excerpt: Relevant entries from data/logs/apotropaios-*.log

Use --log-level trace when reproducing to capture maximum diagnostic detail.

Pull Request Process

Before Starting

1. Check existing issues and PRs to avoid duplicating work
2. For significant changes, open an issue first to discuss the approach
3. Read the Development Guide for coding standards

Branch Strategy

• Branch from develop (not main)
• Name branches descriptively: fix/ipset-set-name-validation, feature/rule-expiry-notification

Code Requirements

• All changes pass make lint (zero ShellCheck warnings)
• All existing tests pass: make test
• New functionality has tests
• Code follows existing naming conventions and patterns
• Functions have documentation headers
• No hardcoded values — use constants from constants.sh
• Input validation on all new user-facing parameters
• Log messages for all significant operations

Documentation Requirements

• Update docs/changelog.md under [Unreleased]
• Update tasks/sync_function.md if dependencies change
• Update relevant wiki pages
• Update CLI help text if commands change
• Update README if major features are added

PR Checklist

## Description
Brief description of what this PR does.

## Type
- [ ] Bug fix
- [ ] New feature
- [ ] Enhancement
- [ ] Documentation
- [ ] Testing

## Testing
- [ ] `make lint` passes
- [ ] `make test` passes (all 97+ tests)
- [ ] New tests added for new functionality
- [ ] Tested on: [list distributions tested]

## Checklist
- [ ] Code follows project coding standards
- [ ] Functions have documentation headers
- [ ] Input validation added where needed
- [ ] Changelog updated
- [ ] sync_function.md updated (if applicable)

Code of Conduct

• Be respectful and constructive in all interactions
• Focus on the technical merits of contributions
• Welcome newcomers and help them get started
• Security vulnerabilities should be reported privately (see Security Policy)

Recognition

Contributors are recognized in the changelog and release notes. Significant contributions are acknowledged in the README.