Contributing to Gyselalib++

Thank you for your interest in contributing to this project. This codebase is part of an academic research effort and is maintained with a focus on accuracy, reproducibility, and clarity. We welcome contributions that improve the project within these boundaries. However, due to the sensitive and specific nature of the research goals, we ask that all proposed changes, especially new features or significant modifications, be discussed with the core team before any work begins.

Bug Reports

One of the most valuable contributions you can make is to report bugs. Bugs can take a variety of forms including:

• incorrect results
• unexpected behaviour
• unclear documentation

Identifying and documenting these issues plays a crucial role in maintaining the integrity and reliability of the code. If you encounter a bug, please open an issue providing as much detail as possible (as indicated by the template). This helps us address problems efficiently and ensures the project remains robust and trustworthy.

Feature Requests

We welcome thoughtful suggestions that enhance the usability, flexibility, or performance of the code. Suggestions should ensure that they are applicable to multiple simulations and can therefore benefit the community. Feature requests that are highly specific to individual test cases are unlikely to be accepted unless a clear benefit to the wider user base can be demonstrated.

To propose a new feature, please open an issue to discuss your idea with the team. This helps ensure alignment with the project’s goals and avoids duplication of effort.

Contributing Code

We appreciate and encourage all contributions that improve the clarity and accuracy of the documentation. Bug fixes that are well-scoped and consistent with the existing codebase are also encouraged.

For security reasons, we cannot run code from forks on our GPU runners. For this reason, contributors who wish to make more substantial changes (e.g., implementing new functionality, modifying core logic, or introducing external dependencies) must first discuss their plans with the core team and request to join the project with elevated privileges. This is essential to maintain code integrity, enable proper testing, and ensure alignment with the project's academic and technical objectives.

Please do not open large pull requests without prior discussion, as they may be closed without review.

All pull requests will be automatically tested. Please review the test results and ensure your changes do not introduce regressions. In addition, any new functionality or bug fix must be accompanied by appropriate tests. Test coverage is monitored, and submissions that reduce coverage without justification may not be accepted.

Please also make sure your code adheres to our coding standards, which are detailed in the project documentation.