Welcome and thank you for your interest in contributing to OCamlFormat. This contribution guide will help you through the contribution process.
If you encounter an issue with OCamlFormat, or if you have inquiries, we encourage you to open a GitHub issue. Please follow the steps below:
- First, verify if your issue hasn't already been reported.
- Specify the OCamlFormat version you're using (
ocamlformat --version). - Include a (preferably short) source file that replicates the issue.
- Clearly define the expected and actual behavior.
- Remain engaged with the issue until closure as your feedback might be needed.
We heartily welcome pull requests. To ensure an effective contribution, please adhere to the steps below:
- For significant, invasive, or output-affecting changes, consider opening an issue for discussion before committing substantial time and effort.
- If you're new to the project, starting with the Good first issues can be beneficial.
- Fork the repository and create your branch from
main. - If you've added code that should be tested, supplement it with tests located in the
test/directory. - Ensure that the test suite passes (see Running the tests for instructions).
After building OCamlFormat, execute dune runtest to check for any regressions. There should be no unexpected diffs. If there are, promote all the diffs with dune promote.
Once the test suite passes, test your pull requests against code in external repositories by executing tools/test_branch.sh. If your pull request modifies an option, also run tools/test_branch.sh "<option>=<value>" to test with the option enabled.
The tools/test_branch.sh script compares two ocamlformat versions (the specified branch or HEAD if omitted, and its main merge base) on other project code and reports any formatting differences. Inspect any differences to make sure they are intentional. Differences in the formatted code with the option disabled should be summarised and explained in the pull request discussion.
OCamlformat's own code must be formatted with the development version and not with the latest release. This can be done with dune build @fmt.
By contributing to OCamlFormat, you accept that your contributions will fall under the LICENSE located in the root directory of this source tree.
To better manage issues and pull requests, we use the following labels:
- Good-first-issue: Suitable for newcomers to the project
- Kind/Bug: Represents a problem or solution to an erroneous/unintended behavior
- Kind/Docs: Pertains to changes in user or source code documentation
- Kind/Feature-request: Proposes a new feature
- Kind/Style-suggestion: Suggests a modification for the formatted output
- Kind/To-discuss: Invites discussion to converge on a solution
You're welcome to contribute to issues and pull requests marked as "Help wanted", or any other issues.