3 ms·

Ask HN: Monorepo design best practices? (naming convention etc.)

2 points by bredren 6y ago

I need to create a company's first repository. It will immediately cover custom plugins to use with the existing site built with an off-the-shelf CMS and commercial plugins. Eventually, it is likely the entire site will be replaced with a custom web application and mobile clients. Rather than discuss the merits of a monorepo, I'm looking for direct implementation recommendations. What is an appropriate folder naming appropriate for top-level and secondary level? i.e. Presuming the company name is largely the product name: Repo path for new custom plugins [org_name]/[company_name_cms_name?]/[custom_plugins?]/ [custom_plugin_name?]/ New Custom web application: [org_name]/[main website? web_application? company_name.com?]/[company_name_[framework_name]]? Mobile client [org_name]/[company_name_framework]?

db48x 6y ago
No naming scheme will be perfect. What you really need is a top–level document that describes what is inside each directory, and how they relate to each other. In prose, with paragraphs, headings, links, and a table of contents. Use something like asciidoctor, markdown, or org-mode so that you have something that is readable in the terminal and can also be exported to HTML.
- bredren 6y ago
  Thanks for this. Where do you generally see this document living? I mentioned in my reply to giorgioz, perhaps a readme on the root could offer this easy reference? I am curious if you have feedback on the other question I posed giorgioz around issue management on a monorepo.
  - db48x 6y ago
    Yea, right in the root directory. It doesn't necessarily have to be in the README, but the if it isn't then the README should mention it prominently.
jjgreen 6y ago
I'd keep the bottom level for repo-maintainence, so bin/ etc/ share/ for executables, configuration etc (if Unix is your thing, or some other pattern), then pkg/ for the per-plugin directories
- bredren 6y ago
  Thank you for this reply. Can you give a bit more detail on what you mean? For example, I will have a .github folder I'll need for CI/CD workflows used across the monorepo. This is sort of becoming my go-to tool for devops things in addition to deployment. Are there other repo-maintenance type folders I should be thinking about that you specifically have in mind? Did you mean to start a tree one directory removed from root so that the root has only a sparse set? What I mean to say is for your pkg/ example, have all services / apps leap off that folder rather than root? If you have any feedback on issue management as I mentioned in my other replies, also happy to take any feedback.
  - jjgreen 6y ago
    Typically you're going to have a pile of scripts for CI, development setup, deployment, so may as well have those in bin/ systematically. To avoid having configuration files clogging up the bottom-level, put those in etc/, and so on. Maybe also share/ for common library code (which could be symlinked into per-plugin locations if you wanted them to be self-contained (git handles symlinks gracefully except on Windows I understand). A doc/ directory maybe? It's likely that the amount of this whole-repo administration code will increase with time, so worthwhile having it with some structure from the start -- the /bin, /etc ... conventions are from Unix of course, but perhaps your team has other roots, in which case whatever works for you. I would advise having these as non-hidden directories with short lower-case names without spaces, makes it easier to script; and README.md files so the documentation is nice & visible on GitHub etc. And yes, the "real" per-project directories in a subdirectory, pkg/, client/, product/, something likes that. Re issues, I've previously used tags to reasonable effect. Not as convenient as per-repo issues, but that's one of the downsides to monorepos. I think the benefits outweigh those.
giorgioz 6y ago
We are using a monorepo with inside 20-30 services and 3-6 native apps (lost the exact count). We have a folder for each service or reusable library. /android (a native android app wrapping the webpapp) /app (SPA webapp) /api (REST apis) /blog /docs /graphql /ios (a native iOS app wrapping the webpapp) /www (landing pages) One tip I can give you is to flat the structure and avoid nesting as much as possible. For example might be better to place the custom_plugins in the root rather than inside company_name_cms_name. Few folders that I believe are not necessary are things like /src (everything is freaking source code). It's better to have one more folder at the root where is visible by scrolling the Project Tree than having a nested folder than is not visible until the parent folder is expanded.
- bredren 6y ago
  Thank you for the specific feedback and general. One thing I noticed is you do not include the framework in the folder name. I may have fallen out of favor, but a while back it seemed like repos would be named in part by their tech. I.e. product_name_django. A quick look at trending projects in python and swift on github seems to confirm that. [0] It seems like you give top level naming to services and to entire applications. Is there anything other than memory or doc with indicating meta to quickly discern what is what? db48x commented on a top-level doc like this, do you use something like that? Perhaps a readme provides this? Can you tell me anything about issues / tickets? For example, I commonly use github issues on a per-repo basis, on some projects that's a problem because they go together. However on a monorepo like you've described, perhaps a lot of tagging would be needed to classify what goes to what. I'm interested in how you issues up to commits, and have effective milestones filled with these issues. [0] https://github.com/trending/swift https://github.com/trending/swift, https://github.com/trending/python https://github.com/trending/python For example, you might see repos that
  - db48x 6y ago
    The advantage of a monorepo over a lot of smaller repositories is that you can make changes across your entire codebase at once. A new feature might involve adding a new api in /api, and updating the mobile apss in /android and /ios, as well as the webapp in /app. You might also mention the feature in the documentation (/docs), as well as the website in /www, and so on. All of those changes happen as part of a single merge to master (or whatever branch system you prefer) and are discussed in a single issue. Simplicity is the whole point, so you just assign the whole issue to a milestone and you're done.

