docs: add blog post about the monorepo migration

Author: darrachequesne

blog/2024-07-12-monorepo.md

@@ -0,0 +1,120 @@
+---
+title: Socket.IO monorepo
+slug: /monorepo/
+authors:
+  - darrachequesne
+---
+
+Hello everyone!
+
+We are happy to announce that the Socket.IO codebase has been merged into a monorepo.
+
+<!--truncate-->
+
+:::note
+
+A monorepo is a single repository containing multiple distinct projects, with well-defined relationships.
+
+More info [here](https://monorepo.tools)
+
+:::
+
+## Modular architecture
+
+As part of the work towards [v1.0](/blog/introducing-socket-io-1-0/) ten years ago (!), the Socket.IO codebase was split into several packages, each with its own responsibility:
+
+![Diagram of the package inter-dependencies](/images/blog/monorepo/packages.png)
+
+At the time, tools like [`lerna`](https://lerna.js.org/) or [pnpm workspaces](https://pnpm.io/workspaces) that make it easier to develop and publish multiple JavaScript packages from the same repository did not exist yet, so the codebase was split into multiple GitHub repositories:
+
+- https://github.com/socketio/socket.io
+- https://github.com/socketio/socket.io-client
+- https://github.com/socketio/socket.io-parser
+- ...
+
+However, this structure has several downsides:
+
+- it's harder for newcomers to dig into the codebase and understand what's going on under the hood
+- a change that affects multiple repositories is more difficult to test
+- mundane tasks like configuring CI or updating development dependencies must be replicated across all repositories
+
+That's why we have made the decision to merge all repositories into [a single one](https://github.com/socketio/socket.io). The source codes for the different packages are now located in the `packages/` directory:
+
+```
+packages/
+├── engine.io
+├── engine.io-client
+├── engine.io-parser
+├── socket.io
+├── socket.io-adapter
+├── socket.io-client
+└── socket.io-parser
+```
+
+## Workspaces
+
+To manage the packages, we use [npm workspaces](https://docs.npmjs.com/cli/v10/using-npm/workspaces) which were introduced in npm v7 (bundled with Node.js v15). The `package.json` file at the root of the repository lists all packages and their development dependencies:
+
+```json title="package.json"
+{
+  "private": true,
+  "workspaces": [
+    "packages/engine.io-parser",
+    "packages/engine.io",
+    "packages/engine.io-client",
+    "packages/socket.io-adapter",
+    "packages/socket.io-parser",
+    "packages/socket.io-client",
+    "packages/socket.io"
+  ],
+  "devDependencies": {
+    // [...]
+  }
+}
+```
+
+After cloning the repository, running `npm install` will fetch all necessary dependencies and create the links between the packages:
+
+```bash
+$ npm ls
+socket.io@ /git/socket.io
+└─┬ [email protected] -> ./packages/socket.io
+  ├── [email protected]
+  ├── [email protected]
+  ├── [email protected]
+  ├── [email protected]
+# highlight-next-line
+  ├── [email protected] -> ./packages/engine.io
+# highlight-next-line
+  ├─┬ [email protected] -> ./packages/socket.io-adapter
+  │ ├── [email protected] deduped
+  │ └── [email protected] overridden
+# highlight-next-line
+  └─┬ [email protected] -> ./packages/socket.io-parser
+    ├── @socket.io/[email protected] -> ./packages/socket.io-component-emitter
+    └── [email protected] deduped
+```
+
+And finally, running `npm test --workspaces` (or `npm test -ws`) will run the tests on all workspaces, ensuring that any change is properly tested over the whole codebase.
+
+:::tip
+
+Our [contributing guide](https://github.com/socketio/socket.io/blob/main/CONTRIBUTING.md) has been updated accordingly.
+
+:::
+
+## Git history
+
+Obviously, losing 10 years of git history from the other repositories was not an option. The repositories have thus been merged with the `--allow-unrelated-histories` option, in order to include their history in the monorepo:
+
+![Schema of the preserved git history](/images/blog/monorepo/git-history.png)
+
+Reference: https://git-scm.com/docs/git-merge#Documentation/git-merge.txt---allow-unrelated-histories
+
+## GitHub issues
+
+Similarly, it was not conceivable to lose the list of open GitHub issues across all repositories, since it is our most valuable source of user feedback, so they have been moved to the main repository: https://github.com/socketio/socket.io/issues
+
+Hopefully, this change should make it easier for anyone to contribute to the project in the future.
+
+That's all folks, thanks for reading!

diagrams/packages.mermaid

@@ -0,0 +1,8 @@
+flowchart
+    socket.io --> engine.io
+    socket.io --> socket.io-parser
+    socket.io-client --> socket.io-parser
+    socket.io-client --> engine.io-client
+    engine.io --> engine.io-parser
+    engine.io-client --> engine.io-parser
+    socket.io --> socket.io-adapter