Content
View differences
Updated by Kabiru Mwenja 11 months ago
<figure class="image op-uc-figure"><div class="op-uc-figure--content"><img class="op-uc-image" src="https://community.openproject.org/api/v3/attachments/360549/content"></div></figure> src="https://community.openproject.org/api/v3/attachments/360621/content"></div></figure>
<br>
### Context
_What is the issue that is motivating this decision or change?_
See ###62381
Work package activity comments are currently defined as Journal#notes, Journals is a model that keeps track of data snapshots/changes of any "Journable" providing a historical data changeset timeline. E.g. In a WorkPackage, it allows us to say track attributes changes such as "Assignee was changed from UserA to UserB".
There are several nuances to this model that are not necessarily relevant to a "Comments" model:
1. It is data intensive, every time a new journal is logged a full data snapshot of the "Journable" e.g. "WorkPackage" is stored.
2. There is a configurable journal aggregation validity period, that allows "changes" to be aggregated into one Journal if the change falls within the aggregation period
1. This aggregation introduces some complexity such as the need for virtual sequencing when rendering Activities, so that they are numbered sequentially 1..n
3. Every time a comment is added, a new data "Snapshot" is (unnecessarily) created, overriding the aggregation period in the case that subsequent journals with notes (comments) are created
4. It powers complex, data and performance intensive features such as the [Baseline Comparison](https://www.openproject.org/docs/user-guide/work-packages/baseline-comparison/)
5. The concept of "internal comments" is superimposed onto the Journals table, even though it's is not relevant to all Journables.
6. Comment relations such as EmojiReaction and Attachment are also imposed on the Journal model albeit not relevant to all Journables
<br>
📖 See the [Journals::CreateService](https://github.com/opf/openproject/blob/258af380b4401de54b917aeffa125e60e6b35ae7/app/services/journals/create_service.rb#L105-L196) for more details on inner workings
###
### Decision
_What is the change that we're proposing or making?_
Extract Journal#notes to the Comments model, define an "Events" SQL View that joins Journals and Comments into a chronological view
##### _Data Migration_
* Journals is one of the largest dataset, and it's possible a data migration would be time intensive- run adequate tests during implementation, consider data migration via background jobs if necessary albeit more complicated #65240
###
### Consequences
_What becomes easier or more difficult to do as a result of this change?_
1. Pro: **Separation of concerns**; It becomes easier to manage Comments as a standalone entity without having to worry about Journal side-effects.
2. Pro: **Data reduction**; a full Journable snapshot is no longer created on every comment write and aggregation is no longer overriden on comments creation
3. Con: **Long Running Data Migration;** Journals is one of the largest dataset, and it's possible a data migration would be time intensive- run adequate tests during implementation, consider data migration via background jobs if necessary albeit more complicated.
4. Con: **Dynamic Sorting & Indexing (\*tbc)**; as the Activities View will be served via an SQL view, we need to sort and possibly index at runtime
<br>
### Context
_What is the issue that is motivating this decision or change?_
See ###62381
Work package activity comments are currently defined as Journal#notes, Journals is a model that keeps track of data snapshots/changes of any "Journable" providing a historical data changeset timeline. E.g. In a WorkPackage, it allows us to say track attributes changes such as "Assignee was changed from UserA to UserB".
There are several nuances to this model that are not necessarily relevant to a "Comments" model:
1. It is data intensive, every time a new journal is logged a full data snapshot of the "Journable" e.g. "WorkPackage" is stored.
2. There is a configurable journal aggregation validity period, that allows "changes" to be aggregated into one Journal if the change falls within the aggregation period
1. This aggregation introduces some complexity such as the need for virtual sequencing when rendering Activities, so that they are numbered sequentially 1..n
3. Every time a comment is added, a new data "Snapshot" is (unnecessarily) created, overriding the aggregation period in the case that subsequent journals with notes (comments) are created
4. It powers complex, data and performance intensive features such as the [Baseline Comparison](https://www.openproject.org/docs/user-guide/work-packages/baseline-comparison/)
5. The concept of "internal comments" is superimposed onto the Journals table, even though it's is not relevant to all Journables.
6. Comment relations such as EmojiReaction and Attachment are also imposed on the Journal model albeit not relevant to all Journables
<br>
📖 See the [Journals::CreateService](https://github.com/opf/openproject/blob/258af380b4401de54b917aeffa125e60e6b35ae7/app/services/journals/create_service.rb#L105-L196) for more details on inner workings
###
### Decision
_What is the change that we're proposing or making?_
Extract Journal#notes to the Comments model, define an "Events" SQL View that joins Journals and Comments into a chronological view
##### _Data Migration_
* Journals is one of the largest dataset, and it's possible a data migration would be time intensive- run adequate tests during implementation, consider data migration via background jobs if necessary albeit more complicated #65240
###
### Consequences
_What becomes easier or more difficult to do as a result of this change?_
1. Pro: **Separation of concerns**; It becomes easier to manage Comments as a standalone entity without having to worry about Journal side-effects.
2. Pro: **Data reduction**; a full Journable snapshot is no longer created on every comment write and aggregation is no longer overriden on comments creation
3. Con: **Long Running Data Migration;** Journals is one of the largest dataset, and it's possible a data migration would be time intensive- run adequate tests during implementation, consider data migration via background jobs if necessary albeit more complicated.
4. Con: **Dynamic Sorting & Indexing (\*tbc)**; as the Activities View will be served via an SQL view, we need to sort and possibly index at runtime