search

KhronosGroup / Vulkan-Site

Vulkan Documentation Project framework for integrated documentation site with spec, proposals, guide, and more
Other
25 stars 2 forks source link

Is submodule really needed for antora-ui-khronos? #32

Closed oddhack closed 8 months ago

oddhack commented 1 year ago

I am getting some odd errors / repo states after creating a branch of this repo locally and doing a build in it. It is difficult to diagnose but I think something about the antora-ui-khronos submodule changed - maybe package-lock.json got updated - in my branch, but that did not go away when I switched back to main.

I find submodules far more pain than they are worth and would prefer we not have any (and update CI accordingly). We have to clone other repos for the different components explicitly already and I'd prefer to use that model for all the repos we depend on. I think the Antora model Dan uses is to autobuild the UI bundle in its own repo, then pull it from the repository when building the site, and we may want to go down that path. Hopefully the UI will stablize quickly, unlike the module contents which will always be evolving.

gpx1000 commented 1 year ago

I'm fine if we really want to remove the submodule. It's easier to work with in CI to have the submodule; it also tracks which version corresponds with automatically so if new changes happen in the submodule, you can easily ensure everyone is using an exact commit version of your dependency. We could use other mechanisms instead. The CI currently builds the ui dependency in the repo that it gets via submodule and then places it in the correct location, so there's no human error potential in getting that setup by a separate process. However, once all of this is stabilized, then no matter what direction we go forward in, it should just be easy and require no one to have memory over "how" to do it.

marty-johnson59 commented 1 year ago

Hi @oddhack, we discussed this briefly - happy to go with your recommendation. Let Steve know if he needs to do anything here...

oddhack commented 8 months ago

Following up - I just tried fixing a problem in the antora-ui-khronos submodule and found that I could not push a branch with the fix to GitHub because the submodule required password authentication, which is no longer (?!) supported.

My take on this is to just checkout the antora-ui-khronos repo in CI as we do with the component repositories like Vulkan-Docs. If we need to pin it at a particular commit that can be done in the CI checkout action. If people are building outside CI - and I may be the only one doing this - then they'll have to replicate that effect by subdirectories or symlinks to the component repo clones and likewise the ui clone.