settle on conventions for versioning

[bdarcus]

We need to figure out our plan going forward for version-management vis-a-vis schema changes. Possible options:

1. ids are stable across versions, and so versioning happens with git branching
2. ids are tied to versions, and so versioning happens via structure of directories in repositories; e.g. http://citationstyles.org/styles/1.1/apa.csl.

[adam3smith]

I'm not sure I'm right about this, but it seems like 2. would work better when different developers adapt new versions at different times - e.g. Mendeley could point to styles/1.1/ as soon as they implement 1.1 and Papers2 could stay with 1.0 as long as needed.

[bdarcus]

I guess the potential downside is figuring out what happens to users across those changes? If I have styles I'm using, do they automatically get updated? If yes, how?

[adam3smith]

shouldn't that be the ref managers' job? - wouldn't seem so hard to include in an upgrade routine.

[bdarcus]

But the ref manager still needs a mechanism to understand a version change.

[rmzelle]

My vote is for 2.

[bdarcus]

If we go this way, perhaps we ought to couple it with changes contemplated in issue #2.

[rmzelle]

Rereading this I'm confused. The issue description talks about ids, but these don't have to be resolvable URLs. Shouldn't we be talking about links?

[bdarcus]

Yes, that's a reasonable conclusion. We've just in the past tended to have them be the same. There's no reason we need do that now, and it actually may help us solve some issues if we don't.

[bdarcus]

One final question though: how would dependent styles fit in this scenario? Presumably they wouldn't change across schema changes?

[rmzelle]

Well, dependent styles did change significantly between CSL 0.8.1 and 1.0, and there very well could be future changes to their format. I think the safest choice is just to treat them the same as independent styles.

[simonster]

So, the more I think about it, at least the way we implement dependent styles currently, we basically have to implement this as:

1. Different style IDs for different versions
2. Change style IDs from zotero.org to citationstyles.org

We need dependent styles to reference the appropriate version of the style. We also need style IDs to be dereferenceable, for the reasons I described here in this thread on xbiblio-devel.

From an implementation perspective, I don't think changing the style IDs should be bothersome. There should never be multiple styles with the same title installed anyway, since this would be confusing, so we can use title, rather than ID, to determine what is an update to an existing style and what is a new style. We could also have separate style base IDs and versioned style IDs, but this would require schema modifications.

[rmzelle]

@simonster: could you explain requirement (1)? Starting with CSL 1.0, independent and dependent styles carry a version attribute on cs:style. Wouldn't it suffice to combine the value of this attribute with a style ID that is stable between CSL versions?

[simonster]

I think we still do. Suppose that we have a CSL 1.0 dependent style that references (e.g.) http://citationstyles.org/styles/apa.csl. As we currently implement it, when the dependent style is installed, the implementation fetches http://citationstyles.org/styles/apa.csl to get the parent.

Now suppose that http://citationstyles.org/styles/apa.csl is updated to CSL 1.1, but the implementation still supports only CSL 1.0. Now, if a user installs the CSL 1.0 dependent style, it still fetches http://citationstyles.org/styles/apa.csl, but this is a CSL 1.1 style, so it doesn't work.

If we want to make dependent styles work properly without a schema change, I can think of three options:

1. We can use different IDs for different versions and move style IDs to citationstyles.org
2. We can specify that the implementation should an HTTP header (e.g., X-Supported-CSL-Versions, which would be a comma-delimited list of supported versions) when fetching parents of dependent styles. When the implementation tries to retrieve http://citationstyles.org/styles/apa.csl, the server could then pass the appropriate version of the style for the client, or send a failure code if no appropriate version is available. This would still require changing style IDs to citationstyles.org, but the style IDs wouldn't need to be versioned.
3. We can change what independent-parent means without changing the schema itself. Specifically, we could state that it is the URL of the parent style, and not require or suggest that it match a style ID at all. The independent style ID could be http://zotero.org/styles/apa or http://citationstyles.org/styles/apa.csl or whatever, but the independent-parent in a dependent style would be http://citationstyles.org/styles/1.0/apa.csl. Now, when the dependent style is installed, the implementation fetches http://citationstyles.org/styles/1.0/apa.csl and stores some kind of "link" between the dependent style and the independent style. This is nice in that it doesn't require a schema change, but not so nice in that the "link" isn't in the CSL files themselves, but rather stored behind the scenes in some database.

If we are willing to admit a schema change, we also have a fourth option:

4. Dependent styles could specify both a parent style ID and a parent style URL (or potentially several parent style URLs for different CSL versions, in which case the implementation would pick the latest version it supports, although then we would need to decide that the format of dependent styles will always be backwards compatible). This is might be the most elegant solution, but maybe we do not want a schema change just to make this work.

Personally, I lean toward options 1 or 2. From an implementer's perspective, I don't think it makes much of a difference which we adopt. 1 would work with our current implementation and 2 would require only a couple additional lines of code.

[rmzelle]

I think we should clearly distinguish between style IDs (URIs) and links (URLs) in this discussion (and the CSL specification could definitely be improved on this point). If we go for proposal 1, would the following do?

Independent styles:

• stable style ID (e.g. <id>http://citationstyles.org/styles/apa</id>); doesn't need to be dereferenceable, and we could keep the current zotero.org IDs
• versioned link with rel="self" (e.g. <link href="http://citationstyles.org/styles/1.0/apa" rel="self"/>)

Dependent styles:

• stable style ID (e.g. <id>http://citationstyles.org/styles/apa-derivative</id>); doesn't need to be dereferenceable, and we could keep the current zotero.org IDs
• versioned link with rel="independent-parent" (e.g. <link href="http://citationstyles.org/styles/1.0/apa" rel="independent-parent"/>)

(the main limitation of this is that the dependent styles don't include the style IDs of the independent parent styles. Also, in this particular example the dependent styles don't carry a link to themselves, although the schema doesn't forbid this)

[simonster]

Rintze, as far as I can tell, that should work.

[bwiernik]

@adam3smith I think this is resolved now with the versioned repo branches?

[adam3smith]

I'm fine with what we have, but I'm not sure it actually fixes the issues raised above? E.g still not clear how the 1.0.2 version of APA (e.g.) is uniquely identified

[bwiernik]

Wouldn't that be identified by the repo branch it's retrieved from rather than in the style itself?

[adam3smith]

My understanding from Simon's point above is that ideally this would be in the style so that self link (or URI) resolve uniquely e.g. for a dependent style, but I think having implementations commit to a branch is acceptable as a solution, so I'm fine with keeping this closed.