Add a contributing guide (#479)

Co-authored-by: Leandro Ostera <[email protected]>

Author: emillon

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

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 .

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