-1 from me. Why? In the problem scope of the proposal I see statement: > An attempt to manually adjust the examples to the 10.0.0 release has > happened for a couple of weeks now, showing how time-consuming it is > to defer dealing with “satellite” repositories after releases are > done. Firstly, As I am the person working on this, I have to disagree. This is not true. The updates are not at all that problematic and it happening for weeks is me giving time to SME's to review their examples. For me that seems like you are basing the proposal on a non-existent problem and you are making statements that are simply not true.
The update is also not a problem, we have a proper versioning setup and the URL links and versions not parameterized can be fixed using script. For example for Sonataflow, the docs and examples were continually adjusted and fixed for 10.0.0, and on main, yet not published as it was stated we are not going to release it as part of the release. For docs, Sonataflow continued with the strategy established in kiegroup, to use antora [1] to create and manage docs in the incubator-kie-kogito-docs [2] repository. It works pretty well, is lightweight and quick to see the results. >From my perspective this proposal downgrades how we develop documentation and also examples. I counter-propose to follow the current approach we have for docs and examples, each can manage their own modules in these docs and example repositories. For example there would be a folder `kogito` and `drools` etc. and central property YAML file to maintain all the module attributes + common attributes in Apache KIE. Current workflows in apache/incubator-kie-kogito-docs ensure new changes are immediately visible after merging, with this CI there is a time until it propagates and I fail to see the value in that. Maybe I am misunderstanding this. We stuck to GHActions in Sonataflow and it worked flawlessly, no build-chain needed. There is no complexity hidden in the Github workflow, as you are stating in the proposal, there are only 3 steps - checkout, build, publish. You also get a nice live preview to check your changes. Same for example repo, there we already have the modularization in place and it works well. With regards to the website publishing job, I think the kie-tools is a good place for that. The website job should build the content before publishing so checking out a couple or one external repository and building it should be ok and should not force a move of documentation from established repositories with working PR checks, previews and properly maintained content. The website should get a header with Docs names where it shows the content for released version - `10.0.x` and subsequently for next. We agree on that. The content can however be pooled from many repositories. We can also do the same for Examples and just point to `10.0.x` branch in examples repository. Next, I disagree with the example ZIP as part of released artifacts, I do not see any use in that. Users can build their own if needed, it should be enough to tell them how to do it in release notes. This also adds another unnecessary job to our already bloated CI to maintain, and forces us to move and commit ZIPs around on new repo. I am sorry but I fail to see the benefit in that. Pushing ZIP of several MB daily? Infra is not going to like us and what is the value? The proposal does not take into account that https://github.com/apache/incubator-kie-kogito-examples is established in Apache KIE technologies, moving examples to incubator-kie-examples we also lose some visibility, notice 260 starts that examples repository has. The proposed workflow now involves `pnpm` which is another tool to install for our contributors that only work with drools, runtimes and apps. So development experience is going down here imho. The docs are already treated as live no? In current settings this could be done by creating the website publish job properly and setting up push notifications on the "satellite" repositories. I have been dedicated to maintaining Sonataflow examples and docs for the past months and this does not feel like an improvement, but a step back that just takes massive amounts of time from everyone. It seems to me that the root cause is a missing job for building and consuming correct documentation content to be published on our website during release. Docs repos are always branched too so if this job exists we execute it last in the chain after the binaries are out and once content is up on the website we announce the release. Maybe if we just do that and everyone provides their steps on how to build their part could be a solution. Like 1. build each component, 2. upload it to the website. 3. Website shows a navbar for each component. Best regards, Dominik [1] https://docs.antora.org/antora/latest/ [2] https://github.com/apache/incubator-kie-kogito-docs
