Merlin is a community oriented open-source project and we encourage and value any kind of contribution. Thanks for taking the time to contribute 🐫 !
Merlin adheres to the OCaml Code of Conduct as stated in the Code of Conduct document. By participating, you are expected to uphold this code. Please report unacceptable behavior either to local contacts (listed in here) or to someone listed in the upstream OCaml Code of Conduct.
Merlin (partial and fragmented) documentation can be found in the following places:
- Installation instructions and editor setup can be found in the README.md and the Github Pages
- Various topics related to editor support and configuration can be found in the wiki.
- The Merlin protocol is described in this document.
Contributions to the documentation are welcome!
We rely on Github's issue tracker 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 has not already been submitted.
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.
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.
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:
$ opam pin menhir 20201216The generated parser file should only be commited if there is an actual change in the grammar.
There is a partial overview over the repo organization with file-granularity at ARCHITECTURE.md. Here is a more high-level overview.
Vendored OCaml typer. Also include Merlin's incremental parser and other utilites. Changes to these modules should be kept minimal as these patches need to be reapplied for each new version of the compiler.
The backbone of merlin. Contains configuration utilities and pipeline management. The pipeline describes the compilation workflow: parsing, ppxing and typing.
The type description of Merlin's protocol as documented in PROTOCOL.md
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.
Contains most of Merlin logic required to answer the queries.
The configuration protocol that configuration servers such as
dot-merlin-reader or dune ocaml-merlin should implement.
The historical configuration server of Merlin. It reads .merlin configuration
files whose syntax is documented in the
wiki.
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
Merlin's behavioral test-suite. We rely on Dune's cram test framework.
The emacs editor mode.
The vim plugin.