Contributing

Contributing

Contributions to phoss-ap are welcome! Whether you are a Peppol service provider, an integrator, or a developer interested in e-invoicing infrastructure, there are many ways to get involved.

Ways You Can Contribute

Contributions are not limited to core code. Here are some areas where help is appreciated:

• Fixing bugs -- Reproduce, diagnose, and fix issues reported in the issue tracker.
• Improving documentation -- Clarify existing wiki pages, add missing details, or fix inaccuracies.
• Adding deployment examples -- Docker, Kubernetes, systemd, cloud-specific deployment guides, etc.
• Writing integration guides -- Walkthroughs for connecting phoss-ap with specific ERP systems, document platforms, or national Peppol infrastructures.
• Adding test cases -- Increase test coverage for existing modules, especially edge cases in retry logic, duplicate detection, and MLS handling.
• Performance tuning -- Profiling, benchmarking, and optimizing database queries, connection pooling, or AS4 message processing.
• Security improvements -- Reviewing configuration defaults, hardening deployment guides, or identifying potential vulnerabilities.
• Supporting new Peppol requirements -- Implementing changes from new Peppol Network Policy releases, updated MLS specifications, or new document types.

Getting Started

1. Fork the repository and clone it locally.
2. Build the project: mvn clean install -DskipTests
3. Review the Maven Module Structure to understand how the codebase is organized.
4. Read the Architecture Overview for a high-level understanding of the system.

Finding Work

• Look for issues labeled good first issue in the issue tracker -- these are scoped tasks suitable for newcomers.
• Issues labeled help wanted indicate areas where maintainer bandwidth is limited and community contributions are especially welcome.
• If you want to work on something not yet tracked, open an issue first to discuss the approach.

Submitting Changes

1. Create a feature branch from main.
2. Keep commits focused -- one logical change per commit.
3. Ensure the project compiles: mvn clean compile
4. Run existing tests: mvn test (if applicable)
5. Open a pull request with a clear description of what the change does and why.

Code Conventions

• Java 21 language level, runs with latest Java LTS version
• No need to follow the existing code style - my formatter will resolve it afterwards
• Use constants from APConfigurationProperties for all configuration keys -- no hardcoded strings in business logic.
• No Spring dependencies outside phoss-ap-webapp.

Reporting Issues

When reporting a bug, please include:

• Steps to reproduce the problem.
• Expected vs. actual behavior.
• Relevant log output or stack traces.
• phoss-ap version and Java version.