search

abathur / ldmud-doc

A temporary repo for working on a revamp of the documentation system for http://github.com/ldmud/ldmud
0 stars 0 forks source link

Version ordering, separation and multi-version change notes in HISTORY sections? #15

Closed abathur closed 7 years ago

abathur commented 9 years ago

It's common (enough) for us to have a history section/line that'll say something like:

HISTORY
    Added in LDMud 3.3.447, backported to LDMud 3.2.10.

Before being fully aware of lines like this, I had created syntax like :history <verstring> <verb>: <explanation> which might in the above case be like :history 3.3.447 introduced: which poses a question about how to handle backports, and how to order version history.

Obviously a use case like this makes a strictly version-number-based ordering of notes ridiculous. Assuming we don't completely re-think the markup, I see two ways to handle it. One is to just include the backport in the explanation: :history 3.3.447 introduced: also backported to 3.2.10, and the other is to introduce first and the backport notice when it happened (chronologically):

:history 3.3.447 introduced:
:history 3.2.10 backported:

Thoughts?

abathur commented 7 years ago

Going to settle on just documenting these chronologically and use the form with separate lines per version for clarity.