Skip to content

Latest commit

 

History

History
94 lines (80 loc) · 4.2 KB

CONTRIBUTING.md

File metadata and controls

94 lines (80 loc) · 4.2 KB
Raw

Contributing to Uncrustify

How to contribute

There are lots of ways to contribute to Uncrustify:

  • Report Issues

  • Propose Features or Improvements

  • Submit Pull Requests

Making changes

  • Pull latest master and create a new branch:

    • Branch name should use lowercase, using - to separate words and not _. Other special characters should be avoided. (However, feel free to use option names verbatim in branch names; _ should be used when part of an option name.)
    • A hierarchical structure may be designated using / (e.g. area/topic), although this is uncommon. The last part of the name can be keywords like bugfix, feature, optim, docs, refactor, test, etc.
    • Branches should be named after what the change is about.
    • Branches should not be named after the issue number, developer name, etc.

  • Organize your work:

    • Specialize your branch to target only one thing. Split your work in multiple branches if necessary.
    • Make commits of logical units.
    • Avoid "fix-up" commits. Instead, rewrite your history so that the original commit is "clean".
    • Try to write a quality commit message:
      • Separate subject line from body with a blank line.
      • Limit subject line to 50 characters.
      • Capitalize the subject line.
      • Do not end the subject line with a period.
      • Use imperative present tense in the subject line. A proper subject can complete the sentence "If applied, this commit will, [subject]".
      • Wrap the body at 72 characters.
      • Include motivation for the change and contrast its implementation with previous behavior. Explain the what and why instead of how.
    • If the git diff command, or the diff part of the git gui, don't produce accurate output, it might be necessary to add some lines to the ~/.gitconfig file: [diff] algorithm = patience [gui] diffopts = --patience

  • Add or update unit tests:

    • All behavioral changes should come with a unit test that verifies that the new feature or fixed issue works as expected.
    • Consider improving existing tests if it makes sense to do so.
    • Any unused test number may be used, however it is preferred to keep related tests together, if possible.
    • Read Writing Tests for more details.

  • Polish your work:

    • The code should be clean, with documentation where needed.
    • The change must be complete (no upcoming fix-up commits).
    • Functional changes should always be accompanied by tests (see above). Changes without tests should explain why tests are not present. (Changes that are non-functional, such as documentation changes, can usually omit tests without justification.)
    • Any updates to src/options.h, including option descriptions, should be accompanied by an update of the option documentation. This can be done by building uncrustify and then running: ./scripts/release_tool.py optiondocs path_to_uncrustify_binary

  • Prepare a Pull Request (PR):

    • To reduce the likelihood of conflicts and test failures, consider rebasing your work on top of latest master before creating a PR.
    • Verify that your code is working properly by running ctest in your build directory. (Changes that fail CI will not be merged. Running the tests locally will help to avoid this.) You can change the level of logging by changing the line 104 and 109 of the file tests/test_uncrustify/test.py to another value.
    • The PR title should represent what is being changed (a rephrasing of the branch name if set correctly).
    • The PR description should document the why the change needed to be done and not how, which should be obvious by doing the code review.
    • After commiting a new PR, one may have a look to the results: https://coveralls.io/github/uncrustify/uncrustify