I’m honestly +1 for the Guided Tour pretty name, but feel free to suggest other options.
As for the technical name, I propose xwiki-platform-guidedtour.
Since this is a blocker for development, the deadline for choosing a pretty + technical name will be 2026-03-17T22:59:00Z.
The new extension will be heavily inspired by the existing Tour App, but I think it was decided to split them, in order to make the new app optional, until it is ready to be installed by default in XS.
The PR was made as a first draft prototype, but it should be moved now to a new module, to also rewrite the app to adhere to newer XWiki code style/hyerarchy. But we’re lacking a name right now.
I agree with Gabriel, I’m +1 for Guided Tour and xwiki-platform-guidedtour
Continue bundling the Tour extension in XS. But allow users to install the new Guided Tour. Will they be compatible? What happens when you have both installed?
At some point, move the Tour extension to contrib and bundle the Guided Tour in XS (thus replacing the Tour extension).
I’d still be in favor of having a single Tour extension and develop a v2 of it (in a branch), and when ready merge on master. It could even be developed on master with some feature flags.
That’s another debate.
Conceptually I think we could build on top of the existing tour application.
I’m not against this option.
On the other hand, @surli is more in favor of creating a new app (hence the new name), and to provide a migration path from the old tour to the new tour later.
Pros:
easier to keep having the old, less pressure to be backward compatible
easier code review since the developments are going to change the architecture in significant ways
Cons:
extra work to write the migration logic.
risk of conflicts when the old and new tours are installed at the same time
Yes, I think we need to agree about the strategy first. Choosing the name would be a consequence of that.
Note that we don’t upgrade often the major version for extensions but it’s meant for that (we use semantic versioning for extensions too). So a 2.x version doesn’t need to be compatible with a 1.x version.
For me the main reason to start a new extension is that we basically start from scratch: we might reuse some concepts from the existing tour app, but that’s it. We’re not even sure to reuse xobjects to define tour (still to be discussed), technologies will be very different, the structure of the app too etc.
So I feel it’s really much more easier to just separate them entirely.
Well we’re not even sure to migrate anything, and it’s the same cons for a tour 2.0 if we don’t preserve backward compatibility. It might be even be harder since here we might want to provide a migration to allow upgrades.
For me it’s the only risk and it should be easy to mitigate: maybe it won’t even be a problem to have both app installed at the same time. And if it’s a problem we can probably provide a detection in the new app to disable it and put a warning when tour is installed.
I’m not sure if I fully understand, so I’ll try to rephrase in my own words. Please let me know if I got it right.
What you’re saying is that it would be ok to develop the Guided Tour Extension on a separate branch, with completely different technologies compared to the current Tour App, and then, at some point, release it as a replacement for the Tour App, in a v2, even if the v2 implementation wouldn’t be backwards compatible with the v1 implementation.
If that’s the case, I feel like this approach could potentially cause more issues than it would solve, since we’d need to make sure from day 1 that everything is migrated properly and cleaned up when the user updates from v1 to v2.
Also, I’m not sure how many users maintain custom tours on their wiki, but I think this would also force them to basically migrate to a new tool. What happens if they accidentally update to v2 then want to go back to v1? Do we provide upgrade and downgrade scripts for tours?
Plus, there would be no way of the 2 tools coexisting, as we currently aren’t sure if having one of them would really hinder the use of the other. In practice, it would definitely be redundant to install 2 tools that do the same thing, but if it functionally works, maybe we could just notify the user that they can remove one of the extensions instead of forcing them to do so.
Yes, if the topic is the same and the only difference is the technologies, it wouldn’t make much sense to develop a new extension as this would be something internal that users don’t see.
The trick is in knowing if the new Guided Tour is an evolution of the existing Tour or a revolution (i.e. a full replacement). At first glance, it feels like there are some common concepts (and thus we could imagine not breaking existing users and just adding new features). Note that for a v2, as I said, it’s acceptable to break some backward compatibility. Of course if you break 100% of it, then it doesn’t make sense anymore, and it’s no longer an evolution…
I haven’t followed enough the latest discussions on the Guided Tour to know if it’s an evolution or a revolution.
We’re not even sure to reuse xobjects to define tour (still to be discussed)
That’s an important aspect, and if we do, then it feels more like an evolution with new features added.
True, and I agree it makes sense only if we reuse the same xobjects and more generally we don’t break too much.
Good point. It would mean uninstalling the latest version and re-installing an older version. Since we bundle the Tour, it would mean users will be forced to upgrade to the new version I think.
This is more about what we want to support. I doubt that we’ll support both and thus users will have to move to the new tour eventually (if they want bug fixes and new features/improvements).
Note that the Extension Manager has a way to indicate that a new extension replaces another one (by indicating it in the pom.xml), so we could very well do that even if it’s a separate extension. I think that if we don’t do this, then the EM will uninstall the old tour extension automatically anyway since it’d not be bundled anymore in the XS flavor.
But that’s when we bundle the new tour, for now, we could just not bundle it. However, note that when we bundle it (and that’s the idea I believe), we’ll be faced with this situation.
It feels a bit easier because it’s always easier to start from scratch. But we need to take into account our users. Having 2 tours, 2 documentation will make it harder for users since they’ll need to understand the difference and decide which one to use (or which one is installed). Imagine google for “xwiki tour”. You’ll get 2 entries.
I’m not against having 2 extensions. I still think that it depends on whether we see the new tour as an evolution or a revolution.
So, without knowing more, I’m +0 to have 2 extensions if that’s what you believe is the right choice but please take into account the points listed above.
If we have 2 extensions, “Guided Tour” is good for me for the name and xwiki-platform-guidedtour. I don’t like that when we move the Tour extension to contrib/attic, there’ll remain only a single tour in XS, which would ideally be named just “Tour” and at xwiki-platform-tour but I guess that’s acceptable that it won’t be. That’s part of the confusion I mentioned above about having 2 extensions vs one.
Thank you for your detailed response, Vincent. I agree with your points about user confusion, and we will keep that in mind moving forward.
To add some context, we were thinking of the Guided Tour as more of a revolution to the Tour App, rather than an evolution. The plan is to maintain a similar feature set, but to modernize and simplify the codebase, which may mean not worrying about backwards compatibility. Instead, we’re leaning more towards providing migration scripts for the current tours to ensure that users have a good experience when the Guided Tour becomes the default.
Thank you again for sharing your perspective, it will be really helpful since we want to make sure that the transition from one extension to the other is as smooth as possible. Our main goal is to improve the user experience and the maintainability of the extension over the long run, even if that means some short-term challenges.
