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:
- adding a localized term
- adding a variable or type
- adding a new parameter option
- 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
See “A Note on CSL Versioning” at
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
See “A Note on CSL Versioning” at
CSL 1.0 Specification Update 2010-05-30 - Citation Style Language
.
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
See “A Note on CSL Versioning” at
CSL 1.0 Specification Update 2010-05-30 - Citation Style Language
.
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
See “A Note on CSL Versioning” at
CSL 1.0 Specification Update 2010-05-30 - Citation Style Language
.
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
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