2 points by bredren 6y ago

db48x 6y ago

No naming scheme will be perfect. What you really need is a top–level document that describes what is inside each directory, and how they relate to each other. In prose, with paragraphs, headings, links, and a table of contents. Use something like asciidoctor, markdown, or org-mode so that you have something that is readable in the terminal and can also be exported to HTML.

bredren 6y ago
Thanks for this. Where do you generally see this document living? I mentioned in my reply to giorgioz, perhaps a readme on the root could offer this easy reference? I am curious if you have feedback on the other question I posed giorgioz around issue management on a monorepo.
- db48x 6y ago
  Yea, right in the root directory. It doesn't necessarily have to be in the README, but the if it isn't then the README should mention it prominently.

jjgreen 6y ago

I'd keep the bottom level for repo-maintainence, so bin/ etc/ share/ for executables, configuration etc (if Unix is your thing, or some other pattern), then pkg/ for the per-plugin directories

bredren 6y ago
Thank you for this reply. Can you give a bit more detail on what you mean? For example, I will have a .github folder I'll need for CI/CD workflows used across the monorepo. This is sort of becoming my go-to tool for devops things in addition to deployment. Are there other repo-maintenance type folders I should be thinking about that you specifically have in mind? Did you mean to start a tree one directory removed from root so that the root has only a sparse set? What I mean to say is for your pkg/ example, have all services / apps leap off that folder rather than root? If you have any feedback on issue management as I mentioned in my other replies, also happy to take any feedback.
- jjgreen 6y ago
  Typically you're going to have a pile of scripts for CI, development setup, deployment, so may as well have those in bin/ systematically. To avoid having configuration files clogging up the bottom-level, put those in etc/, and so on. Maybe also share/ for common library code (which could be symlinked into per-plugin locations if you wanted them to be self-contained (git handles symlinks gracefully except on Windows I understand). A doc/ directory maybe? It's likely that the amount of this whole-repo administration code will increase with time, so worthwhile having it with some structure from the start -- the /bin, /etc ... conventions are from Unix of course, but perhaps your team has other roots, in which case whatever works for you. I would advise having these as non-hidden directories with short lower-case names without spaces, makes it easier to script; and README.md files so the documentation is nice & visible on GitHub etc. And yes, the "real" per-project directories in a subdirectory, pkg/, client/, product/, something likes that. Re issues, I've previously used tags to reasonable effect. Not as convenient as per-repo issues, but that's one of the downsides to monorepos. I think the benefits outweigh those.

giorgioz 6y ago

We are using a monorepo with inside 20-30 services and 3-6 native apps (lost the exact count). We have a folder for each service or reusable library. /android (a native android app wrapping the webpapp) /app (SPA webapp) /api (REST apis) /blog /docs /graphql /ios (a native iOS app wrapping the webpapp) /www (landing pages) One tip I can give you is to flat the structure and avoid nesting as much as possible. For example might be better to place the custom_plugins in the root rather than inside company_name_cms_name. Few folders that I believe are not necessary are things like /src (everything is freaking source code). It's better to have one more folder at the root where is visible by scrolling the Project Tree than having a nested folder than is not visible until the parent folder is expanded.

bredren 6y ago
Thank you for the specific feedback and general. One thing I noticed is you do not include the framework in the folder name. I may have fallen out of favor, but a while back it seemed like repos would be named in part by their tech. I.e. product_name_django. A quick look at trending projects in python and swift on github seems to confirm that. [0] It seems like you give top level naming to services and to entire applications. Is there anything other than memory or doc with indicating meta to quickly discern what is what? db48x commented on a top-level doc like this, do you use something like that? Perhaps a readme provides this? Can you tell me anything about issues / tickets? For example, I commonly use github issues on a per-repo basis, on some projects that's a problem because they go together. However on a monorepo like you've described, perhaps a lot of tagging would be needed to classify what goes to what. I'm interested in how you issues up to commits, and have effective milestones filled with these issues. [0] https://github.com/trending/swift https://github.com/trending/swift, https://github.com/trending/python https://github.com/trending/python For example, you might see repos that
- db48x 6y ago
  The advantage of a monorepo over a lot of smaller repositories is that you can make changes across your entire codebase at once. A new feature might involve adding a new api in /api, and updating the mobile apss in /android and /ios, as well as the webapp in /app. You might also mention the feature in the documentation (/docs), as well as the website in /www, and so on. All of those changes happen as part of a single merge to master (or whatever branch system you prefer) and are discussed in a single issue. Simplicity is the whole point, so you just assign the whole issue to a milestone and you're done.