[META] Discussion: Logs vs Revisions

Note: this discussion is most likely going to be in the context of the next version of farmOS (8.x-2.x) built on Drupal 8. See #2361735: [META] Map out Drupal 8 / farmOS 8.x-2.x Dependencies

In farmOS 7.x-1.x, "Asset" entities are used to represent things like plantings, animals, equipment, etc, and "Log" entities are used to represent events that occur in relation to those assets.

Sometimes there is ambiguity around where a certain piece of data should be stored: on the asset, or on the log. In farmOS 7.x-1.x, revisions to assets are not stored, so changes to fields on assets do not get recorded in a structured way with a timestamp. Generally speaking, this means that fields on assets should be used for unchanging attributes of the assets, like "Name", "Crop", "Sex", etc.

An example of a changing attribute is location. Asset location is assigned by creating Movement logs that reference the asset. So an asset's location is not a field on the asset, but rather determined by looking at the most recent Movement log of that asset.

For some attributes, it's less clear whether a field or a log should be used. For example, assets have a checkbox on them that designates whether they are "Active" or not. Assets that are not active are considered "archived" in farmOS, and are not displayed in most of the UI by default.

The difficult in storing "Active" as a field, however, is that we can't tell exactly when an asset was marked active/inactive. The only timestamp recorded is the asset's "last modified" timestamp, but because that is not directly tied to the "active" field it is not reliable for that purpose.

In Drupal 8, assets will store revisions automatically. So every time you save an asset, it will save a new revision, and that revision will have a timestamp. This will allow more accurate tracking of changes to fields on the asset.

It begs the question, though: should location also be a field on the asset? And should changing locations be stored as revisions instead of movement logs? This question got me thinking more about the question: when should an asset's attribute be store in a field, and when should it be stored in a log?

I would like to propose the following rules for deciding that - for review and discussion - and to be included in the developer documentation:

If the change is specifically for one asset: use revisions.

If the change can apply to multiple assets: use logs.

In the "location" example, these rules explain why it makes sense to use logs instead of revisions. If revisions were used, and you moved 200 cattle, the same movement information and geometry would need to be stored as a revision in each of the cattle assets. With a log, you can store it in one place and reference all the assets.

In the "active" example, it makes more sense to store each active/inactive status on the assets themselves, as revisions.

That's my current thinking at least. Ideas welcome!