Trapster Documentation

Appearance

Coding Guidelines Community ​

Thank you for contributing to Trapster Community Edition. This page covers coding standards, the pull request process, and legal requirements.

If you have not set up a local environment yet, start with Development Setup.

Pull request workflow ​

Contributions are welcome. Please follow these steps:

  1. Fork the repository
  2. Create a branch : git checkout -b feature-branch
  3. Make your changes
  4. Commit : git commit -m 'Add new feature'
  5. Push : git push origin feature-branch
  6. Open a pull request against main

Keep pull requests focused: one logical change per PR is easier to review.

Branch naming ​

TypePatternExample
Featurefeature/descriptionfeature/ldap-query-logging
Fixfix/descriptionfix/ssh-banner-encoding
Documentationdocs/descriptiondocs/rsync-config

Before submitting ​

  • Update documentation if your change affects users
  • Add or update tests in tests/ for new behavior
  • Run the test suite and confirm it passes:
bash
python -m pytest tests/
  • Do not commit secrets, API keys, or environment-specific paths

PR description ​

  • Clearly describe what changed and why
  • Reference related GitHub issues
  • Include screenshots for UI or HTTP skin changes
  • Call out breaking changes explicitly

Review process ​

  • Address review comments promptly
  • Keep the PR scoped to a single change
  • Rebase on main if needed to resolve conflicts

For larger features, open a GitHub Discussion or issue first so maintainers can confirm the approach.

Contributor License Agreement (CLA) ​

You must sign the CLA before your first pull request can be merged.

When you open a PR for the first time, a bot comments with instructions to sign the Ballpoint Contributor License Agreement. You only sign once; future contributions to any Ballpoint project do not require signing again.

In short, the CLA:

  • Grants Ballpoint permission to use your contribution in open-source and commercial products
  • Includes a patent license for contributions that rely on patents you can license
  • Does not change the AGPLv3+ terms under which Community Edition is distributed
  • Does not require you to provide support or warranties for your contribution

Read the full agreement before signing. CLA information is used for tracking only, not for marketing.

License ​

Trapster Community Edition is licensed under the GNU Affero General Public License v3 or later (AGPLv3+). See the LICENSE file in the repository.

By contributing, you agree that your contributions will be licensed under the same terms.

Code style ​

Python ​

  • Follow PEP 8
  • Use type hints for function arguments and return values where practical
  • Maximum line length is 88 characters (Black default)
  • Add docstrings to modules, classes, and public functions
  • Match existing patterns under trapster/; services use the async framework in modules/

Example:

python
from typing import Optional

def process_data(input_data: list[str], max_length: Optional[int] = None) -> dict:
    """Process input data and return results."""
    result: dict = {}
    # ...
    return result

Configuration and HTTP skins ​

  • New services should work with trapster.conf and the wizard where applicable
  • HTTP skins use YAML under trapster/data/http/ : see HTTP honeypot

Commit messages ​

Follow Conventional Commits:

type(scope): description
TypeUse for
featNew feature
fixBug fix
docsDocumentation
styleFormatting, no logic change
refactorCode restructuring
testTests
choreMaintenance

Examples:

feat(web): add new HTTP template engine
fix(ssh): resolve connection handling issue
docs: update installation instructions

Testing ​

  • Write unit tests for new features
  • Include integration tests when behavior spans multiple modules
  • Cover edge cases and error conditions
  • Run python -m pytest tests/ before opening a PR

Documentation ​

  • Update the README or docs when user-facing behavior changes
  • Add docstrings to new public APIs
  • Include configuration examples for new services or HTTP skins

Security ​

  • Never commit sensitive data
  • Report security vulnerabilities privately : follow SECURITY.md, do not open public issues
  • Validate and sanitize untrusted input in new protocol handlers

Community ​

  • Be respectful and inclusive in issues, discussions, and reviews
  • Help others when you can
  • GitHub Discussions : questions and design ideas
  • Discord : chat with the community and the Ballpoint team

Questions? ​