Skip to content

Commit

Permalink
Text editing (#2579)
Browse files Browse the repository at this point in the history 
* line editing and formatting in adherence with style guide

* line editing & formatting

* mostly formatting

* formatting to adhere to style guide

* line editing & formatting to adhere to style guide

* line editing & formatting to adhere to style guide

* minor formatting change

* titles are not markdown

* Make title look the same as previous

---------

Co-authored-by: Christine Rose <[email protected]>
Co-authored-by: Cuihtlauac ALVARADO <[email protected]>
  • Loading branch information
@cuihtlauac @christinerose
3 people authored Jul 5, 2024
1 parent 734c2d8 commit 36b406b
Show file tree
Hide file tree
Showing 7 changed files with 154 additions and 155 deletions.
65 changes: 32 additions & 33 deletions HACKING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,46 +2,46 @@

## Setup and Development

### Setting up the Project
### Setting Up the Project

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:
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:
* Libev: http://software.schmorp.de/pkg/libev.html
* Oniguruma: https://github.com/kkos/oniguruma
* OpenSSL: https://www.openssl.org/
* GNU Multiple Precision: https://gmplib.org/

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)
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)
```
act -s GITHUB_TOKEN=ghghgh .github/workflows/ci.yml -j build
```


The `Makefile` contains many commands that can get you up and running, a typical workflow will be to clone the repository after forking it.
The Makefile contains many commands that can get you up and running. A typical workflow is to clone the repository after forking it.

```
git clone https://github.com/<username>/ocaml.org.git
cd ocaml.org
git clone https://github.com/<username>/OCaml.org.git
cd OCaml.org
```

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.
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.

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`.
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`.

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.
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.

```
make switch
```

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.
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.

```
make deps
```

Opam will likely ask questions about installing system dependencies, for the project to work you will have to answer yes to installing these.
Opam will likely ask questions about installing system dependencies. Ror the project to work, you will have to answer yes to installing these.

### Running the server
### Running the Server

After building the project, you can run the server with:

Expand All @@ -57,7 +57,7 @@ make watch

This will restart the server on filesystem changes.

### Running tests
### Running Tests

You can run the unit test suite with:

Expand All @@ -67,46 +67,45 @@ make test

### Building the Playground

The OCaml Playground is compiled separately from the rest of the server and the generated assets can be found in
The OCaml Playground is compiled separately from the rest of the server. The generated assets can be found in
[`playground/asset/`](./playground/asset/).

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.
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.

To regenerate the playground, you need to install the playground's dependencies first:

```
make deps -C playground
```

After the dependencies have been installed, simply build the project to re-generate the JavaScript assets:
After the dependencies have been installed, simply build the project to regenerate the JavaScript assets:

```
make playground
```

Once the compilation is complete and successuful, the newly generated assets have to be git committed
in ocaml.org and merged as a pull request.
Once the compilation is complete and successuful, commit the newly-generated assets in OCaml.org's Git repo and merge the pull request.

### Deploying

Commits added on some branches are automatically deployed:
- `main` on <https://ocaml.org/>.
- `staging` on <https://staging.ocaml.org/>.
- `main` on <https://OCaml.org/>
- `staging` on <https://staging.OCaml.org/>

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)
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).

To test the deployment locally, you can run the following commands:
To test the deployment locally, run the following commands:

```
docker build -t ocamlorg .
docker run -p 8080:8080 ocamlorg
```

This will build the docker image and run a docker container with the port `8080` mapped to the HTTP server.
This will build the Docker image and run a Docker container with the port `8080` mapped to the HTTP server.

With the docker container running, you can visit the site at <http://localhost:8080/>.
With the Docker container running, visit the site at <http://localhost:8080/>.

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
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.

### Staging Pull Requests

Expand All @@ -118,16 +117,16 @@ to do so. For example, documentation PRs or new features where we need testing
and feedback from the community will generally be live on `staging` for a while
before they get merged.

### Managing dependencies
### Managing Dependencies

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:
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:
```
Dockerfile
Makefile
.github/workflows/*.yml
```

