Publication Versioning

[elyukai]

With the release of the revised 4th German printing of the Core Rules, we started to face differences between books that have more impact than just a fix: Entries are added, removed or replaced. Optolith should take care of those differences for users, so they can play with whatever printing they want/have. But how to represent that in the reworked database? I've come up with a proposal:

In publications, you have a new printings property. This way, you can define printing identifiers that are usable across all languages, but it always maps to a specific printing in each language.

"printings": {
  "description": "Printings are used to provide a unified way to differenciate printings across all languages.",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "id": {
        "description": "The universal printing identifier.",
        "type": "integer",
        "minimum": 2
      },
      "translations": {
        "type": "object",
        "description": "All translations for the entry, identified by IETF language tag (BCP47).",
        "patternProperties": {
          "^[a-z]{2}-[A-Z]{2}$": {
            "type": "object",
            "properties": {
              "number": {
                "description": "The printing's number.",
                "type": "integer",
                "minimum": 2
              }
            },
            "required": ["number"],
            "additionalProperties": false
          }
        },
        "minProperties": 1,
        "additionalProperties": false
    }
    },
    "required": ["id", "translations"],
    "additionalProperties": false
  },
  "minItems": 1
}

Publication example:

id: 1
# ...
printings:
  - id: 2
    translations:
      de-DE:
        number: 4
translations:
  de-DE:
    id: US25001
    nameAbbr: RGW
    name: "Regelwerk"
    releaseDate: 2015-08-06
  en-US:
    id: US25001E
    nameAbbr: CR
    name: "Core Rules"
    releaseDate: 2016-06-08
# ...

It is then referenced in source references, where you can provide optional printing identifiers for in which printing an entry got introduced (default: first) and in which it got removed (default: none). Since it uses universal identifiers it can be used without specifying a language.

"since": {
  "$comment": "Experimental API",
  "description": "The book's universal printing identifier since which the entry is present.",
  "type": "integer",
  "minimum": 2
},
"deprecated": {
  "$comment": "Experimental API",
  "description": "The book's universal printing identifier since which the entry has been removed.",
  "type": "integer",
  "minimum": 2
},

Example source reference property:

src:
  - id: 1
    since: 2
    occurrences:
      de-DE:
        firstPage: 115
        lastPage: 116

What do you think about it?

Things that should be discussed:

• Is it realistic to unify printings? How to handle cases where there are no matches between languages and e.g. a publication in language A gets two revisions and a publication in language B incorporates a few changes from both revisions in language A and then releases a second revision with the remaining changes?
• How to handle page reference differences between printings?

[ElidiaSeehoff]

As far as i can say your approach looks fine, not really qualified to comment on the structure of it.
Regarding your first point i find myself asking how prevelant that problem is or how big people with DSA4 experience think that problem will be. Are we talking just changing phrasing or are we talking mainly changes to prerequisites? If prerequisites are the main problem I would personaly just botch it, with the main entry beeing the most up to date german one, and a seperat entry for each thing with changed prerequisites, that then gets referenced in the main entry. But that seems like a "solution" prone to chaotic mishaps.
Another way could be to use the oldest form as a basis and make the prerequisites dependent on the Version the User selected.

For example:
SF repair printer
The hero knows how to repair a printer, +1 on social interaktions after helping a colleague with this SF.
prerequisite: KL 16
The german edition removes the bonus to social interactions, and later the english edition keeps the +1, but lowers the prerequisite to KL 14
Maybe the prerequisites and source could look something like this:

prerequisites:
  type: Plain
  version: 1
    from: first src
    value:
      - type: Increasable
        value:
          id:
            type: Attribute
            value: 2
          value: 16
  version: 2
    from: second src
    value:
      - type: Increasable
        value:
          id:
            type: Attribute
            value: 2
          value: 14
src:
  - id: 1
    since: 1
    occurrences:
      en-US:
        firstPage: 6
      de-DE:
        firstPage: 8
  - id: 1
    since: 2
    occurrences:
      en-US:
        first Page: 9

i'm not sure how much of an abomination that code/idea is, and it would require access to ALL newer and older editions, which could pose a major financial hurdle. But i hope that i can at least get a few ideas rolling ^^

Edit: spelling, and the idea that it will be a major problem to make the version changeable. I think it will be best to make that impossible.

[elyukai]

Thanks so much for your input!

Are we talking just changing phrasing or are we talking manly changes to prerequisites?

We are (sadly) talking about differences of entire entries – like in the new revision of the German Core Rules (4th revised printing), quite a few entries or subentries were removed, others added. Changes in prerequistes or minor changes in phrasing are probably mostly bug fixes, which are fine to change without versioning them IMO (I haven't encountered any prerequisite changes yet, tho).

But i hope that i can at least get a few ideas rolling ^^

Yes, you do! ^^ <3

[ElidiaSeehoff]

Ah, then i fundamentaly missunderstood the problem ^^
If it is "just" new entries comming and old entries going, i would treat the new revision as a new book in everything but publication ID, new entries get added in line with the canonical id's and removed entries get a part in src marking them as invisible if a newer revision is chosen, just as you wrote.
Maybe add a possibility to use all avalible entries with an "expert mode", as i can see serveral of my players trying to optimice with a combination of new and old entries.
As for the "replacing entries", there i would need an example to comment on as i don't really know what this incures.

[elyukai]

i would treat the new revision as a new book in everything but publication ID

So if an entry has updated pages in revision 2 it would look like this?

src:
  - id: 1
    deprecated: 2
    occurrences:
      de-DE:
        firstPage: 8
  - id: 1
    since: 2
    occurrences:
      de-DE:
        first Page: 9

I mean, yeah, but I'm not sure yet if its great to have two source references with the same publication identifier … 🤔

new entries get added in line with the canonical id's

I'm not quite sure I understand what you mean … New entries cannot be added sorted by publication id since this would require a remapping of the previous identifiers and that would be a breaking change. I can only do that now since I already introduce breaking changes.

Maybe add a possibility to use all avalible entries with an "expert mode", as i can see serveral of my players trying to optimice with a combination of new and old entries.

Yeah, that would be possible, although it probably wont make it in the 2.0.0.

As for the "replacing entries", there i would need an example to comment on as i don't really know what this incures.

"Replacing" just as a combination of adding and removing: The Moha culture has been split up into two cultures, Utulu and Forest Folks (I think thats the English translations, not sure tho).

[ElidiaSeehoff]

Yeah, ment it just as you wrote the code. it seems like the most straight forward solution, other than reworking the whole publication ID system and giving each revision it's own publication ID.

Regarding the new entries, i mean adding them at the end, just continuing with the ID's. One would just act as if the new revision was a new book that came canonical at the release date of the revision. Don't really have a clue how to do it differently :-/

[elyukai]

Ah, okay, yeah, then we mean the same thing. 👍🏻 Thanks again for your feedback! 🤗🥰