[contrib] Repository for Confluence macros and tools

Development
#1

Hi,

I would like to contribute some macros and tools that are helpful for Confluence Migration.
The name of the repository could be

macros-confluence
or
application-confluence-migration
or
confluence-migration-tools

I would include in this module the dependencies of Confluence XML and Filter streams so that when you install this module you get the right modules installed.

Thanks
Ludovic

#2

Hi Ludo,

Great!

The only problem I see is that we don’t want to have this module replace the official confluence migration extension IMO (which is supported by the xwiki core dev team).

I think it would be better to add a new module to the existing https://github.com/xwiki-contrib/confluence repo.

However we don’t know enough what you’d like to add specifically and how much clean/production-quality it’ll be at this stage.

What do you have in mind in term of “macros” and “tools”?

Would the macros be xwiki rendering macros? If so, they’re not specific to confluence I guess and can be used with any xwiki syntax, no? Or do you consider them to be temporary and the user needs to remove them after they have migrated their content?

What would be the tools?

We could it two ways:

  1. You develop it under: application-confluence-tools. Then we check it out, and decide if we want to merge it into https://github.com/xwiki-contrib/confluence, depending on the results and usefulness.
  2. You develop it directly under https://github.com/xwiki-contrib/confluence but then I think it would be nice to explain more what you want to achieve and discuss it on the dev forum to gather feedback from others and verify we all agree about the direction.

What would you prefer?

Thanks

#3

I think we can develop in that repo in a separate module. It can be a separate sub-module installable on it’s own so it does not represent a big risk for the other packages.

The first part of the package is a set of macros that would do the bridge between confluence macros or XWiki macros. It could contain some redone macros also that would be similar to confluence ones. It’s questionnable here if we should publish them in a separate repository as the macro in itself could be working separately. If the macro is a bridge then I believe it makes full sense to have it there.

Now we could also add as dependencies all the macros of XWiki that are not provided by default in XWiki and would be used by the bridge macros, in order to ease the installation of the dependencies of that package. It’s unclear if this is a good idea or not as not all users of Confluence might be using ALL macros.

In any case the first goal here is to give some already done bridge macros and try to do the simple ones. For example the “status” macro in confluence would be an easy one.

I can start by developping in a branch of the confluence package to prepare the work.

Ludovic

#4

I forgot to answer that one. At this point the tools are scripts that detect all macros used in a set of pages and counting their usage. This allows to detect if all macros have a bridge or equivalent and which ones to focus on

#5

Note that a first step before thinking about writing a bridge macro is to write a converter from the Confluence macro call into an XWiki macro call IMO. A bridge would only make sense if it needs some runtime logic to do the conversion.

That being said I agree that adding more submodules in, https://github.com/xwiki-contrib/confluence even experimental ones, is not a problem.

#6

But there are not easy to test. It’s much easier to test and validate a bridge macro than doing the conversion. Especially if you have already converted. The process of writing a convertor when you see a missing macro is huge as you need to reimport. Also if we got something wrong in the conversion then the bridge macro can be modified. Anything done wrong in the conversion is unrecoverable.

For many of these macros I prefer the bridge approach. We could also add some scripts to make a permanent conversion.

#7

WDYM by a bridge? Just an empty macro that calls another macro?

I’m not sure it’s a good idea since it would let the user use the wrong macro name. Why not instead of convert the confluence macro to the xwiki one in this case?

Yeah I wouldn’t do this. You should know that @tmortagne is working on https://design.xwiki.org/xwiki/bin/view/Proposal/Autodiscovermacroextensions thanks to FASTEN, so that would be a solution for this need IMO. WDYT?

What does it do? If it’s useful then I’d put it in repo separate of the confluence one. There are 3 choices:

  • it’s core and then move it to xwiki-rendering or xwiki-platform
  • introduce or use an existing extension that is a pack of small macros
  • have a repo for it and release it separately

Except that it has to be maintained since it’s inside a maintained/recommended repo.

So a kind of report about macro usages. After the conversion is done? Note that it would need to run in an async job with a progress bar since there can be lots of pages. This feels like an admin tool that could go in an admin section of the confluence admin.

Except that you’re not helping your users that much since you’re creating fake macros that are not the right ones that they should use. It’s something temporary. It’s ok if your work is just a temporary experiment but it quickly needs to be converted into a converter IMO.

Note that it’s actually much simpler to test if the code is in java (we already have a rendering test fwk for it). Maybe you mean that it’s expected that the user himself/herself will need to edit the macro?