{ "cells": [ { "cell_type": "markdown", "id": "e7bce956", "metadata": {}, "source": [ "# Split VCS repository\n", "\n", "## Test\n", "\n", "A new version control repository exists, with code/notes split out from another repository. Implicit\n", "in starting a new project is making a decision whether to create a new repository or work in a new\n", "directory or on a branch of the most closely-related repository.\n", "\n", "Examples of the most closely-related (default) repository:\n", "- Your personal-notes\n", "- Your shared-notes\n", "- A book's associated repository (VGT, SR2, LYHGG)\n", "- Your coworker's repository\n", "\n", "Any of your personal or public repositories:\n", "- https://gitlab.com/davidvandebunte\n", "- https://github.com/davidvandebunte\n", "% - https://main.gitlab.in.here.com/vandebun\n", "\n", "If you feel uncertain about what your non-split options are, consider these DuckDuck bangs:\n", "- `!glab`\n", "- `!gh`\n", "\n", "## Value\n", "\n", "In general, this approach encourages independence and isolation.\n", "\n", "### Dependency Management\n", "\n", "[ca]: ./containerize-application.md\n", "\n", "See the reasons you split docker images in [Containerize Application][ca]; but splitting images does\n", "not strictly require splitting repositories. Conversely, it makes little sense to split repositories\n", "for code that has nearly zero special dependencies. For example:\n", "- Plain text English notes\n", "- bash\n", "- git\n", "- python (without packages)\n", "\n", "### Speed\n", "\n", "[mpdn]: https://medium.com/@mattklein123/monorepos-please-dont-e9a279be011b\n", "[mvm]: https://chengl.com/multirepo-vs-monorepo/\n", "\n", "Search. You can expect `git grep` and `git log -G` to slow down as the size of a repository\n", "increases. What if you limit your search to a directory, though?\n", "\n", "Pulls. How long does it take to pull the repository to a new developer's machine? If your `.git`\n", "directory is large, then it will take a long time. The more repos you merge (the bigger your\n", "monorepo), the slower this gets. So you have to take more time to think about keeping history small.\n", "\n", "See also \"VCS Scalability\" in [Monorepos: Please don’t!][mpdn], \"Tooling\" in [Multirepo vs\n", "Monorepo][mvm], and \"Scalability Challenges\" in `!w Monorepo`.\n", "\n", "### Publication\n", "\n", "[sn]: ./share-notes.md\n", "\n", "See [Share Notes][sn]. We often need to split across the public/private divide. You can do this\n", "without splitting repositories; instead fork the public repository and create a private \"backup\"\n", "repository to push to.\n", "\n", "The downside is if you are regularly using your fork/branch, you'll be constantly rebasing that code\n", "on the upstream until it is merged.\n", "\n", "## Cost\n", "\n", "[aom]: https://danluu.com/monorepo/\n", "\n", "In general, this approach encourages shared responsibility and centralization.\n", "\n", "### Search\n", "\n", "For example, so you can search only your personal notes repo for some thought you had. A web search\n", "is much less effective and flexible than `git grep` (even if you know which site to search).\n", "\n", "### Modularization Premium\n", "\n", "[smb]: https://martinfowler.com/articles/microservice-trade-offs.html#boundaries\n", "[mp]: https://martinfowler.com/bliki/MicroservicePremium.html\n", "[mf]: https://martinfowler.com/bliki/MonolithFirst.html\n", "\n", "Said another way, it's difficult to iterate quickly on a set of manyrepo (cost to feedback speed).\n", "This point is made in many ways in [Monorepo Explained](https://monorepo.tools/).\n", "\n", "In general, modularizing code has a cost. Even refactoring code takes time, and you shouldn't do it\n", "earlier than you need to. Slightly larger costs include even defining a simple API (such as an\n", "evaluation docker's API) and creating version numbers you manually increment.\n", "\n", "The modularization premium may include setting up some kind of \"metarepo\" (e.g. an orchestration\n", "repo).\n", "\n", "See also [Strong Module Boundaries][smb] and its discussions of [MonolithFirst][mf]. A split of\n", "repositories often means a split into separate microservices. Consider the [MicroservicePremium][mp]\n", "specifically as well.\n", "\n", "Wikipedia is a great example of how you can avoid splitting your thoughts (it's similar to a\n", "monorepo of notes) and still work on the public side of the line; the downside is how it can be hard\n", "to contribute to because it has so many \"conceptual\" dependencies.\n", "\n", "### Cross-Project CI/CD\n", "\n", "[mmm]: https://notes.burke.libbey.me/metarepo/\n", "\n", "See \"Tooling\" in [Monorepo, Manyrepo, Metarepo][mmm] and [Advantages of monorepos][aom]. An\n", "unmentioned advantage to the monorepo approach potentially lets you use only git rather than the\n", "cross-project options offered by GitLab and GitHub (tying you to their platforms).\n", "\n", "For example, let's say you wanted to enforce a code formatting standard. It's quite easy to set up a\n", "CI/CD pipeline that enforces coding standards because docker images with these tools are readily\n", "available. In practice it doesn't happen because no one wants to set this up 10 times for many small\n", "repositories, or figure out how to deduplicate `.gitlab-ci.yml` content (and still call the same\n", "content in 10 places).\n", "\n", "Worse, one team (thinking of a person, actually) wants to use `yapf`. Another wants to use `black`.\n", "They have separate repositories so they can have their own code formatting standard.\n", "\n", "### Simpler Reorganization\n", "\n", "See \"Simplified organization\" in [Advantages of monorepos][aom]. When you want to reorganize docker\n", "boundaries or \"projects\" in general you can do so without going to GitLab or GitHub. Consider the\n", "value in organizing notes in general; see [](./organize-notes.md).\n", "\n", "### Forced Collaboration\n", "\n", "[mpd]: https://medium.com/@adamhjk/monorepo-please-do-3657e08a4b70\n", "\n", "See [Monorepo: please do!][mpd].\n", "\n", "### Simpler Retrospective\n", "\n", "If you only have one or a few repos, it's much easier to review all the commits that one person or\n", "the team did in a sprint.\n", "\n", "% ### vim\n", "\n", "% In a manyrepo setup you should have one vim instance per repo, in a monorepo setup you have a vim\n", "% instance per directory.\n", "\n", "% TODO: improve-split-vcs-repository.md" ] } ], "metadata": { "jupytext": { "cell_metadata_filter": "-all", "formats": "md:myst", "text_representation": { "extension": ".md", "format_name": "myst", "format_version": 0.13, "jupytext_version": "1.11.5" } }, "kernelspec": { "display_name": "Python 3 (ipykernel)", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.9.7" }, "source_map": [ 14 ] }, "nbformat": 4, "nbformat_minor": 5 }