Skip to content

Latest commit

 

History

History
129 lines (81 loc) · 6.37 KB

CONTRIBUTING.md

File metadata and controls

129 lines (81 loc) · 6.37 KB
Raw

Contributing to elastix

Thank you for considering contributing to elastix!

Do you have questions about the source code?

  • Ask any question about how to use elastix on the mailing list.

  • Do not open an issue on GitHub for general questions, registration questions, or issues you may have while running elastix. GitHub issues are primarily intended for bug reports and fixes.

  • General information about elastix can be found on our wiki or at the website.

  • The manual explains much of the inner workings of image registration.

Did you find a bug?

  • Ensure the bug was not already reported by searching on GitHub under Issues.

  • If you're unable to find an open issue addressing the problem, you can open a new one. Be sure to include a title and clear description, as much relevant information as possible. A code sample with a test demonstrating the expected behavior that is not occurring would be awesome.

Do you intend to add a new feature or change an existing one?

  • Suggest your change on the elastix mailing list.

  • Do not open an issue on GitHub until you have collected positive feedback about the change.

Did you write a patch that fixes a bug?

  • Open a new GitHub pull request (PR) with the patch.

  • Make sure the PR is done with respect to the main branch.

  • Ensure the PR description (log message) clearly describes the problem and solution. Include the relevant issue number if applicable. One-line messages are fine for small changes, but bigger changes should look like this: $ git commit -m "ENH: A brief summary of the commit

    A paragraph describing what changed and its impact."

  • We use the following tags for commit messages:

    • ENH: for functional enhancements of the code
    • BUG: for fixing runtime issues (crash, segmentation fault, exception, or incorrect result)
    • COMP: for compilation issues (error or warning)
    • PERF: for performance improvements
    • STYLE: a change that does not impact the logic or execution of the code (improve coding style, comments, documentation)

The body of the message should clearly describe the motivation of the commit (what, why, and how). In order to ease the task of reviewing commits, the message body should follow the following guidelines:

  1. Leave a blank line between the subject and the body. This helps git log and git rebase work nicely, and allows to smooth generation of release notes.
  2. Try to keep the subject line below 73 characters.
  3. Capitalize the subject line.
  4. Do not end the subject line with a period.
  5. Use the imperative mood in the subject line (e.g. BUG: Add missing spacing).
  6. Use semantic line feeds to separate different ideas, which improves the readability.
  7. Be concise, but honor the change: if significant alternative solutions were available, explain why they were discarded.
  8. If the commit refers to a topic discussed in elastix' mailing list, or fixes a regression test, provide the link. If it fixes a compiler error, provide a minimal verbatim message of the compiler error. If the commit closes an issue, use the GitHub issue closing keywords.

Keep in mind that the significant time is invested in reviewing commits and pull requests, so following these guidelines will greatly help the people doing reviews.

These guidelines are largely inspired by Chris Beam's How to Write a Commit Message post.

  • Ensure the PR adheres to our coding conventions, the PR code format will be checked with clangFormat on the CI. The hook can be used locally, for details see below.

  • We will review your PR and possibly suggest changes. All PR will be tested on the GitHub Actions CI. When all lights are green, the PR will be merged.

  • More information on pull requests can be found here and here.

Pre-commit clangFormat hook

A pre-commit hook that formats the code in the repository according to the correct clangFormat, is available for git. In order to use the hook, it is has to be moved to the .git/hooks folder locally:

For Unix:

cp .githooks/pre-commit .git/hooks

chmod u+x .git/hooks/pre-commit

For Windows:

copy .githooks\pre-commit .git\hooks

The pre-commit hooks is triggered by any git commit message, if files that don't adhere to the correct clangFormat style are found, these files are changes. Run git status or git diff to see these changes. Changes, if found, have to be re-added and re-commited with git, make sure to use the --amend flag when re-commiting to keep the commit history clean.

Coding conventions

Start reading our code and you'll get the hang of it. We optimize for readability:

  • We indent using two spaces (soft tabs). This ensures a consistent layout of the code on different text editors.

  • We ALWAYS put spaces after list items and function arguments ([1, 2, 3], not [1,2,3]), around operators (x += 1, not x+=1), etc.

  • Use /** ... */ style documentation.

  • Member variables of classes should start their name with m_. For example: m_NumberOfIterations.

  • Type definitions should start with a capital. ImageType for example, instead of imageType.

  • This is open source software. Consider the people who will read your code, and make it look nice for them. It's sort of like driving a car: Perhaps you love doing donuts when you're alone, but with passengers the goal is to make the ride as smooth as possible.

Code of conduct

Please respect our code of conduct.

Thanks, The elastix team