11

To simplify deployment and project management tasks I maintain a monorepo containing several packages that each have a semver version. To be clear, I don't mean several repositories managed from one place, I mean a single Git repository that tracks several packages with a common toolchain. Note that this does NOT imply that this is the only repository maintained by my team. I just manage the one in question for a specific delivery pipeline.

The monorepo itself is hard to version with semver because a major version bump in a package might not justify a major version bump in the monorepo itself. Take a GUI moving from v2.9.3 to v3.0.0 on the grounds that it uses a new design system that other packages don't use yet. That's arguably not a breaking change in the monorepo, since:

  • The monorepo change would probably just amount to a dependency addition.
  • There's no reason to alarm the team with a major version bump for the monorepo that distracts from the more relevant change in the package.

The relationship between version changes in the monorepo and packages are, in general, difficult to automate unless highly-specific or brittle assumptions are taken as objective.

Note that I am assuming that two version bumps must happen simultaneously because if the monorepo does not have its own version and related tags, then that messes up the git describe output that we use company wide.

What strategy would you apply in my position?

Let me clarify some details given what I've read from other users. Assume that there are several tactics at play around the company to manage revisions. There's a monorepo with semver, but there's another repo using git submodules and yet another using cross-stack deployment tools. Given my position I have to assume that suggestions to normalize on one option are, unfortunately, non-actionable right now. The act of splitting up or combining repositories is a breaking change with a ripple effect. This should help you understand why I am restricting the question to use of semver on a repository; it's the least expensive change in context.

Improve this question
8
  • 2
    I'm sorta wondering why the version number matters in the slightest. Don't the packages that serve as dependencies more or less manage themselves, from a versioning perspective? Maybe you can clarify why you think it's such a big issue with a specific example. The Wikipedia article mentions this versioning problem in passing, but doesn't properly explain it, nor does the reference article it attributes.
    – Robert Harvey
    Sep 11, 2018 at 1:55
  • Related: atlassian.com/blog/git/git-project-dependencies
    – Robert Harvey
    Sep 11, 2018 at 2:02
  • How is your company using git describe? Why not have non simultaneous version bumps and just tag each package? You can have tags of "packageA-2.9.3" and "packageB-4.1.0" without any trouble. It still lets you go back and fork a package if you need to patch an old version's security flaws. And git describe will still function, just perhaps not how you're used to it functioning.
    – curiousdannii
    Sep 11, 2018 at 12:38
  • @curiousdannii This is the direction I'm leaning. I just need to gauge devop's sensitivity to the change in git describe's output this morning.
    – Sage Gerard
    Sep 11, 2018 at 12:51
  • @RobertHarvey Specific examples are only going to be hypothetical since the code is proprietary. Some packages are published directly to stakeholders via a CDN that resolves semver in URLs. Other packages have an internal audience, but I got push back on simplifying the versioning scheme for those (e.g. dates) from an appeal to consistency. But in any case, the issue boils down to a lack of definition, which in turn causes a lack of automation. I'm here to see if someone can suggest something better defined within stated constraints.
    – Sage Gerard
    Sep 11, 2018 at 12:56

2 Answers 2

Reset to default
7

Perhaps a more manageable solution is a Changelog.

If your publishing components anyway, there should be a changelog. I'm not talking about checkin comments. I'm talking about a version controlled file describing important changes in the software.

Have the file as prepend only. Add major changes with some symbol say asterisk, and minor changes with say a plus sign. The list is terminated by a page break of hyphens eg: "-----"

Have a release job inspect the log up to the "----". Based on what it finds and the previous version number generate a new semver. Major bumps if a major change is in the log. Minor bumps if a minor version is in the log, otherwise bump the patch number. If the release is developmental, add some incremental build number on (commit number after that if desired). If the release is a complete release, then the job injects the final version number into the changelog and prepends a new empty section.

The release job can be run automatically (after tests) or manually depending on what works for the team.

Extra points if the release job fails due to an incorrectly edited changelog.

Improve this answer
1
  • 1
    Hey, thank you for coming in to take a swing at this. Still eyeballing the community input here and appreciate the automation focus. Thinking about variations of this but am unsure if I can accept the answer yet. Will do so if this baseline is most applicable
    – Sage Gerard
    Nov 13, 2018 at 2:30
2

repositories dont have versions. The software in repositories has versions.

Normally you might tag a commit with the version of the software in that commit

But if you have more than one versioned component in your repo, then you cant reflect multiple versions in a single version number.

If your components arent used outside of the repo, they dont really need independent versions. You can just version the main application and use that as your 'repo version'

If you have a separate library which is published by itself, move it to its own repository and start versioning it with its own number distinct from the main app and other components.

This allows you to have repository versions that match the single versioned bit of software in each repo.

Also, it allows you to finish libraries and just use the unchanged binary. Which is one less source of bugs to worry about!

Improve this answer
3
  • 4
    Your answer boils down to "don't use a monorepo", which is hardly what the OP is looking for. There are of course many other options.
    – curiousdannii
    Sep 11, 2018 at 12:35
  • 1
    @curiousdannii not really. You can use a monorepo and have one version which you use as a repo version, you can use a monorepo with multiple versioned components and not have a repo version.
    – Ewan
    Sep 11, 2018 at 12:43
  • 1
    @Ewan Thank you. We're committed to maintaining single-command deployments and regimented build procedures, so adding another repository adds more work to maintain those guarantees. Work like that is likely to get deprioritized in our team, otherwise I'd spend more time working on something consistent with this answer. I understand I did not clarify some team dynamics/motivations, so I'll qualify my question accordingly.
    – Sage Gerard
    Sep 11, 2018 at 12:48

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.