Contributing guidelines

We welcome your contributions to x3d2! To ensure effective collaboration, please follow the guidelines outlined below.

General principles

  • Create an issue before opening a Pull Request (PR)

  • Keep PRs small and focused with detailed descriptions

  • Ensure Fortran code is formatted with fprettify

  • Write tests for new features and bug fixes

  • Request a maintainer to review your PR before merging

  • Rebase your branch on top of the latest main before merging

Issues first

  • Open an issue before starting work on a feature or bug fix, unless one already exists.

  • Open issues as early as possible to avoid wasted effort and ensure alignment.

  • Provide detailed descriptions and relevant context in issues.

  • Assign issues to the person responsible for the work to avoid duplication.

  • Keep issues updated with the latest information and status.

  • Close issues once the work is complete to maintain project organization.

Note

Prototyping is encouraged and can help write the issue content. However, open an issue before committing to a specific design or implementation.

Commit message guidelines

To keep commit history readable and maintainable, we recommend the following best practices:

  • Write clear and concise commit messages.

  • Use short messages for minor changes. Messages like “Fix typo” or “Update documentation” are acceptable for small updates.

  • Make atomic commits: Each commit should represent a single logical change. Avoid bundling unrelated changes in a single commit.

  • Reference relevant issue numbers in commit messages to provide context (e.g., “Fixes #123”).

  • Provide a detailed description in the commit message body if the change is not self-explanatory.

Code formatting

  • Use fprettify for automatic Fortran formatting. Some non-default configuraiton options are specified in the project’s .fprettify.ini file.

  • We recommend installing the pre-commit hook to automatically format your code before each commit. Alternatively you can run fprettify manually before submitting a pull request.

  • PRs will not be merged unless all code conforms to formatting.

Pull requests and code review

  • PRs must be small and focused (one PR per feature/bug fix).

  • Write meaningful PR desriptions to help reviewers. This should include:

    • Summary of changes

    • Technical explanation of key modifications

    • Link to the relevant issue

    • Test results (if applicable)

  • Self-review your code and ensure tests pass before requesting a review.

  • PRs must be approved by at least one maintainer before merging.

  • For high-impact changes a second review is recommended but not required.

  • For small, non-critical PRs (e.g. documentation, minor formatting), self-merging is allowed.

Merging best practices

Before merging your PR to main, follow these guidelines.

  • Rebase instead of merging: Rebase your feature branch on top of the latest main to avoid unnecessary merge commits and keep the commit history linear.

# Fetch the latest changes from the original repository
git fetch upstream

# Checkout your feature branch
git checkout my-feature-branch

# Rebase your branch on top of the latest main
git rebase upstream/main

  • Resolve conflicts during rebase: If there are conflicts during rebase, resolve them manually. Use the following commands to continue the rebase after resolving conflicts:

# Add the resolved files
git add .

# Continue the rebase
git rebase --continue

  • We leave it to the developer to decide whether they want to squash commits before merging. For large PRs, you may want to keep the commit history provided that:

    • Each commit is atomic and represents a single meaningful change that is complete and self-consistent.

    • The code should not be broken at any commit in the history (i.e., each commit should pass all tests). If a bug is introduced in a commit, it should be fixed in the same commit without creating a new commit.

The main aim of these guidelines is to keep the merge history linear and readable.