# versioning strategy?

**URL:** <https://discourse.citationstyles.org/t/versioning-strategy/939>\
**Category:** CSL Development\
**Created:** [January 18, 2011, 3:48pm UTC](https://discourse.citationstyles.org/t/versioning-strategy/939 "2011-01-18T15:48:41Z")\
**Posts on this page:** 6\
**Page:** 1

<div class="post-metadata">

**Author:** ![Bruce\_D\_Arcus1](https://avatars.discourse-cdn.com/v4/letter/b/4bbf92/32.png) [@Bruce\_D\_Arcus1](https://discourse.citationstyles.org/u/Bruce_D_Arcus1)\
**Post date:** [January 18, 2011, 3:48pm UTC](https://discourse.citationstyles.org/t/versioning-strategy/939/1 "2011-01-18T15:48:41Z")

</div>

I believe I’ve brought this up before, but we probably need to come to  
a documented conclusion about how we want to manage schema spec and  
even style changes going forward.

Off the top of my head, I see the following categories of change, in  
ascending levels of impact:

1. adding a localized term
2. adding a variable or type
3. adding a new parameter option
4. CSL syntax changes (which may or may not be tied to feature enhancements)

So first question: is this list complete?

Second question, how do we want to proceed?

Clearly 4 should be reserved for some major release (1.x, for example,  
or even full point), but beyond that? I tend to think 1-3 can be  
candidates for minor releases that do not involve style forking. But  
they do need to be reflected in the spec doc, which might mean we want  
to split the main syntax doc from the terms, variables, etc.?

Bruce

---

<div class="post-metadata">

**Author:** ![Rintze\_Zelle](https://yyz1.discourse-cdn.com/flex029/user_avatar/discourse.citationstyles.org/rintze_zelle/32/175_2.png) [@Rintze\_Zelle](https://discourse.citationstyles.org/u/Rintze_Zelle)\
**Post date:** [January 18, 2011, 4:10pm UTC](https://discourse.citationstyles.org/t/versioning-strategy/939/2 "2011-01-18T16:10:15Z")

</div>

See “A Note on CSL Versioning” at  
[http://citationstyles.org/2010/05/30/csl-1-0-specification-update-2010-05-30/](http://citationstyles.org/2010/05/30/csl-1-0-specification-update-2010-05-30/).

I don’t really see the upside of splitting of the terms and variables. Any  
CSL updates are probably going to be infrequent anyways, and CSL development  
is fragmented enough as it is with three main repositories (csl docs, csl  
schema and csl locales).

In my opinion, a more pressing issue is whether we should set requirements  
in the CSL spec for forward compatibility of CSL processors (e.g. we could  
require that unknown attributes and elements are ignored, and create tests  
for this purpose).

Rintze

---

<div class="post-metadata">

**Author:** ![Bruce\_D\_Arcus1](https://avatars.discourse-cdn.com/v4/letter/b/4bbf92/32.png) [@Bruce\_D\_Arcus1](https://discourse.citationstyles.org/u/Bruce_D_Arcus1)\
**Post date:** [January 18, 2011, 4:32pm UTC](https://discourse.citationstyles.org/t/versioning-strategy/939/3 "2011-01-18T16:32:00Z")

</div>

> See “A Note on CSL Versioning” at  
> [CSL 1.0 Specification Update 2010-05-30 - Citation Style Language](http://citationstyles.org/2010/05/30/csl-1-0-specification-update-2010-05-30/)  
> .

Yes, that’s good. But it’s a little vague on what we mean by “major  
and minor backwards incompatible updates.” I think “major” = “CSL  
syntax”

> I don’t really see the upside of splitting of the terms and variables. Any  
> CSL updates are probably going to be infrequent anyways, and CSL development  
> is fragmented enough as it is with three main repositories (csl docs, csl  
> schema and csl locales).

Well, let’s take a practical example that prompted this: we need to  
add a single, new, variable.

How do we do this?

Now, I’d presume we’d have to change the schema, change and release a  
new version of the spec document, despite the fact that nothing else  
has changed.

Splitting them means the core spec remains the same, but we just  
update the variable doc.

> In my opinion, a more pressing issue is whether we should set requirements  
> in the CSL spec for forward compatibility of CSL processors (e.g. we could  
> require that unknown attributes and elements are ignored, and create tests  
> for this purpose).

+1

What about attributes?

Do any of the implementors have comments on this, and possible spec  
language suggestions?

Bruce

---

<div class="post-metadata">

**Author:** ![Rintze\_Zelle](https://yyz1.discourse-cdn.com/flex029/user_avatar/discourse.citationstyles.org/rintze_zelle/32/175_2.png) [@Rintze\_Zelle](https://discourse.citationstyles.org/u/Rintze_Zelle)\
**Post date:** [January 18, 2011, 4:59pm UTC](https://discourse.citationstyles.org/t/versioning-strategy/939/4 "2011-01-18T16:59:58Z")

</div>

> > See “A Note on CSL Versioning” at
> 
> [CSL 1.0 Specification Update 2010-05-30 - Citation Style Language](http://citationstyles.org/2010/05/30/csl-1-0-specification-update-2010-05-30/)
> 
> > .
> 
> Yes, that’s good. But it’s a little vague on what we mean by “major  
> and minor backwards incompatible updates.” I think “major” = “CSL  
> syntax”

I don’t see the need to be less vague here. Any backwards incompatible  
update will be similarly painful, requiring style updating via some sort of  
update.xsl. And for the near future, we’re focusing on a backwards  
compatible update anyways (CSL 1.0.1, for Zotero 2.1).

> > I don’t really see the upside of splitting of the terms and variables.  
> > Any  
> > CSL updates are probably going to be infrequent anyways, and CSL  
> > development  
> > is fragmented enough as it is with three main repositories (csl docs, csl  
> > schema and csl locales).
> 
> Well, let’s take a practical example that prompted this: we need to  
> add a single, new, variable.
> 
> How do we do this?
> 
> Now, I’d presume we’d have to change the schema, change and release a  
> new version of the spec document, despite the fact that nothing else  
> has changed.
> 
> Splitting them means the core spec remains the same, but we just  
> update the variable doc.

You’d still have to update the schema, as the new variable won’t validate  
against the old schema. The only alternative would be to create a separate  
schema just for variable validation (ugh). As long as we provide a good  
changelog (and tests), nobody’s going to care where we list the variables  
(in the spec or a separate document).

> In my opinion, a more pressing issue is whether we should set requirements
> 
> > in the CSL spec for forward compatibility of CSL processors (e.g. we  
> > could  
> > require that unknown attributes and elements are ignored, and create  
> > tests  
> > for this purpose).
> 
> +1
> 
> What about attributes?

I think I touched on that: “we could require that unknown attributes and  
elements are ignored”

Rintze

---

<div class="post-metadata">

**Author:** ![Bruce\_D\_Arcus1](https://avatars.discourse-cdn.com/v4/letter/b/4bbf92/32.png) [@Bruce\_D\_Arcus1](https://discourse.citationstyles.org/u/Bruce_D_Arcus1)\
**Post date:** [January 18, 2011, 5:16pm UTC](https://discourse.citationstyles.org/t/versioning-strategy/939/5 "2011-01-18T17:16:51Z")

</div>

> > > See “A Note on CSL Versioning” at
> > > 
> > > [CSL 1.0 Specification Update 2010-05-30 - Citation Style Language](http://citationstyles.org/2010/05/30/csl-1-0-specification-update-2010-05-30/)  
> > > .
> > 
> > Yes, that’s good. But it’s a little vague on what we mean by “major  
> > and minor backwards incompatible updates.” I think “major” = “CSL  
> > syntax”
> 
> I don’t see the need to be less vague here. Any backwards incompatible  
> update will be similarly painful, requiring style updating via some sort of  
> update.xsl.

But what IS a “backward incompatible” change, and why is OK that we  
don’t define it?

I’m asking this for the future, of course. E.g. someone adds an issue  
to the tracker: how do we distinguish whether it’s targeted for 1.1 or  
1.0.2?

How do we know if a style files needs to go in a “1.0” branch versus a “1.1”?

> And for the near future, we’re focusing on a backwards  
> compatible update anyways (CSL 1.0.1, for Zotero 2.1).
> 
> > > I don’t really see the upside of splitting of the terms and variables.  
> > > Any  
> > > CSL updates are probably going to be infrequent anyways, and CSL  
> > > development  
> > > is fragmented enough as it is with three main repositories (csl docs,  
> > > csl  
> > > schema and csl locales).
> > 
> > Well, let’s take a practical example that prompted this: we need to  
> > add a single, new, variable.
> > 
> > How do we do this?
> > 
> > Now, I’d presume we’d have to change the schema, change and release a  
> > new version of the spec document, despite the fact that nothing else  
> > has changed.
> > 
> > Splitting them means the core spec remains the same, but we just  
> > update the variable doc.
> 
> You’d still have to update the schema, as the new variable won’t validate  
> against the old schema. The only alternative would be to create a separate  
> schema just for variable validation (ugh).

This is another issue we’ve talked about before: I’m really leaning  
towards some schema changes that make it possible for these simple  
changes to validate with older schema versions.

I really do think we need to treat the syntax and model of CSL  
differently than we do basic tokens.

> As long as we provide a good  
> changelog (and tests), nobody’s going to care where we list the variables  
> (in the spec or a separate document).

Does anyone else on this list (say Andrea?) care about this issue? If  
not, we can drop it.

[… snipping rest, since rintze was just pointing out I misread his a  
sentence …]

Bruce

---

<div class="post-metadata">

**Author:** ![Rintze\_Zelle](https://yyz1.discourse-cdn.com/flex029/user_avatar/discourse.citationstyles.org/rintze_zelle/32/175_2.png) [@Rintze\_Zelle](https://discourse.citationstyles.org/u/Rintze_Zelle)\
**Post date:** [January 18, 2011, 5:39pm UTC](https://discourse.citationstyles.org/t/versioning-strategy/939/6 "2011-01-18T17:39:51Z")

</div>

If all styles that validate against the old version of the schema would also  
validate against the new version, the schema changes between the two  
versions would be backwards compatible, and would qualify for e.g. a 1.0.x  
release. This would be the case for new variables, terms, types, optional  
attributes and optional elements.

Rintze