You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: HACKING.md
+32-33Lines changed: 32 additions & 33 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,46 +2,46 @@
2
2
3
3
## Setup and Development
4
4
5
-
### Setting up the Project
5
+
### Setting Up the Project
6
6
7
-
Before starting to hack you need a properly configured development environment. Linux and macOS are supported and used daily by the core team. System dependencies include:
7
+
Before starting to hack, you need a properly configured development environment. Linux and macOS are supported and used daily by the core team. System dependencies include:
The project [`Dockerfile`](./Dockerfile) contains up-to-date system configuration instructions, as used to ship into production. It is written for the Alpine Linux distribution but is meant to be adapted to other environments such as Ubuntu, macOS+Homebrew or others. The GitHub workflow file [`.github/workflows/ci.yml`](.github/workflows/ci.yml) also contains useful commands for Ubuntu and macOS. Since ocaml.org is mostly written in OCaml, a properly configured OCaml development environment is also required, but is not detailed here. Although Docker is used to ship, it is not a requirement to begin hacking. Currently, ocaml.org doesn't yet compile using OCaml 5, version 4.14 of the language is used. It is possible to run workflow files in `.github/workflows` using the [nektos/act](https://github.com/nektos/act) tool. For instance, run the following command to run the CI checks run by GitHub on each pull request (where `ghghgh` is replace by an _ad-hoc_ GitHub token, see: https://github.com/nektos/act#github_token)
13
+
The project [`Dockerfile`](./Dockerfile) contains up-to-date system configuration instructions, as used to ship into production. It is written for the Alpine Linux distribution, but it is meant to be adapted to other environments such as Ubuntu, macOS+Homebrew, or others. The GitHub workflow file [`.github/workflows/ci.yml`](.github/workflows/ci.yml) also contains useful commands for Ubuntu and macOS. Since OCaml.org is mostly written in OCaml, a properly configured OCaml development environment is also required, but is not detailed here. Although Docker is used to ship, it is not a requirement to begin hacking. Currently, OCaml.org doesn't yet compile using OCaml 5; version 4.14 of the language is used. It is possible to run workflow files in `.github/workflows` using the [`nektos/act`](https://github.com/nektos/act) tool. For instance, the following command runs the CI checks through GitHub on each pull request (where `ghghgh` is replace by an _ad-hoc_ GitHub token, see: https://github.com/nektos/act#github_token)
Ensure you have `opam` installed. Opam will manage the OCaml compiler along with all of the OCaml packages needed to build and run the project. By this point we should all be using some Unix-like system (Linux, macOS, WSL2) so you should [run the opam install script](https://opam.ocaml.org/doc/Install.html#Binary-distribution). There are also manual instructions for people that don't want to run a script from the internet. We assume you are using `opam.2.1.0` or later which provides a cleaner, friendlier experience when installing system dependencies.
26
+
Ensure you have `opam` installed. Opam will manage the OCaml compiler along with all of the OCaml packages needed to build and run the project. By this point, we should all be using some Unix-like system (Linux, macOS, WSL2), so you should [run the opam install script](https://opam.OCaml.org/doc/Install.html#Binary-distribution). There are also manual instructions for people that don't want to run a script from the internet. We assume you are using `opam.2.1.0` or later, which provides a cleaner, friendlier experience when installing system dependencies.
27
27
28
-
With opam installed you can now initialise opam with `opam init`. Note in containers or WSL2 you will have to run `opam init --disable-sandboxing`. Opam might complain about some missing system dependencies like `unzip`, `cc` (a C compiler like `gcc`) etc. Make sure to install these before `opam init`.
28
+
With opam installed, you can now initialise opam with `opam init`. Note that in containers or WSL2, you will have to run `opam init --disable-sandboxing`. Opam might complain about some missing system dependencies like `unzip`, `cc` (a C compiler like `gcc`), etc. Make sure to install these before `opam init`.
29
29
30
-
Finally from the root of your project you can setup a [local opam switch](https://opam.ocaml.org/doc/Manual.html#Switches) and install the dependencies. There is a single `make` target to do just that.
30
+
Finally from the root of your project, you can setup a [local opam switch](https://opam.OCaml.org/doc/Manual.html#Switches) and install the dependencies. There is a single `make` target to do just that.
31
31
32
32
```
33
33
make switch
34
34
```
35
35
36
-
If you don't want a local opam switch and are happy to install everything globally (in the opam sense) then you can just install the dependencies directly.
36
+
If you don't want a local opam switch and are happy to install everything globally (in the opam sense), then you can just install the dependencies directly.
37
37
38
38
```
39
39
make deps
40
40
```
41
41
42
-
Opam will likely ask questions about installing system dependencies, for the project to work you will have to answer yes to installing these.
42
+
Opam will likely ask questions about installing system dependencies. Ror the project to work, you will have to answer yes to installing these.
43
43
44
-
### Running the server
44
+
### Running the Server
45
45
46
46
After building the project, you can run the server with:
47
47
@@ -57,7 +57,7 @@ make watch
57
57
58
58
This will restart the server on filesystem changes.
59
59
60
-
### Running tests
60
+
### Running Tests
61
61
62
62
You can run the unit test suite with:
63
63
@@ -67,46 +67,45 @@ make test
67
67
68
68
### Building the Playground
69
69
70
-
The OCaml Playground is compiled separately from the rest of the server and the generated assets can be found in
70
+
The OCaml Playground is compiled separately from the rest of the server. The generated assets can be found in
71
71
[`playground/asset/`](./playground/asset/).
72
72
73
-
You can build the playground from the root of the project, there is no need to move to the `./playground/` directory for the following commands.
73
+
You can build the playground from the root of the project. There is no need to move to the `./playground/` directory for the following commands.
74
74
75
75
To regenerate the playground, you need to install the playground's dependencies first:
76
76
77
77
```
78
78
make deps -C playground
79
79
```
80
80
81
-
After the dependencies have been installed, simply build the project to re-generate the JavaScript assets:
81
+
After the dependencies have been installed, simply build the project to regenerate the JavaScript assets:
82
82
83
83
```
84
84
make playground
85
85
```
86
86
87
-
Once the compilation is complete and successuful, the newly generated assets have to be git committed
88
-
in ocaml.org and merged as a pull request.
87
+
Once the compilation is complete and successuful, commit the newly-generated assets in OCaml.org's Git repo and merge the pull request.
89
88
90
89
### Deploying
91
90
92
91
Commits added on some branches are automatically deployed:
93
-
-`main` on <https://ocaml.org/>.
94
-
-`staging` on <https://staging.ocaml.org/>.
92
+
-`main` on <https://OCaml.org/>
93
+
-`staging` on <https://staging.OCaml.org/>
95
94
96
-
The deployment pipeline is managed in <https://github.com/ocurrent/ocurrent-deployer> which listens to the `main` and `staging` branches and builds the site using the `Dockerfile` at the root of the project. You can monitor the state of each deployment on [`deploy.ci.ocaml.org`](https://deploy.ci.ocaml.org/?repo=ocaml/ocaml.org)
95
+
The deployment pipeline is managed in <https://github.com/ocurrent/ocurrent-deployer>, which listens to the `main` and `staging` branches and builds the site using the `Dockerfile` at the project's root. You can monitor the state of each deployment on [`deploy.ci.OCaml.org`](https://deploy.ci.OCaml.org/?repo=ocaml/OCaml.org).
97
96
98
-
To test the deployment locally, you can run the following commands:
97
+
To test the deployment locally, run the following commands:
99
98
100
99
```
101
100
docker build -t ocamlorg .
102
101
docker run -p 8080:8080 ocamlorg
103
102
```
104
103
105
-
This will build the docker image and run a docker container with the port `8080` mapped to the HTTP server.
104
+
This will build the Docker image and run a Docker container with the port `8080` mapped to the HTTP server.
106
105
107
-
With the docker container running, you can visit the site at <http://localhost:8080/>.
106
+
With the Docker container running, visit the site at <http://localhost:8080/>.
108
107
109
-
The docker images automatically build from the `live` and `staging` branches, and are then pushed to Docker Hub: https://hub.docker.com/r/ocurrent/v3.ocaml.org-server
108
+
The Docker images automatically build from the `live` and `staging` branches. They are then pushed to Docker Hub: https://hub.docker.com/r/ocurrent/v3.OCaml.org-server.
110
109
111
110
### Staging Pull Requests
112
111
@@ -118,16 +117,16 @@ to do so. For example, documentation PRs or new features where we need testing
118
117
and feedback from the community will generally be live on `staging` for a while
119
118
before they get merged.
120
119
121
-
### Managing dependencies
120
+
### Managing Dependencies
122
121
123
-
ocaml.org is using an Opam switch which is local and bound to a pinned commit in opam-repository. This is intended to protect the build from upstream regressions. The Opam repository is specified in three (3) places:
122
+
OCaml.org is using an opam switch that is local and bound to a pinned commit in `opam-repository`. This is intended to protect the build from upstream regressions. The opam repository is specified in three (3) places:
124
123
```
125
124
Dockerfile
126
125
Makefile
127
126
.github/workflows/*.yml
128
127
```
129
128
130
-
When bringing up ocaml.org to a newer pin, the commit hash found it those files must be changed all at once.
129
+
When bringing up OCaml.org to a newer pin, the commit hash found it those files must be changed all at once.
131
130
132
131
Once the opam repo pin is updated, the local switch must be updated using the following command:
Copy file name to clipboardExpand all lines: data/changelog/merlin/2024-05-22-merlin-5.0.md
+6-6Lines changed: 6 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,18 +4,18 @@ tags: [merlin, platform]
4
4
changelog: |
5
5
+ merlin binary
6
6
- Support for OCaml 5.2 (#1757)
7
-
- destruct: Removal of residual patterns (#1737, fixes #1560)
7
+
- `destruct`: Removal of residual patterns (#1737, fixes #1560)
8
8
- Do not erase fields' names when destructing punned record fields (#1734,
9
9
fixes #1661)
10
10
- Ignore SIGPIPE in the Merlin server process (#1746)
11
11
- Fix lexing of quoted strings in comments (#1754, fixes #1753)
12
12
- Improve cursor position detection in longidents (#1756)
13
-
- Addition of a merlin-lib.commands library which disassociates the
14
-
execution of commands from the new_protocol, from the binary, allowing
13
+
- Addition of a `merlin-lib.commands` library that disassociates the
14
+
execution of commands from the `new_protocol`, from the binary, allowing
15
15
it to be invoked from other projects (#1758)
16
-
- New occurrences backend: Don't index occurrences when merlin.hide
16
+
- New occurrences backend: Don't index occurrences when `merlin.hide`
17
17
attribute is present. (#1768)
18
-
- Use the new uid_to_decl table in 5.2's cmt files to get documentation.
18
+
- Use the new `uid_to_decl` table in 5.2's CMT files to get documentation.
19
19
(#1773)
20
20
21
21
@@ -25,4 +25,4 @@ We are pleased to announce the release of Merlin 5.0-502!
25
25
26
26
This release brings official support for OCaml 5.2. Substantial backend changes were required to adapt to this release, especially for features such as occurrences and get-documentation. Do not hesitate to report any suspicious behavior in the [issue tracker](https://github.com/ocaml/merlin/issues)!
27
27
28
-
This release also fixes a handful of issues, two of them improving the behavior of Merlin's `destruct` feature.
28
+
This release also fixes a handful of issues, two of them improving the behaviour of Merlin's `destruct` feature.
0 commit comments