TL;DR the mockup: https://cdpn.io/pen/debug/eYReNXM/29d1a2e6760a69e567af62c783f2f8de

Changes on the artifact links management

Context and objectives

Historically, links were on "forward" only, that is to say A -> B. This was stored as a new changeset on A with a link on B. Display of "reverse" links was added later because it was needed to know at B level that there was a link coming from A.

Then, semantics were added on top of links: first informally with Tracker Hierarchy so A -> B with a hierarchy was actually A -parent-of-> B.

As things continued to evolve, types where introduced. Generic, platform defined, types as well has types with a semantic a Tuleap level (_is_child or _covered_by).

Nowadays, with the overhaul of Artifact Links management, we should acknowledge that:

• the legacy is to big to be changed (ie. the storage of links). So there will be forward and reverse links, pretty much forever,
• BUT we should try to mask this as a detail of implementation as much as possible.

That means, that it should be possible to interact with reverse links (add, remove, change type, change direction) transparently at artifact level without having to understand that: Given "A -parent-of-> B" And "but actually, it's B the parent" Should not end with "I need to go on A and remove the link to B and then go on B and create a new linke _is_child with A as a target".

The objective should be to "just" change, either at A or B that "B is the parent" and then Tuleap will do the heavy lifting to changeset are done at the expected artifact.

This should be handled by Tuleap backend. It should be transparent to Tuleap API consumer (JS app, legacy Tuleap front end as well as external REST API consumers)

REST PUT /artifacts/:id

As a consequence of the preview statements, the REST route to update an artifact should transparently support "forward" and "reverse" links and to the appropriate change in either artifacts accordingly.

We also need to keep the backward compatibility with the existing integrations that already set links via links key in the payload so it's expected that a new key that deals with both types of links will be added. Of course, only one of the 2 keys should be used for a given invocation.

New key behaviour

• the new key is expected to have all "forward" AND "reverse" links (while links only add forward links).
• removing a link from "forward" or "reverse" means that the target artifact is no longer linked. So for reverse links, that means updating the target artifact to remove the link torward the current one.

Update consistency

Updates should be consistent:

• Given I update "Title" and I remove a reverse link.
• And that I'm not allowed to remove the reverse link (for instance I don't have the update permission on the target artifact link field)
• Then neither Title nor removal of link should be done.