From 73a072acb1b39fa35334ce96a26c3e43e364c0cf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ulysse=20G=C3=A9rard?= Date: Thu, 18 Apr 2024 17:56:02 +0200 Subject: [PATCH 1/5] initial draft for the contributing document --- CONTRIBUTING.md | 120 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 120 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..4c8cfb31a --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,120 @@ +# Contributing to Merlin + +Merlin is a community oriented open-source project and we encourage and value +any kind of contribution. Thanks for taking the time to contribute 🐫 ! + +## Code of Conduct + +Merlin adheres to the OCaml Code of Conduct as stated in the [Code of Conduct +document](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this +code. Please report unacceptable behavior either to local contacts (listed in +[here](CODE_OF_CONDUCT.md)) or to someone listed in the upstream [OCaml Code of +Conduct](CODE_OF_CONDUCT.md). + +## Documentation + +Merlin (partial and fragmented) documentation can be found in the following +places: +- Installation instructions and editor setup can be found in the + [README.md](README.md) and the [Github Pages](https://ocaml.github.io/merlin/) +- Various topics related to editor support and configuration can be found in the + [wiki](https://github.com/ocaml/merlin/wiki). +- The Merlin protocol is described in [this + document](https://github.com/ocaml/merlin/blob/master/doc/dev/PROTOCOL.md). + +Contribution to the documentation are welcome! + +## Question, bug reports and feature requests + +We rely on [Github's issue tracker](https://github.com/ocaml/merlin/issues) for +support questions, feature requests and bug reports. + +When reporting an issue, please include a precise reproduction in the bug report +when that's possible, as it is a very useful tool to investigate. You should +also check that you are using the latest version of Merlin and that a similar +issue as not already been submitted. + +## Code contributions + + ### Legal Notice + When contributing to Merlin, you must agree that you have authored 100% of the + content, that you have the necessary rights to the content and that the content + you contribute may be provided under the [project's MIT + license](https://github.com/ocaml/merlin/blob/master/LICENSE). + + +### Styleguides + +As of today, Merlin's codebase does not use a code formatter. When contributing +code to an existing module, one should adopt the style of the surrounding code. +Please keep lines under 80 characters. + +We plan to move the codebase to ocamlformat in a near future. + +Changes unrelated to the issue addressed by a PR should be made in a separate +PR. Additionally, formatting changes in parts of the code not concerned by a +specific PR should be proposed in another PR. + +### Menhir version + +Merlin promotes the generated Menhir parser in its sources. This is done to +avoid depending on Menhir when installing Merlin. However this also means that +unnecessary diff will appear when the parser gets re-generated by a different +version of Menhir. To remove this diff please use version `20201216`: +```bash +$ opam pin menhir 20201216 +``` +The generated parser file should only be commited if there is an actual change +in the grammar. + +### Repository organization + + +#### `/src/ocaml` +Vendored OCaml typer. Also include Merlin's incremental parser and other +utilites. + +#### `/src/kernel` +The backbone of merlin. Contains configuration utilities and pipeline +management. The pipeline describe the compilation workflow: parsing, ppxing and +typing. + +#### `/src/frontend/query_protocol.ml` +The type description of Merlin's protocol as documented in +[PROTOCOL.md](https://github.com/ocaml/merlin/blob/master/doc/dev/PROTOCOL.md) + +#### `/src/frontend/query_commands.ml` +This file contains the dispatcher: a large pattern matching that answers +Merlin's queries. Most of the time answering a query begins with getting the +Typedtree from the pipeline and calling the correct analysis functions. + +#### `/src/analysis` +Contains most of Merlin logic required to answer the queries. + +#### `/src/dot-protocol` +The configuration protocol that configuration servers such as +`dot-merlin-reader` or `dune ocaml-merlin` should implement. + +#### `/src/dot-merlin-reader` +The historical documentation server of Merlin. Tt reads `.merlin` configuration +files whose syntax is [documented in the +wiki](https://github.com/ocaml/merlin/wiki/Project-configuration). + +#### `/src/frontend/ocamlmerlin` +The standard Merlin frontend, composed of a long-running server and a client. +This is the frontend used by the test-suite and standard emacs and vim plugins. +For an alternative frontend, see +[ocaml-lsp-server](https://github.com/ocaml/ocaml-lsp/) + +#### `/tests/test-dirs` +Merlin's behavioral test-suite. We rely on Dune's cram test framework. Ideally, +any opened issue should be accompanied by a test with a reproduction. When +working on a fix for an issue, please have a first commit with the test showing +the issue, before commits that fix the issue and update the test result +accordingly. + +#### `/emacs` +The emacs editor mode. + +#### `/vim` +The vim plugin. From 87940463390988ee02f93897aec7ca9d1d95b07f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ulysse=20G=C3=A9rard?= Date: Tue, 23 Apr 2024 16:37:44 +0200 Subject: [PATCH 2/5] wip: remove "legal" notice Unclear usefulness / rightfulness, requires more discussions --- CONTRIBUTING.md | 7 ------- 1 file changed, 7 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4c8cfb31a..f555ad7d5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -36,13 +36,6 @@ issue as not already been submitted. ## Code contributions - ### Legal Notice - When contributing to Merlin, you must agree that you have authored 100% of the - content, that you have the necessary rights to the content and that the content - you contribute may be provided under the [project's MIT - license](https://github.com/ocaml/merlin/blob/master/LICENSE). - - ### Styleguides As of today, Merlin's codebase does not use a code formatter. When contributing From f82fd9fc0a58d3975f72b0105dbbc6bf6bc0500e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ulysse=20G=C3=A9rard?= Date: Thu, 16 May 2024 15:37:13 +0200 Subject: [PATCH 3/5] Implement suggested changes Co-authored-by: Rafal Gwozdzinski Co-authored-by: Sonja Heinze --- CONTRIBUTING.md | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f555ad7d5..ef316f8c9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -22,7 +22,7 @@ places: - The Merlin protocol is described in [this document](https://github.com/ocaml/merlin/blob/master/doc/dev/PROTOCOL.md). -Contribution to the documentation are welcome! +Contributions to the documentation are welcome! ## Question, bug reports and feature requests @@ -32,7 +32,7 @@ support questions, feature requests and bug reports. When reporting an issue, please include a precise reproduction in the bug report when that's possible, as it is a very useful tool to investigate. You should also check that you are using the latest version of Merlin and that a similar -issue as not already been submitted. +issue has not already been submitted. ## Code contributions @@ -48,6 +48,11 @@ Changes unrelated to the issue addressed by a PR should be made in a separate PR. Additionally, formatting changes in parts of the code not concerned by a specific PR should be proposed in another PR. +Ideally, any opened issue should be accompanied by a test with a reproduction. +When working on a fix for an issue, the first commit should contain the test +showing the issue. Following commits should fix the issue and update the test +result accordingly. + ### Menhir version Merlin promotes the generated Menhir parser in its sources. This is done to @@ -65,7 +70,8 @@ in the grammar. #### `/src/ocaml` Vendored OCaml typer. Also include Merlin's incremental parser and other -utilites. +utilites. Changes to these modules should be kept minimal as these patches need +to be reapplied for each new version of the compiler. #### `/src/kernel` The backbone of merlin. Contains configuration utilities and pipeline @@ -89,7 +95,7 @@ The configuration protocol that configuration servers such as `dot-merlin-reader` or `dune ocaml-merlin` should implement. #### `/src/dot-merlin-reader` -The historical documentation server of Merlin. Tt reads `.merlin` configuration +The historical configuration server of Merlin. It reads `.merlin` configuration files whose syntax is [documented in the wiki](https://github.com/ocaml/merlin/wiki/Project-configuration). @@ -100,11 +106,7 @@ For an alternative frontend, see [ocaml-lsp-server](https://github.com/ocaml/ocaml-lsp/) #### `/tests/test-dirs` -Merlin's behavioral test-suite. We rely on Dune's cram test framework. Ideally, -any opened issue should be accompanied by a test with a reproduction. When -working on a fix for an issue, please have a first commit with the test showing -the issue, before commits that fix the issue and update the test result -accordingly. +Merlin's behavioral test-suite. We rely on Dune's cram test framework. #### `/emacs` The emacs editor mode. From 5ba620f6e6a85b0828a36988db8f0e3cf72fdeca Mon Sep 17 00:00:00 2001 From: Ulysse <5031221+voodoos@users.noreply.github.com> Date: Thu, 16 May 2024 15:38:08 +0200 Subject: [PATCH 4/5] Add repo organisation introduction Co-authored-by: Sonja Heinze --- CONTRIBUTING.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ef316f8c9..2bf7cf85c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -67,6 +67,9 @@ in the grammar. ### Repository organization +There is a partial overview over the repo organization with file-granularity at +[ARCHITECTURE.md](https://github.com/ocaml/merlin/blob/master/doc/dev/ARCHITECTURE.md). +Here is a more high-level overview. #### `/src/ocaml` Vendored OCaml typer. Also include Merlin's incremental parser and other From 81947a9cb0f5b0b0dd5926cac815bc263c9c4cfc Mon Sep 17 00:00:00 2001 From: Ulysse <5031221+voodoos@users.noreply.github.com> Date: Thu, 16 May 2024 15:38:18 +0200 Subject: [PATCH 5/5] Fix typo Co-authored-by: Sonja Heinze --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2bf7cf85c..339c19b73 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -78,7 +78,7 @@ to be reapplied for each new version of the compiler. #### `/src/kernel` The backbone of merlin. Contains configuration utilities and pipeline -management. The pipeline describe the compilation workflow: parsing, ppxing and +management. The pipeline describes the compilation workflow: parsing, ppxing and typing. #### `/src/frontend/query_protocol.ml`