Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Loading…

settle on conventions for versioning #7

Open
bdarcus opened this Issue · 15 comments

4 participants

@bdarcus
Owner

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
Owner

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
Owner

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
Owner

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

@bdarcus
Owner

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

@rmzelle
Owner

My vote is for 2.

@bdarcus
Owner

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

@rmzelle
Owner

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
Owner

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
Owner

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

@rmzelle
Owner

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
Owner

@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
Owner

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Something went wrong with that request. Please try again.