The Need for a Company Monorepo

There are three things needed to build a product:

• Organization
• Project
• Implementation

Organization is the thing that facilitates everything. It makes sure that there are resources that can be used to build the thing, that there is a place where you can work, that equipment that is needed is provided, that salaries get payed and so on.

Project is the guidance that directs the effort. It provides planning and structure to the work, ensures that risks are identified and mitigated, work items prioritized, and so forth.

Implementation is where the idea is realized; code is written, hardware designed, mechanical solutions drawn.

The thing is, all these intersect. The project can create a requirements specification, but it is the implementation that converts it to something tangible. The project might identify a lack of resources, but it the organization that supplies them.

If you separate these parts, you end up with friction. Information needs to flow between these parts and the more work that is required for this to work, the more the risks increases.¹

If you treat your project and implementation instead as a unit, you can reduce the friction between these. You will keep you software documentation alongside the actual source code. You can keep your requirements specification next to your drawings.

The remedy, I believe, is if you place this in a monorepo, alongside some CI.

Inside you place everything; reports, plans, documentation, source code, CAD files, etc. A CI pipeline is employed to build the documentation in web and PDF format.

It helps you with quality control, change control and design review.

Quality control

Since you place your documentation in a monorepo, you get access to some automated testing you can do, using a CI pipeline.

Some suggestions:

• Check requirements for completeness and fail the build if not.
• Run spell checks on documents and warn for new spelling errors.
• Identify new dependencies and fail the build if the architecture is not updated as well.
• Lint your hardware BOM to find unexpected COGS increases early, missing specs or other errors.

Continuous automated checking is a powerful tool – why use it only for your source code?

Change control

Imagine that you have a released product.² You receive a request from a customer that a feature needs some slight tweak. You create a new issue in your issue tracker where you describe what needs to be changed.

Someone gets assigned implementing the change. That person then updates both the implementation, the requirements specification and the test specification. The person pushes the changes to the forge and opens a PR. The CI pipeline builds and checks the documentation, and implementation. (Here you can go wild and check for traceability and whatnot)

A code owner file automatically assigns the product manager to review the updated requirements specification and another developer to review the implementation. A test engineer might be assigned to review the test specification and perhaps test the modified test case. Once both are happy, the change is merged and voila, one atomic change to the product.

The traceability becomes crystal clear. One issue, one PR, all changes neatly diff’ed. No need to reference document versions that are mixed with other implementation of changes.

Roles are enforced automatically. No need to hunt a responsibility document to find the appropriate person to review. No forgetting to include someone you should.

Design review

Your design review process is then also very nice. Once you decide you have a new version you wish to release, all you need to do is to create a PR from develop to main (or nightly to stable, or whatever you choose) and you get a very detailed history of what has changed.

If you create a design review branch (or release) you have a neat spot to do the final adjustments if you find a typo, you find dependencies between changes or something.

Your final piece will be adding the design review protocol, commit and push and have all involved sign off the PR. (You could in fact have the PR description be the review protocol, I would not recommend it)

All changes, neatly summarized.

This concept is something I’m currently exploring in Aqla. A live demo is hosted on Gitlab.