anil.recoil.org
My aggregated monorepo of OCaml code, automaintained
1# Monorepo Development Guide
2
3This is a monorepo managed by `monopam`. Each subdirectory is a git subtree
4from a separate upstream repository.
5
6## Making Changes
7
81. Edit code in any subdirectory as normal
92. Build and test: `opam exec -- dune build` and `opam exec -- dune test`
103. Commit your changes to this monorepo with git
11
12## Exporting Changes to Upstream
13
14After committing changes here, they must be exported to the individual
15repositories before they can be pushed upstream:
16
17```
18monopam push
19```
20
21This extracts your commits into the individual checkouts in `../src/`.
22You then review and push each one manually:
23
24```
25cd ../src/<repo-name>
26git log --oneline -5 # review the changes
27git push origin main # push to upstream
28```
29
30## Pulling Updates from Upstream
31
32To fetch the latest changes from all upstream repositories:
33
34```
35monopam pull
36```
37
38This updates both the checkouts and merges changes into this monorepo.
39
40## Important Notes
41
42- **Always commit before push**: `monopam push` only exports committed changes
43- **Check status first**: Run `monopam status` to see which repos have changes
44- **One repo per directory**: Each subdirectory maps to exactly one git remote
45- **Shared repos**: Multiple opam packages may live in the same subdirectory
46 if they share an upstream repository
47
48## Troubleshooting
49
50If `monopam push` fails with "dirty state", you have uncommitted changes.
51Commit or stash them first.
52
53If merge conflicts occur during `monopam pull`, resolve them in this monorepo,
54commit, then the next pull will succeed.