Versioning of CSL and the CSL spec

CSL Development
21

Just noting this here for future reference; in RNC/RNG, a method to simplify multi-schema design/maintenance.

A basic csl-1.0.rnc file:

start = element style { non-meta }
non-meta = element citation { text }? & element bibliography { text }?

… and then a hypothetical csl-1.1.rnc schema file that simply redefines the pattern to use for the style pattern:

include "csl.rnc"
start |= element style { non-meta-1.1 }

# here we redefine the pattern on style
non-meta-1.1 = element citation { text }? & element bibliography { text }? & element intext { text }?
22

To put this differently, no reason to have very minor version changes for documentation fixes?

23

@Bruce_D_Arcus You are primarily concerned with the question if a you can use the 1.1 schema to validate existing styles. Is this right?

If yes, can’t we just add this to csl.rnc

  version =
    
    ## Indicate CSL version compatibility ("1.0" for CSL 1.0).
    [ a:defaultValue = "1.1" ] attribute version { "1.1" | "1.0"}

This schema will validate styles with 1.0 and 1.1. If we don’t introduce backwards incompatible changes, that shouldn’t be a problem. Or is it?

We could then just merge into master (or dev) and tag accordingly. (We should tag now with 1.0.1.) The current master just has to have those alternative attributes.

24

That wouldn’t distinguish the two models. It would tell you that 1.0 styles with an intext element were valid when they’re not.

25

Hmm, that’s right. Looks like this is indeed more complicated to get right than I initially thought. :unamused:

One reason for my confusion is that validity against a schema is not the same thing as processor compatibility. To validate a 1.0 style you’ll need a 1.0 schema but you can use this style with a processor that implements 1.8. (At least, according to what @cormacrelf writes here.) So, concerning the processor version="1.0" indicates the minimal requirements, but for validation you’ll need an exact match. Right?

This also means that we cannot (or should not) simply update the version attribute in all existing styles to version="1.1".

But: Do you think it will be necessary to validate against 1.0 once 1.1 is out? If yes, what about relying on git checkout tags/v.1.0.1 -b master for these cases.

26

This is kind of the implicit question behind my ideas in this thread.

It gets pretty complicated to try to maintain multiple schema patterns. I just pushed a commit for the in-text work that tried to do this, but I started to get confused even for this small change.

27

Have you seen this: https://blog.osteele.com/2004/08/xml-schema-versions/
Old post but still interesting.

28

I may have seen it when initially working on the first rnc schema. It does show how big a PITA it can be to try to internally version the schema.

I’d really prefer not to.

Here’s what the commits look like for the “easy” transition to 1.1 and the intext addition; more documentation than code:

29

Worth keeping in mind that article was written long before wide use of DVCS like git.

30

Ok, let’s say the next version is 1.0.2. How do style authors and processors know the exact version a style needs if we still have version="1.0"? Checking out the old version if you need to be sure is good for style authors, but what about processors?
(But perhaps a new attribute on cs:style could help here, processorversion or so.)

Maybe that’s not necessary as we can reasonably assume processors to incorporate those minimal changes quite soon. (Or we can even do the necessary changes ourselves, if necessary.) Or the processor will just complain about unknown variables so users get a warning?

31

I think yes; that style authors would really be on whatever latest versions, with preference to the latest x.x version.

32

Ok, thinking a bit more about it I guess you’re right. If we want a painless update, the next version should be 1.0.2.

What is more, I now think the approach taken by the CSL 1.0 Specification Update 2010-05-30 that I’ve already quoted above is right (although the distinction between minor and major incompatibilities is not quite clear.)

So, the new in-text feature should be on 1.0.3. (It is backwards compatible.)
The next additional backwards compatible feature is 1.0.4. etc.

Deprecating choose would perhaps be a good candidate for a 1.1. release. It’s backwards incompatible, but it’s perhaps still a minor incompatibility.

Changing the datamodel from flat to hierarchical may be considered a major incompatibility, so that would be 2.0.

Does that look feasible?

33

For me, yes.

But we obviously need new input from @Sebastian_Karcher and @Rintze_Zelle1.

In this model, we would just submit PRs against master, and keep version number constant, and the decisions would be how to sequence the merges and when to tag a 1.0.x version.

So logically, merge the low-hanging fruit of the straightforward variable and item type changes first, tag 1.0.2, then intext and tag 1.0.3.

Then do the same with docs, etc.

34

Or a development branch?

Concerning the rest, yes.

35

I’m agnostic because I don’t entirely understand the implications of that decision for us. But if it makes sense, sure.

36

Here’s an argument against develop that makes sense to me, and fits with where I was heading with this:

1 Like
37

I have no strong opinions here. I’m ok with both approaches.
Only a question: If we merge directly into master, doesn’t that mean that style authors always have to check out a specific tag? Or we can only merge immediately before a new release.

38

So, where are we now here? We’ll probably need a decision here to get on with the other issues.

39

Yes, we’re frozen. Need input from @Frank_Bennett @Sebastian_Karcher @Rintze_Zelle1

40

I’m contemplating merging the PRs in the next few days, and we can worry about version tags separately.