Documentation: https://tuleap-documentation.readthedocs.io/en/latest/administration-guide/project-export-import.html#references

Important: This proposal only covers the ability to keep references like "artf1234", "wiki547", "cmmt888" clickable with a link to the corresponding imported resource inside Tuleap. It means that given a wiki page "FooBar" that contains in a text "artf1234", when I look at this artifact, I don't have any link from the artifact back to the wiki page.

There are 3 steps:

• Enhance the import XML format to allow definition of mapping
• Store the conversion elements at Tuleap side
• Use the mapping table to generate the links

XML import format

For each imported item (artifacts, wiki pages, git, svn, frs package) there is a <reference> section that allows to define what is the original reference and to which item it corresponds in the target system.

Artifacts:

    <tracker>
        <artifact id="1234">
        ...
        <references>
            <reference source="artf1234" target="1234">

-> source is the original reference, target is the id of the artifact.

Plan

    <tracker>
        <artifact id="6963">
        ...
        <references>
            <reference source="plan6963" target="6963">

-> source is the original reference, target is the id of the artifact.

Subversion:

    <svn>
        <repository ...>
            ...
            <references>
                <reference source="cmmt64324" target="1">
                <reference source="cmmt64455" target="2">
            </references>

-> source is the original reference, target is the subversion revision number in the repo

Git:

    <git>
        <repository ...>
            ...
            <references>
                <reference source="cmmt64325" target="aa1ea8443b96bc8cbd0cfde28258280f1c3e166a">
                <reference source="cmmt78905" target="6710d1e62860cdad9f90636c97dd48c9da1bb8a9">
            </references>

-> source is the original reference, target is the git sha1 of the commit

FRS:

    <frs>
        <package id="1">
            ...
            <references>
                <reference source="pkg1289" target="1">

-> source is the original reference, target is the package id (needs to be added)

Mediawiki:

    <mediawiki>
        <references>
            <reference source="wiki76532" target="HomePage">

-> source is the original reference, target is the wiki page name

Covered:

• artfXXX (point to an artifact)
• pkgXXX (point to an FRS package)
• cmmtXXX (point to a commit svn or git)
• wikiXXX (point to a wiki page)

Store the conversion elements at Tuleap side

In Tuleap, there is a new plugin "TeamForge Compatibility" that will parse those references and store them in dedicated tables.

There is a sub-plugin for each supported plugin. For example:

• teamforge-compat: pkgXXX (general structure + links to feature handled by the core)
• teamforge-compat-tracker: artfXXX, trackerXXX
• teamforge-compat-svn: cmmtXXX
• teamforge-compat-git: cmmtXXX

Those plugin will know about keywords (artfXXX, pkgXXX, cmmtXXX, wikiXXX, ...) and what to store (e.g. for svn: project, repo, revision).

Concern: the size of the mapping table might be very big, even if we intend to split by services. For instance, for subversion we need to store 1 entry per repository revision.

Use the mapping table to generate the links

When a page is rendered (wiki, svn, git, etc) the existing "tuleap references" mecanism is extended by "TeamForge Compatibilty" plugin to:

• detect the TF patterns (wikiXXXX)
• replace the text by link to the corresponding element.