Citation Style Language

Versioning of CSL and the CSL spec

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.

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

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:

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

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?

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

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?

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.

Or a development branch?

Concerning the rest, yes.

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

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

1 Like

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.

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

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

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

Basically good for me. But then current master will be ahead of 1.0.1. Will that cause trouble if someone validates against that schema version?

My thought is if people want to validate against 1.0.1, they should validate against that tag?

1 Like

Main problem I see is the sequence of the commits would then constrain the tagging. As in, if I merged intext first, that would pretty much require it be part of same tag is the more minor changes.

I guess unless we rewrite the git history, which is possible, but maybe a little risky?

I merged the variable and type addition commits.

I believe I wrote the commit messages such that all linked issues are now closed.

Any other minor changes along these lines we want to add now?

On the intext PR, I had to do some git surgery to fix it. Can you two take another look?

@bwiernik @Denis_Maier

I will take a look at intext. There are a few more variables that I think we can add in the minor release. I will open a new PR.

1 Like