Overhaul of link expansion docs #2763
Conversation
docs/link-expansion.md
Outdated
| reversal in link expansion and has the role of determining which editions | ||
| will need re-presenting to the content store as a result of an update to a | ||
| document. | ||
| [dependency resolution](dependency-resolution.md). This is the opposite of link expansion. When a document is updated, Publishing API works out which documents link to the updated document, and presents the linked documents to Content Store. |
There was a problem hiding this comment.
I wanted to add something here about the limitations of dependency resolution in cases where the cardinality of the links has changed or the ordering of the links, but I couldn't actually rationalise what the limitation is.
Theoretically when an edition has a new link added to it, dependency resolution should run to ensure that any content items which link to the edition are presented to content store with their latest expanded links. Is that not how things work in reality?
Obviously when it's a new document we can't have linked to it yet so dependency resolution can't work, but that can be managed through Publishing apps (though at this point if Publishing apps are doing callbacks to update related items on create, they might as well do them on update and delete as well, so dependency resolution isn't abstracting away a lot of complexity for them).
ryanb-gds
force-pushed
the
update-link-expansion-docs
branch
from
beefec7 to
23e5860
Compare
This commit makes the differences between link set links and edition links more explicit. It also explains why publishing applications might use one or the other of those categories of link and why each of them exists. It also attempts to explain dependency resolution in a bit more detail. This commit also includes a large number of edits for clarity.
ryanb-gds
force-pushed
the
update-link-expansion-docs
branch
from
23e5860 to
80ce934
Compare
ryanb-gds
force-pushed
the
update-link-expansion-docs
branch
from
80ce934 to
291991b
Compare
docs/link-expansion.md
Outdated
|
|
||
| They are typically used for taxonomy based links and aren't related to the | ||
| specific content of an edition. | ||
| Edition links should be the default approach to link creation, because link set links have the disadvantage of applying to all editions and locales of a document, which is generally not what is required in most use cases. However, edition links have a substantial limitation, which is that recursive link expansion is not applied to them. If a document needs to access data from documents more than one link away, then link set links must be used. |
There was a problem hiding this comment.
Could you link to the section on recursive link expansion here, just in case the reader isn't sure what that is.
|
|
||
| They do not follow a draft/published workflow, once added they will apply to | ||
| editions of a document on both draft and live content stores. | ||
| There was an attempt to allow recursive expansion of edition links, but we weren't able to complete it. See <https://github.com/alphagov/publishing-api/pull/2605>. |
There was a problem hiding this comment.
It's worth noting that we found another (albeit convoluted) way of solving the problem we faced, without needing recursive link expansion. We probably could've got the recursive expansion working if we'd dedicated a lot more time to it.
This commit makes the differences between link set links and edition links more explicit. It also explains why publishing applications might use one or the other of those categories of link and why each of them exists.
It also attempts to explain dependency resolution in a bit more detail.
This commit also includes a large number of edits for clarity. There's a particularly notable one in the section about edition state which was very ambiguous about whether it was discussing the linked edition or the linking edition - worth checking particularly closely for accuracy.
Trello: https://trello.com/c/iIVbEEWO