Replacing admin/editor/etc releases with git submodules

[gregorydlogan]

Hi all,

For the rest of this discussion I'm going to refer to 'the submodule', which means realistically any major module that's not in the mainline opencast/opencast codebase. This list currently stands at:

• https://github.com/opencast/opencast-admin-interface
• https://github.com/opencast/opencast-editor
• https://github.com/opencast/studio

As a committer group, we've noticed that the current version of the submodules in our release branches sometimes lags behind the release branch within the submodule repo itself. Notably, develop frequently doesn't get updated since there is no release manager there to remember to actually do those updates. This is, obviously, not ideal - testing on things like stable.opencast.org depends on having up-to-date code! Among several suggestions, we identified the usage of git submodules to effectively import those submodule repositories without making significant changes to them. This would allow existing development to continue in those repos without disruption, but also let the mainline repository stay automatically up-to-date with some Github magic. I have been experimenting with this locally, and I think it's a good fit. There will be a learning curve, especially if you are using an older git version and/or have never used submodules before, but it's not hard to figure out in the long run.

This runs us into a couple of questions though:

• Adding a submodule effectively adds the full contents of a normal git clone into your local clone. With most submodules this isn't an issue - that code is all unique anyway. With the admin UI it's more unfortunate. The admin UI contains the full history of Opencast, which means initial/full clone times can get pretty long. Does it make sense to rewrite the history now that we've identified a good reason to do this aside from 'storing all of the history is dumb, we should remove that'?
• Switching between submoduled, and non submoduled branches is problematic. You have to manually remove the submodule, and git thinks there are conflicts. I suspect that if we make this change, we should apply it to r/18.x and newer and drop r/17.x support at the same time. This, coincidentally, is going to happen right away anyway, but it does mean that those of us supporting not-18+ are going to have to deal with this on a regular basis.

I'm going to bring this up at the dev meeting on Tuesday, but I figured I would put this out today so people have time to read and think about this before we talk. Comments and concerns are welcome here as well.

Edit: Rewriting history in the admin module would also include nice-to-haves like removing tabs in favour of spaces, which we've also talked about doing.

[mtneug]

There will be a learning curve, especially if you are using an older git version and/or have never used submodules before, but it's not hard to figure out in the long run.

Has there been recent changes to submodules? Isn't it a quite old feature?

• Adding a submodule effectively adds the full contents of a normal git clone into your local clone. With most submodules this isn't an issue - that code is all unique anyway. With the admin UI it's more unfortunate. The admin UI contains the full history of Opencast, which means initial/full clone times can get pretty long. Does it make sense to rewrite the history now that we've identified a good reason to do this aside from 'storing all of the history is dumb, we should remove that'?

+1

• Switching between submoduled, and non submoduled branches is problematic. You have to manually remove the submodule, and git thinks there are conflicts. I suspect that if we make this change, we should apply it to r/18.x and newer and drop r/17.x support at the same time. This, coincidentally, is going to happen right away anyway, but it does mean that those of us supporting not-18+ are going to have to deal with this on a regular basis.

Timing makes sense. Although that would change the build definition mid-release, e.g. the build files for container images would need to be updated. Not sure if adopters expect this especially for custom scripts. But I guess this would minimize the overall migration pain.

[gregorydlogan]

No recent changes to submodules afaik, but I also never know what distros people are using for their daily driver. I remember being stuck on an early Maven 3 build for a long time because I was running Debian 10 which had frozen it's version of Maven a very long time ago. I wouldn't expect this to be a problem for 99% of developers, but I try and keep things like this in mind.

This would be almost transparent to someone modifying the build files. Indeed, since the containers are using recent git, the submodules would be cloned and on disk by default already - there would be no separate steps for pulling down the submodules. Most modifications would, I imagine, happen after Opencast was cloned, and thus this would be transparent to the modifier unless they're looking for this.

[LukasKalbertodt]

• Yes rewrite admin UI history
• Good timing makes the change easier, so yes
• We need a good place of documentation for "submodule woes" that just has an easy fix for every common scenario (e.g. changing branches). And also maybe include a list of things that automatically work, i.e. I didn't know the initial clone will recursively clone by default, and I don't know if switching branches (with both having the submodules, but at different revisions) works like one would expect.
• You haven't outlined how the submodules would get updated though. Just a GH action script running regularly?
• Generally sounds very good!

[geichelberger]

What if we reintroduce a monorepo?

[gregorydlogan]

One of the original goals of the current architecture was to allow for not-Java folks to comfortably work on the project. This included being, effectively, Committers in those subprojects without being general Committers.

I have no strong opposition to moving these into the upstream repo, but it would be a lot more work moving issues etc. Given the relative lack of benefit vs submodules, I would probably stick with separate repos.

[KatrinIhler]

+1 for rewriting the Admin UI and also for the timing. If people switch frequently, it's always possible to clone a repo to disc multiple times. Also +1 for Lukas' docs suggestion for common issues. we should also announce this change when it happens, maybe even on the website.

[gregorydlogan]

Further experimentation here continues to look good, so I think going ahead with this makes sense.

Specific to the admin ui, rewriting history does not break existing tags/releases - the binaries attached to the releases stay the same. The caveat to this is that the tags do get rewritten, so the links to the source for the release/tag link to new history. Since we're not changing functionality this is fine, but if you're trying to build a SBOM or something you will end up with an artifact with the old hash burned into the html, and a tag pointing at the new hash. Assuming we document what was done, and when, I think this is a non-issue. Anyone trying to look that closely at the history is probably doing that with future releases in mind, not existing ones.

TODOs:

• Prepare PRs into admin, editor, and studio
  • Documenting that history has been rewritten, when it was done and what releases this change affects
    • This documentation should include things like "don't force push the old history", and "remove all your local tags and re-fetch them"
    • Encouraging a fresh git clone is probably a good idea
  • Adding maven pom files so that they're in the right place for the upstream repo. This does not affect development internally to the module
    • Aside from studio, which would have the release branches added at this point as well.
  • Adding a GHA script to update mainline on major branch change
  • Remove existing GHA release infrastructure since it's no longer needed
  • This will generate multiple PRs since we need to create the pom file, then modify it to match each branch (cf 18-SNAPSHOT, 19-SNAPSHOT)
  • Pick a single day where no one aside from me is pushing to the submodule repositories to execute the rewrite for admin.
• Prepare PR into mainline repo
  • Documenting, briefly, how to work with sub modules. Further reading links into the git docs themselves.
    • How to do a full clone, add the submodules to existing clones, update the submodule version manually
  • Replacing the current admin, editor, and studio modules with submodules
  • This will generate multiple PRs since we need to create the submodules, then point the hashes at the correct places for each submodule+branch pair
• Rename repos so that they're all in the same vein, cf admin vs opencast-admin-ui
  • Discussion on 2026-01-20, consensus was yes and rename without the opencast- prefix.
  • Also rename the other projects which aren't submodules, cf rpm, deb, and container repos.

Open Questions:

• When do I force push the rewrite?
  • This needs to be after the docs referred to above and written, please hold...

[LukasKalbertodt]

Wait, your comment seems to imply studio and editor also get their history rewritten. Why? I thought the big history rewrite is only needed for admin UI. Studio and editor repos are kept as they are, just that the main repo references them via submodules, right?

[gregorydlogan]

Sorry, I should have been more clear. The only repo getting its history rewritten is admin, everyone else is only getting the submodules treatment.

[gregorydlogan]

Implementation of this will be part of #7493, please discuss anything further related to this in that discussion.