Improve repository for newcomers (ocaml-ppx#2380)

* Add a Roadmap
* Add authors and maintainers information
* Improve Contributing Guide and README
* Convert Hacking guide to Markdown
* Rename LICENSE
* Update Changelog tags
* Add description of the project in opam file
* Remove outdated bash completion for test_branch

Co-authored-by: Guillaume Petiot <[email protected]>
Co-authored-by: Jules Aguillon <[email protected]>

Author: 3 people

CHANGES.md

@@ -1,71 +1,55 @@
-# Contributing to OCamlFormat
+# OCamlFormat Contribution Guide
 
-## Reporting Issues
+Welcome and thank you for your interest in contributing to OCamlFormat. This contribution guide will help you through the contribution process.
 
-If you encounter a problem when using OCamlFormat or if you have any questions, please open a [GitHub issue](https://github.com/ocaml-ppx/ocamlformat/issues/).
+## Reporting Issues
 
-1. Check first if your issue has already been [reported](https://github.com/ocaml-ppx/ocamlformat/issues/).
-2. Include the version of OCamlFormat you are using (`ocamlformat --version`).
-3. Include a (preferably short) source file which demonstrates the issue.
-4. Describe the expected and actual behavior.
-5. Do not unsubscribe from the issue until it is closed, the maintainers may ask for your feedback.
+If you encounter an issue with OCamlFormat, or if you have inquiries, we encourage you to open a [GitHub issue](https://github.com/ocaml-ppx/ocamlformat/issues/). Please follow the steps below:
 
-When acknowledged, the project maintainers will add [labels](#ocamlformat-labels) to your issue throughout its lifespan.
+1. First, verify if your issue hasn't already been [reported](https://github.com/ocaml-ppx/ocamlformat/issues/).
+2. Specify the OCamlFormat version you're using (`ocamlformat --version`).
+3. Include a (preferably short) source file that replicates the issue.
+4. Clearly define the expected and actual behavior.
+5. Remain engaged with the issue until closure as your feedback might be needed.
 
 ## Pull Requests
 
-We actively welcome pull requests.
+We heartily welcome pull requests. To ensure an effective contribution, please adhere to the steps below:
 
-1. Prior to investing a large amount of time into significant or invasive changes, or those that affect the output, it is likely more efficient to first open an issue for discussion and planning.
-2. If you are not familiar with the project, focus first on the [Good first issues](https://github.com/ocaml-ppx/ocamlformat/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3A%22Good-first-issue+%3A%2B1%3A%22).
+1. For significant, invasive, or output-affecting changes, consider opening an issue for discussion before committing substantial time and effort.
+2. If you're new to the project, starting with the [Good first issues](https://github.com/ocaml-ppx/ocamlformat/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3A%22Good-first-issue+%3Agreen_heart%3A%22) can be beneficial.
 3. Fork the repository and create your branch from `main`.
-4. If you have added code that should be tested, add tests (they should be located in the `tests/passing` directory).
-'.
-5. Ensure the test suite passes (see [Running the tests](#running-the-tests)).
-
-When acknowledged, the project maintainers will add [labels](#ocamlformat-labels) to your pull request throughout its lifespan.
-
+4. If you've added code that should be tested, supplement it with tests located in the `test/` directory.
+5. Ensure that the test suite passes (see [Running the tests](#running-the-tests) for instructions).
 
-### Running the tests
+### Running the Tests
 
-Once OCamlFormat has been built, run `make test` to check for regressions.
+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`.
 
-The first step of `make test` is to ensure that invoking OCamlFormat on its own source code produces the same source code (you can run `make fixpoint` to only check this). If OCamlFormat is not integrated with the editor you use, you should run `make fmt` to reformat all OCamlFormat source files.
+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 second part of `make test` is to ensure the test suite passes. You should not see any unexpected diff. One can accept all diffs at once with `make regtests-promote`.
+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.
 
-Once `make test` passes, pull requests should be tested on the code in a set of external repositories. This can be done by executing `tools/test_branch.sh <rev>` where `<rev>` is the git revision/branch containing the pull request's changes. If a pull request affects an option, `OCAMLFORMAT=<option>=<value> tools/test_branch.sh <rev>` should also be run to test with the option enabled.
+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`.
 
-The `tools/test_branch.sh` script runs two versions of `ocamlformat` (the specified branch, or `HEAD` if omitted, and its merge base with main) on the test code and reports the differences in the formatted code. Formatting failures may also be reported on the terminal, these will need to be fixed before a pull request can be merged. The differences should be inspected to ensure they are as intended. Pull requests changing the format of code should generally introduce an option to enable the alternate style (if in doubt, open an issue for discussion). Any differences in the formatted code with the option disabled should be summarized and explained in the pull request discussion.
+## Licensing
 
-To benefit from the autocompletion of git branch names in the `tools/test_branch.sh` script, if you use the `bash` shell, add the following line to your `~/.bashrc` file:
-```
-source <path-to-ocamlformat>/tools/ocamlformat_test_branch
-```
-
-If you use the `zsh` shell, add the following lines to your `~/.zshrc` file:
-```
-autoload bashcompinit
-bashcompinit
-source <path-to-ocamlformat>/tools/ocamlformat_test_branch
-```
-
-## License
-
-By contributing to OCamlFormat, you agree that your contributions will be licensed under the LICENSE file in the root directory of this source tree.
+By contributing to OCamlFormat, you accept that your contributions will fall under the LICENSE located in the root directory of this source tree.
 
 ## OCamlFormat Labels
 
-### Issue specific
+To better manage issues and pull requests, we use the following labels:
+
+### Issue-Specific Labels
 
-- [Good-first-issue](https://github.com/ocaml-ppx/ocamlformat/labels/Good-first-issue%20%3A%2B1%3A): This issue is a good entry point in the project for new contributors
+- [Good-first-issue](https://github.com/ocaml-ppx/ocamlformat/labels/Good-first-issue%20%3A%2B1%3A): Suitable for newcomers to the project
 
-### Kind
+### Kind Labels
 
-- [Kind/Bug](https://github.com/ocaml-ppx/ocamlformat/labels/Kind%2FBug%20%3Ax%3A): This issue describes a problem or this contribution addresses a problem (erroneous/unintended behavior)
-- [Kind/Docs](https://github.com/ocaml-ppx/ocamlformat/labels/Kind%2FDocs): This is related to a documentation change (user documentation or source code documentation)
-- [Kind/Feature-request](https://github.com/ocaml-ppx/ocamlformat/labels/Kind%2FFeature-request): This issue or contribution proposes a new feature
-- [Kind/Style-suggestion](https://github.com/ocaml-ppx/ocamlformat/labels/Kind%2FStyle%20suggestion): This issue or contribution proposes a style modification for the formatted output
-- [Kind/To-discuss](https://github.com/ocaml-ppx/ocamlformat/labels/Kind%2FTo-discuss): Discussion needed to converge to a solution
+- [Kind/Bug](https://github.com/ocaml-ppx/ocamlformat/labels/Kind%2FBug%20%3Ax%3A): Represents a problem or solution to an erroneous/unintended behavior
+- [Kind/Docs](https://github.com/ocaml-ppx/ocamlformat/labels/Kind%2Fdocs): Pertains to changes in user or source code documentation
+- [Kind/Feature-request](https://github.com/ocaml-ppx/ocamlformat/labels/Kind%2Ffeature-request): Proposes a new feature
+- [Kind/Style-suggestion](https://github.com/ocaml-ppx/ocamlformat/labels/Kind%2Fstyle-suggestion): Suggests a modification for the formatted output
+- [Kind/To-discuss](https://github.com/ocaml-ppx/ocamlformat/labels/Kind%2Fto-discuss): Invites discussion to converge on a solution
 
-Feel free to contribute on the [Help wanted](https://github.com/ocaml-ppx/ocamlformat/labels/Help%20wanted%20%3Afire%3A) issues and pull requests.
+You're welcome to contribute to issues and pull requests marked as ["Help wanted"](https://github.com/ocaml-ppx/ocamlformat/labels/Help-wanted%20%3Awarning%3A), or any other issues.

CONTRIBUTING.md

@@ -0,0 +1,64 @@
+# Contributing to OCamlFormat
+
+## Testing on other projects
+
+The `tools/test_branch.sh` script facilitates testing by building two versions of OCamlFormat and running them on the sources of specific projects. The list of tested projects can be found and modified in `test-extra/Makefile`.
+
+These project sources are cloned into the `test-extra/code` directory. We use Git to manage the state of the script:
+
+- Staged changes indicate the diffs introduced by formatting with the first revision.
+- Unstaged changes represent the diffs introduced by upgrading OCamlFormat to the second revision.
+
+## Release procedure
+
+Follow these steps for the release procedure:
+
+1. Ensure the release milestone is achieved.
+2. Review the impact of the release on real source code: In `test-extra/Makefile`, uncomment the extended list of projects to test and run `tools/test_branch.sh -a "previous_release"`. Any diffs should be discussed with the maintainers of these projects to gather feedback before continuing the release.
+3. If a supported OCaml version lacks CI support, run the test suite locally.
+4. In `CHANGES.md`, replace `unreleased` with the current version (`a.b.c`) and date. In `README.md`, `doc/faq.mld`, and `doc/getting_started.mld`, update the recommended version to use in `.ocamlformat` files. Commit these changes.
+5. Tag using `dune-release tag`.
+6. Verify that the release binary has a release version number with: `dune build @install && dune install --prefix _install && ./_install/bin/ocamlformat --version && rm -rf _install`. It should output just `a.b.c`.
+7. Lint using `dune-release lint`.
+8. Amend the release commit if necessary and update the tag using `dune-release tag --force`.
+9. Push the changes with `git push --tags`.
+10. Release in automatic mode using `dune-release -p ocamlformat-lib,ocamlformat,ocamlformat-rpc-lib`.
+11. Close the release milestone.
+12. Each release should be announced on <https://discuss.ocaml.org/>.
+13. Create a Windows asset:
+    - Go to <https://github.com/ocaml-ppx/ocamlformat/actions/workflows/build-mingw64.yml>.
+    - Run the workflow on the `main` branch.
+    - Once the build is successful, go to the workflow result page.
+    - Download the `ocamlformat-main.exe` artifact.
+    - Rename it to `ocamlformat-a.b.c.exe`.
+    - Go to <https://github.com/ocaml-ppx/ocamlformat/releases/edit/a.b.c>.
+    - Add the binary.
+    - Click "Update release".
+
+## Backporting changes to a point release
+
+Sometimes, it's helpful to create a point release, but the main branch contains changes that would be unsuitable for a point release.
+
+Consider a situation where the last release is 0.3.5, and since then, the main branch contains new features F1, F2 and a bugfix B. Instead of reverting F1 and F2 in the main branch, you can create a release branch for the 0.3 releases.
+
+Please follow the detailed guide in the original document on how to prepare a release branch, create a release, and merge the release branch.
+
+## Building on Windows
+
+`ocamlformat` can be built as a native Windows binary using the `mingw64` toolchain under Cygwin. The required Cygwin packages are:
+
+- `git`, `curl`, `unzip`
+- `m4`, `patchutils`, `make`
+- `mingw64-x86_64-binutils`, `mingw64-x86_64-gcc-core`, `mingw64-x86_64-headers`, `mingw64-x86_64-runtime`
+
+To build the binary, execute `bash tools/build-mingw64.sh` from the root of the repository. The first time this script is run, it will install `opam` in the subdirectory `_build-mingw64` and use it to install all the dependencies of `ocamlformat`, after which it will build the binary. Subsequent runs will only rebuild `ocamlformat`. If you need to start from scratch, simply remove the `_build-mingw64` directory.
+
+This script can also be triggered as a GitHub Action named `build-mingw64`, which will build the binary in a GitHub worker and upload it back to GitHub. To retrieve it, select the Action run in question and scroll down to "Artifacts".
+
+## Building the documentation
+
+To build the documentation, run the following command:
+
+```
+dune build @doc && xdg-open _build/default/_doc/_html/ocamlformat/index.html
+```