Journal the addition and removal of File Links on Work Packages

[mereghost]

Original ticket: https://community.openproject.org/projects/openproject/work_packages/42368

Disclaimer: This feature send me on multiple wild goose chases with a lot of dead ends, which was fun. xD

Activities ☑️

With the context from the issue, first question is: what constitutes an Activity? Any changes of the state to the object of interest. A file added, an assignee added, the creation of the object itself from the aether.

How does it work? ⚙️

Internally, every activity is an entry in the Journal model. Every new object there, has a version attached to it and we compare different versions against each other to create the activities. Each of these changes are a detail in Journal parlance.

The actual mechanism of the comparison is kinda cool, but I'll leave you to explore that.

So, for WorkPackages (or for any journalized model) every time changes happen and are saved to the database, a new Journal entry is created that points to the specialized Journal model for that object. The specialized Journal (Journal::WorkPackageJournal in this case) it snapshots the model at the time of saving.

When a journalized record is removed, so are all its journal entries.

Attachments 📋

Attachments aren't properly an attribute of WorkPackage but an associated model. Also, if when you destroy an object, the journal entries go with it, so how does it show the added and removed files on screen (or via the API)?

For those there's a couple of tricks. The Journals::CreateService instead of relying on the Journal::AttachmentJournal it creates a special type of journal called Journal::AttachableJournal that points to an Attachment and version of the Journal that itself points to the Journal::WorkPackageJournal.

When you remove the Attachment another WorkPackageJournalis added without the AttachableJournal, thus making the diff between the records show that the previous file was missing.

All this behaviour is dealt with within the Journal::CreateService massive SQL.

The Solution 🧪

I've tried to mimic the behaviour already existing by introducing the Journal::StorableJournal (yeah, I'm terrible at naming) that will behave exactly as the Journal::AttachableJournal. This meant editing the SQL inside the Journal::CreateService and adding the necessary queries.

Besides this, I had to add calls to the Journal::CreateService on both of our ...FileLink::CreateService and ...FileLink::DeleteService. The code is identical, but it felt like overkill to just create another abstraction for it (cue in Sandy Metz "the wrong abstraction is worse than repetition").

I also needed to add a formatter for our file_links on the Journal. This will allow us to change the rendered templates easily if needed. Besides this there was only a couple of touch-ups on other files to eager-load the new records.

[akabiru]

Top work! 🏆 The detailed PR description is a really nice touch 👍🏾

*I don't have enough context here so will leave the end approval to Jens :)

[ulferts]

The change is good and follows along the established patterns. Nothing in here surprised me in a bad way so the change itself is on a good track. I added some remarks but it should be easy to address.

What I have been wondering for some time is how to turn the Journals::CreateService to become more flexible so that it is easier to journalize associations and to only do the journalization of e.g. custom_values where it is necessary. But this part does not need to be addressed within this PR.

I haven't tested the code myself as don't have the env set up for it. I'll see how much of a hassle it turns out to be. If I don't manage to do it, somebody else would have to cover that part.

[ulferts]

Amends look good. So from my side, this is good to merge at will.