When bringing up ocaml.org to a newer pin, the commit hash found it those files must be changed all at once.
When bringing up OCaml.org to a newer pin, the commit hash found it those files must be changed all at once.

Once the opam repo pin is updated, the local switch must be updated using the following command:
```sh
Expand All @@ -136,22 +135,22 @@ opam repo set-url pin git+https://github.com/ocaml/opam-repository#<commit-hash>

Where `<commit-hash>` is the pinned hash specified in the files mentioned above.

Once this is done, you can do `opam update` and `opam upgrade`. If ocamlformat
Once this is done, you can run `opam update` and `opam upgrade`. If OCamlFormat
was upgraded in the process, the files `.ocamlformat` and
`.github/workflows/ci.yml` must be modified with the currently installed version
of ocamlformat.
of OCamlFormat.

## Repository structure
## Repository Structure

The following snippet describes the repository structure.
The following snippet describes the repository structure:

```text
.
├── asset/
| The static assets served by the site.
│
├── data/
| Data used by ocaml.org in Yaml and Markdown format.
| Data used by OCaml.org in Yaml and Markdown format.
│
├── playground/
│ The source and generated assets for the OCaml Playground
Expand Down
12 changes: 6 additions & 6 deletions data/changelog/merlin/2024-05-22-merlin-5.0.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,18 +4,18 @@ tags: [merlin, platform]
changelog: |
+ merlin binary
- Support for OCaml 5.2 (#1757)
- destruct: Removal of residual patterns (#1737, fixes #1560)
- `destruct`: Removal of residual patterns (#1737, fixes #1560)
- Do not erase fields' names when destructing punned record fields (#1734,
fixes #1661)
- Ignore SIGPIPE in the Merlin server process (#1746)
- Fix lexing of quoted strings in comments (#1754, fixes #1753)
- Improve cursor position detection in longidents (#1756)
- Addition of a merlin-lib.commands library which disassociates the
execution of commands from the new_protocol, from the binary, allowing
- Addition of a `merlin-lib.commands` library that disassociates the
execution of commands from the `new_protocol`, from the binary, allowing
it to be invoked from other projects (#1758)
- New occurrences backend: Don't index occurrences when merlin.hide
- New occurrences backend: Don't index occurrences when `merlin.hide`
attribute is present. (#1768)
- Use the new uid_to_decl table in 5.2's cmt files to get documentation.
- Use the new `uid_to_decl` table in 5.2's CMT files to get documentation.
(#1773)
Expand All @@ -25,4 +25,4 @@ We are pleased to announce the release of Merlin 5.0-502!

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)!

This release also fixes a handful of issues, two of them improving the behavior of Merlin's `destruct` feature.
This release also fixes a handful of issues, two of them improving the behaviour of Merlin's `destruct` feature.
2 changes: 1 addition & 1 deletion data/changelog/odoc/2024-04-30-odoc-2.4.2.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,4 +9,4 @@ changelog: |
- Fix issues #1066 and #1095 with extended opens (@jonludlam, #1082, #1100)
---

We've released Odoc 2.4.2 with compatibility with OCaml 5.2 and a few bug fixes.
We've released `odoc` 2.4.2 with OCaml 5.2 compatibility and a few bug fixes.
18 changes: 9 additions & 9 deletions data/changelog/opam/2021-02-08-opam-2-1-0-beta4.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,8 +13,8 @@ changelog: |
* Set OPAMCLI=2.0 during package action commands [#4492 @kit-ty-kate]
* Fix sandbox check on first `opam init` [#4370 @rjbou - fix #4368]
* Print shell-appropriate eval command on `opam init` [#4427 @freevoid]
* Fix init script check in csh [#4482 @gahr]
* The stdout of `pre-` and `post-session` hooks is now propagated to the user [#4382 @AltGr - fix #4359]
* Fix `init` script check in csh [#4482 @gahr]
* The `stdout` of `pre-` and `post-session` hooks is now propagated to the user [#4382 @AltGr - fix #4359]
* `post-install` hooks are now allowed to modify or remove installed files [#4388 @lefessan]
* Add support for switch-specific pre/post sessions hooks [#4476 @rjbou - fix #4472]
* Ensure we don't advertise upgrades to hidden versions [#4477 @AltGr - fix #4432]
Expand All @@ -23,7 +23,7 @@ changelog: |
* Fix `--update-invariant` when removing or changing package name [#4360 @AltGr - fix #4353]
* Fix updates of the invariant with `--update-invariant` [#4431 @AltGr]
* Fix cleanup of build dirs for version pinned packages [#4436 @rjbou - fix #4255]
* Fix opamfile format upgrade on pinning [#4366 @rjbou - fix #4365]
* Fix `opamfile` format upgrade on pinning [#4366 @rjbou - fix #4365]
* Fix `pin --show` actually pinning [#4367 @rjbou - fix #4348]
* When several pins are needed, do their fetching in parallel [#4399 @rjbou - fix #4315]
* Don't cleanup VCS pin source directories [#4399 @rjbou]
Expand All @@ -34,25 +34,25 @@ changelog: |
* Skip loading the switch state for variable lookup when possible [#4428 @rjbou]
* Fix package variables display when no config file is found [#4428 @rjbou]
* Fix `opam option depext-bypass-=["XXX"]` [#4428 @rjbou]
* Lint: add a check that strings in filtered package formula are booleans or variables [#443 @rjbou - fix #4439]
* Lint: add a check that strings in filtered package formula are Booleans or variables [#443 @rjbou - fix #4439]
* Fix handling of filename-encoded pkgname in opam files [#4401 @AltGr - fix ocaml-opam/opam-publish#107]
* Don't recompile when modifying the package flags [#4477 @AltGr]
* Add depext support for NetBSD and DragonFlyBSD [#4396 @kit-ty-kate]
* Fix depexts on OpenBSD, FreeBSD and Gentoo: Allow short names and full name paths for ports-based systems [#4396 @kit-ty-kate]
* Fix depexts on OpenBSD, FreeBSD, and Gentoo: Allow short names and full name paths for ports-based systems [#4396 @kit-ty-kate]
* Handle the case where `os-family=ubuntu` as `os-family=debian` [#4441 @alan-j-hu]
* Update opam's opam files to 2.0 [#4371 @AltGr]
* Update opam's `opam` files to 2.0 [#4371 @AltGr]
* Makefile: Add rule `custom-libinstall` for `opam-custom-install` use [#4401 @AltGr]
* Use the archive caches when running `opam admin cache` [#4384 @AltGr - fix #4352]
* Fix explosion of `opam admin check --cycles` on repositories with huge cliques [#4392 @AltGr]
* Much improved format-preserving printer [#4298 #4302 @rjbou - fix #3993]
* Fix missing conflict message when trying to remove required packages [#4362 @AltGr]
* Fix the Z3 backend for upgrades [#4393 @AltGr]
* Fix cases where opam would wrongly complain about action cycles [#4358 @AltGr - fix #4357]
* Fix permission denied fallback for openssl [#4449 @Blaisorblade - fix #4448]
* Add debug & verbose log for patch & subst applications [#4464 @rjbou - fix #4453]
* Fix permission denied fallback for `openssl` [#4449 @Blaisorblade - fix #4448]
* Add debug & verbose log for patch & `subst` applications [#4464 @rjbou - fix #4453]
* Be more robust w.r.t. new caches updates when `--read-only` is not used [#4467 @AltGr - fix #4354]
* Improved and extended tests [#4375 #4395 #4428 #4385 #4467 #4475 #4483 @emillon @rjbou @AltGr @freevoid @dra27]
* Switched to Github actions [#4463 @rjbou]
* Switched to GitHub actions [#4463 @rjbou]
---

_Feedback on this post is welcomed on [Discuss](https://discuss.ocaml.org/t/ann-opam-2-1-0-beta4/7252)!_
Expand Down
Loading

0 comments on commit 36b406b

Please sign in to comment.