From 232a8ffab32a83882c9b9119b1f9a61f56a39c71 Mon Sep 17 00:00:00 2001
From: Etienne Millon <me@emillon.org>
Date: Tue, 6 Feb 2024 11:28:51 +0100
Subject: [PATCH] Add a contributing guide (#479)

Co-authored-by: Leandro Ostera <leandro@abstractmachines.dev>
---
 CONTRIBUTING.md    | 35 +++++++++++++++++++++++++++++++++++
 Makefile           | 19 ++++++++++++++++++-
 dune-workspace.dev | 13 ++++++-------
 3 files changed, 59 insertions(+), 8 deletions(-)
 create mode 100644 CONTRIBUTING.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..8b4b41c
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,35 @@
+# Contributing
+
+Thanks for contributing to UTop!
+
+## Setting up local switches
+
+UTop comes from a `dune-workspace.dev` file to test it across all supported
+versions.
+
+Run `make create-switches` to create all the required switches.
+
+Now you can run `dune` with the `--workspace dev-workspace.dev` flag to run
+the same command across all the workspaces. The `make
+all-supported-ocaml-versions` command will build the project with this setup.
+
+## Compatibility Across Versions
+
+Some code will be different from one version of OCaml to the next. If you find
+some that does, please abstract it away using the `UTop_compat` module.
+
+For example, the `Load_path.get_paths ()` function has changed recently to
+return a record with shape `{ visible: string list; hidden: string list }`, but
+this function used to return a single `string list`.
+
+Defining this function using pre-processor macros allows us to give the same
+function two different bodies on different version of the language.
+
+```ocaml
+let get_load_path () =
+#if OCAML_VERSION >= (5, 2, 0)
+  Load_path.((get_paths ()).visible)
+#else
+  Load_path.get_paths ()
+#endif
+```
diff --git a/Makefile b/Makefile
index e2e7cc7..e4b2a80 100644
--- a/Makefile
+++ b/Makefile
@@ -17,7 +17,6 @@ reinstall:
 	$(MAKE) uninstall
 	$(MAKE) install
 
-
 .PHONY: examples
 examples:
 	dune build @examples
@@ -39,3 +38,21 @@ cinaps:
 clean:
 	rm -rf _build *.install
 	find . -name .merlin -delete
+
+.PHONY: create-switches
+create-switches:
+	opam switch create utop-412 4.12.0
+	opam switch create utop-413 4.13.1
+	opam switch create utop-414 4.14.1
+	opam switch create utop-500 5.0.0
+	opam switch create utop-510 5.1.0
+	opam switch create utop-520 5.2.0+trunk
+
+.PHONY: install-switches
+install-switches:
+	opam install --switch utop-412 --deps-only --with-test -y .
+	opam install --switch utop-413 --deps-only --with-test -y .
+	opam install --switch utop-414 --deps-only --with-test -y .
+	opam install --switch utop-500 --deps-only --with-test -y .
+	opam install --switch utop-510 --deps-only --with-test -y .
+	opam install --switch utop-520 --deps-only --with-test -y .
diff --git a/dune-workspace.dev b/dune-workspace.dev
index 59b0386..19ad9d9 100644
--- a/dune-workspace.dev
+++ b/dune-workspace.dev
@@ -1,8 +1,7 @@
 (lang dune 1.0)
-;; This file is used by `make all-supported-ocaml-versions`
-(context (opam (switch 4.02.3)))
-(context (opam (switch 4.03.0)))
-(context (opam (switch 4.04.2)))
-(context (opam (switch 4.05.0)))
-(context (opam (switch 4.06.1)))
-(context (opam (switch 4.07.0)))
+(context (opam (switch utop-411)))
+(context (opam (switch utop-412)))
+(context (opam (switch utop-413)))
+(context (opam (switch utop-414)))
+(context (opam (switch utop-500)))
+(context (opam (switch utop-510)))