release: publish ui-bundle to let other projects reference it #537
Conversation
|
🚀 Preview for c74dbfd is available at https://pr-537--camel.netlify.app |
|
The new Antora based Asciidoctor docs site UI, at GitHub, has some tasks and actions to release a new version on each UI commit. That way you can be sure you know what you are getting. Dan has been saying for years the use of snapshots for the default UI is very ill-advised and finally did something about it for the Asciidoctor docs site.
https://github.com/asciidoctor/asciidoctor-docs-ui.git <https://github.com/asciidoctor/asciidoctor-docs-ui.git>
gulp.d/tasks/release.js
.github/workflows/release.yml
David Jencks
… On Feb 11, 2021, at 2:22 PM, github-actions[bot] ***@***.***> wrote:
🚀 Preview for c74dbfd <c74dbfd> is available at https://pr-537--camel.netlify.app <https://pr-537--camel.netlify.app/>
—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub <#537 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAELDXUUKXDMUKC5KQ75TLLS6RKBNANCNFSM4XPSSOYA>.
|
Hi, are you suggesting we should start releasing tags of the website at each (or specific commits) and attach the UI to each release? That would complicate a bit the workflow in subprojects that need to align, but we can think to it if it's worth. I can understand why Dan thinks that using snapshots for the default UI is a bad thing, an error there can break thousands of external projects that use it in "production". It's not exactly our context, where we want this only to have a preview of the subproject, because they don't live on their own. Personally I'd use both approaches here, so I can use snapshot in the subprojects until it breaks. Wdyt? |
|
I don't fully understand the need for this, we have one website we publish (camel.apache.org), and UI is built in the process of building that website. Is there another website that uses the same UI? If so I think this needs to be discussed on the dev mailing list first. If this is for development, the build of the UI takes a couple of seconds and you can point to it on the filesystem. To speed up working on a component of the website I usually use a customized Antora playbook file containing only the scm configuration for that component. Then the workflow is quite easy and quick: What we do not want is to have a release that's not under ASL published from a ASF repository, the UI is licensed under MPL 2.0. |
|
I'm not sure we're understanding each other completely... probably my fault:-) I certainly don't see a point in putting a version on the website with each change, but it might make sense to put a version on the ui whenever it changes. If that's hard to detect currently I'd consider moving the ui to a dedicated repo. |
You know what? It's Friday, not really a sunny day, but the weather is warm. I go for a walk.
|
|
I think there is value in this PR and the kamelet catalog needs to find a place in the website, so @zregvart if you have proposals on how to package this stuff and publish it it would be nice if you could share your thoughts. There is a lot of work behind this PR and the kamelet catalog one and lose it would be a shame. |
|
@oscerd PR this publishes the result of building the I did not object to this, I questioned the need for it, which I maintain is fair to question. |
|
Yes, but in this way, maybe we won't have to build the whole website on each build? I think we should evaluate if it is worth to at least evaluate it |
|
Maybe i misunderstood the problem but I think this was related in some way to kamelet catalog, to have a faster build |
|
🚀 Preview for c74dbfd is available at https://pr-537--camel.netlify.app |
|
It takes 19s to build the antora-camel-ui (look for I think I understand the intention of this, but I don't see the need for this. For development (running previews and such), building the theme locally and using a custom Antora playbook gives much faster turnaround. For this to be of any use for previewing one would have to wait for the PR to be merged and the release to be made. So in that regard for preview/development this is not really helpful. If the antora-camel-ui were to be used to publish a different website than camel.apache.org, this is another discussion, and one that needs to be done on the dev mailing list at that. |
|
I don't think someone wants to use it outside of the Apache organization. By the way I'll wait @nicolaferraro for better understanding. |
|
I'm back. I know that a problem, and this in particular, can be solved in multiple ways. I was just proposing one. This PR does something like publishing the snapshots of the website template on a repository, so that others can just pull it. We use this approach for Camel K and Camel K Runtime, using the official Apache Snapshots Maven repository. The advantage is that you can work on one project without having to link, build and periodically refresh the other and, at the same time, you find quickly if something breaks. It has also many drawbacks, I agree. It's not a problem if this is not merged for the reasons above, it's not essential.. |
|
I think overall the only authoritative preview will be the one done on the camel-website repository, no other preview will be up to date or as involved as the one in the camel-website repository. If building the antora-camel-ui or using a custom Antora playbook was an issue then I could reconsider this, but I don't see it as an issue. On the other hand I see a number of issues if we do releases of antora-camel-ui, spanning from that UI being only a part of the overall Antora configuration (we have patches, extensions and attributes), specific Antora version. All that would need to be duplicated for the preview to be relevant. I would also maintain that the policy on releasing to GitHub releases is not in place or has been discussed, there is an area for confusion here, whereby someone might mistake this for an official ASF release, which for licensing reason and project charter reasons (not really a part of Camel distribution), I maintain, cannot be done. So instead of doing this, I suggest working from the camel-website repository, copy the |
|
I have decidedly mixed feelings about this. My original point was simply that if the UI is made available to builds separate from the website build, it’s worth considering the latest way to do it, which happens to only work on GitHub at this point, rather than using the really problematical way the Antora default UI is “distributed” as an unstable snapshot. Some points in favor of a versioned UI, independent of the website playbook project or content repos:
Against:
|
|
I feel like we're debating what can be done and how and various pros/cons of each approach, but not focusing on why we should be doing it. The workflow and the amount of effort involved in getting a preview in another repository is equal or greater in effort and complexity than getting the preview running from this repository. With time the configuration, versions and any modifications done to how we use Antora will diverge. Disregarding everything else (legal issues, added complexity, decay of configuration), what benefit does running a preview from another repository give us in contrast to running a preview from this repository? |
|
I’m not sure publishing the UI bundle separately, versioned, is a good idea for Camel, but here are two things that I think it would enable that I think are useful:
1. Make it easy to build the same content using different versions of the UI, for comparison.
2. Make it easy to build, locally, one component, say camel-quarks, with the camel UI. I’m not imagining this being a preview, just a convenience for someone working on that component’s docs who wants to see what it will look like (broken links to other components and all).
To me, (1) would be more convincing if the entire website was built using Antora, as I’ve previously advocated for.
I also think a separate UI project is logically more tidy, but this argument is definitely undercut by the existence of the Hugo UI; it may well make more sense to keep all the UI bits for the website in the same project.
David Jencks
… On Feb 15, 2021, at 1:00 AM, Zoran Regvart ***@***.***> wrote:
I feel like we're debating what can be done and how and various pros/cons of each approach, but not focusing on why we should be doing it. The workflow and the amount of effort involved in getting a preview in another repository is equal or greater in effort and complexity than getting the preview running from this repository. With time the configuration, versions and any modifications done to how we use Antora will diverge.
Disregarding everything else (legal issues, added complexity, decay of configuration), what benefit does running a preview from another repository give us in contrast to running a preview from this repository?
—
You are receiving this because you commented.
Reply to this email directly, view it on GitHub <#537 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAELDXSULGPJY7OYFS5RAODS7DPEDANCNFSM4XPSSOYA>.
|
|
I saw this again today... I think the problem this is trying to solve is to have really quick builds of small parts of the Antora website with the actual Camel UI bundle.
After trying to fix a bunch of partial website builds eg. in camel-quarkus I'm convinced that the only sustainable approach involves generating small modifications of the antora-playbook.yml in camel-website. It's just not possible to keep anything else working. If we can agree on this then we can start to figure out how to do partial builds, and we won't need to have the UI available anywhere else. I have several ideas on how to automate partial builds, I'll see if I can come up with a somewhat concrete description. |
|
closing old outdated PRs |
I don't know if this will work with the new Apache policies (it works in my fork btw).
This will continuously release a moving
snapshottag based on the current master, with theui-bundle.ziptemplate as release artifact. This way I can set the following on a Camel subproject antora-playbook file:And that will render the subproject docs with the latest Apache Camel website template.
It's actually the same approach used by Antora for their default template (but they are on Gitlab).