# Versioning CSL styles

**URL:** <https://discourse.citationstyles.org/t/versioning-csl-styles/1647>\
**Category:** CSL Development\
**Created:** [June 5, 2020, 9:13am UTC](https://discourse.citationstyles.org/t/versioning-csl-styles/1647 "2020-06-05T09:13:10Z")\
**Posts on this page:** 20\
**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:** [June 5, 2020, 9:13am UTC](https://discourse.citationstyles.org/t/versioning-csl-styles/1647/1 "2020-06-05T09:13:10Z")

</div>

I’m not sure where this ended up (what are we doing?), but a practical question related to this:

When we move to 1.1, hopefully soon, when we convert styles, do their IDs change, or are they simply a different version of the same style?

If the former, obviously the upgrade script could automate ID assignment.

And a bit of an aside for this thread; if the latter (which seems more sensible to me), do our styles simply get maintained on separate git branches?

---

<div class="post-metadata">

**Author:** ![bwiernik](https://yyz1.discourse-cdn.com/flex029/user_avatar/discourse.citationstyles.org/bwiernik/32/438_2.png) [@bwiernik](https://discourse.citationstyles.org/u/bwiernik)\
**Post date:** [June 6, 2020, 2:12pm UTC](https://discourse.citationstyles.org/t/versioning-csl-styles/1647/2 "2020-06-06T14:12:16Z")

</div>

IDs definitely stay the same. Schema Version updates. Before that, we could just archive the 1.0.1 styles with a GitHub release. Is there a need to continue maintaining styles on an old version?

---

<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:** [June 6, 2020, 2:57pm UTC](https://discourse.citationstyles.org/t/versioning-csl-styles/1647/3 "2020-06-06T14:57:08Z")

</div>

> [@bwiernik](#):
>
> Is there a need to continue maintaining styles on an old version?

The practical question is what happens to APA when we move to 1.1; do we:

1. tag the current repo, run the upgrade script, and continue development on 1.1, in the same branch, or …
2. create one or more branches, to maintain parallel version of the styles, in case we want to able to tweak 1.0 styles

I _think_ 2 is the better option. I’m not exactly sure how this should work, but it should make parallel development easy if we want, prioritize the latest, and also make it easy for clients to get the version they want, for whatever reason.

Perhaps we consider master latest, and branch whenever we need to increment that version number on the styles?

And per the subject of this thread, I think we keep status quo the schema, but:

1. make prominent in the spec the purpose of the id; that it is a _stable_ and machine-readable identifier
2. mention in the spec using a urn:uuid uri as a good option
3. consider requiring 2 in the styles repo for new styles

---

<div class="post-metadata">

**Author:** ![Denis\_Maier](https://avatars.discourse-cdn.com/v4/letter/d/8491ac/32.png) [@Denis\_Maier](https://discourse.citationstyles.org/u/Denis_Maier)\
**Post date:** [June 6, 2020, 3:24pm UTC](https://discourse.citationstyles.org/t/versioning-csl-styles/1647/4 "2020-06-06T15:24:24Z")

</div>

What about two subfolders: 1.0 and 1.1? Current styles will end up in 1.0, and could still be tweaked if necessary? Is that better or worse than branches?

---

<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:** [June 6, 2020, 3:29pm UTC](https://discourse.citationstyles.org/t/versioning-csl-styles/1647/5 "2020-06-06T15:29:17Z")

</div>

I think it’s worse, because it’s duplicating a lot of files.

If we just branch when we need to (like, before updating all styles to “1.1”, merge master to the “1.0 branch”), it’s practically the same result.

For example, here’s the url for one style in the 1.0 branch:

`https://raw.githubusercontent.com/citation-style-language/styles/1.0/acm-sig-proceedings-long-author-list.csl`

The question for me really is upon the move to 1.1, do we create a 1.1 branch and do development there.

---

<div class="post-metadata">

**Author:** ![Denis\_Maier](https://avatars.discourse-cdn.com/v4/letter/d/8491ac/32.png) [@Denis\_Maier](https://discourse.citationstyles.org/u/Denis_Maier)\
**Post date:** [June 6, 2020, 4:34pm UTC](https://discourse.citationstyles.org/t/versioning-csl-styles/1647/6 "2020-06-06T16:34:24Z")

</div>

Some questions:  
Do we need to maintain two versions? Couldn’t we just update all styles to 1.1 and never look back?

Or the opposite:  
Do we need to update all styles?  
Can’t we just expect a current processor to also use a 1.0 style?

---

<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:** [June 6, 2020, 4:43pm UTC](https://discourse.citationstyles.org/t/versioning-csl-styles/1647/7 "2020-06-06T16:43:43Z")

</div>

> [@Denis\_Maier](#):
>
> Do we need to maintain two versions? Couldn’t we just update all styles to 1.1 and never look back?

We could.

But maybe a better question is, are we 100% sure we’d never want to modify earlier versions? If we don’t have a version branch, we can’t.

> [@Denis\_Maier](#):
>
> Or the opposite:  
> Do we need to update all styles?  
> Can’t we just expect a current processor to also use a 1.0 style?

I guess it depends where 1.1 ends up in the end. Maybe, but not necessarily?

---

<div class="post-metadata">

**Author:** ![Denis\_Maier](https://avatars.discourse-cdn.com/v4/letter/d/8491ac/32.png) [@Denis\_Maier](https://discourse.citationstyles.org/u/Denis_Maier)\
**Post date:** [June 6, 2020, 5:56pm UTC](https://discourse.citationstyles.org/t/versioning-csl-styles/1647/8 "2020-06-06T17:56:41Z")

</div>

> [@Bruce\_D\_Arcus1](#):
>
> I guess it depends where 1.1 ends up in the end. Maybe, but not necessarily?

I wasn’t talking about 1.1 being compatible per se with 1.0. Rather, I thought a 1.1 citeproc should be able to switch into 1.0 mode.

---

<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:** [June 6, 2020, 6:04pm UTC](https://discourse.citationstyles.org/t/versioning-csl-styles/1647/9 "2020-06-06T18:04:06Z")

</div>

I’m just imaging a situation where we have some significant change, that impacts processing, and a new implementation comes around that doesn’t want to bother with 1.0.

---

<div class="post-metadata">

**Author:** ![Denis\_Maier](https://avatars.discourse-cdn.com/v4/letter/d/8491ac/32.png) [@Denis\_Maier](https://discourse.citationstyles.org/u/Denis_Maier)\
**Post date:** [June 6, 2020, 7:08pm UTC](https://discourse.citationstyles.org/t/versioning-csl-styles/1647/10 "2020-06-06T19:08:33Z")

</div>

Are you working on a processor?

---

<div class="post-metadata">

**Author:** ![Denis\_Maier](https://avatars.discourse-cdn.com/v4/letter/d/8491ac/32.png) [@Denis\_Maier](https://discourse.citationstyles.org/u/Denis_Maier)\
**Post date:** [June 6, 2020, 7:41pm UTC](https://discourse.citationstyles.org/t/versioning-csl-styles/1647/11 "2020-06-06T19:41:09Z")

</div>

Joking aside…  
That could happen, yes. But we’re currently not really heading in that direction as 1.1 will not be such a watershed. There are significant new features, but the bigger ones won’t be backwards incompatible. If we later on have a change that breaks current behaviour, we’ll have to release 1.2 anyway…

---

<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:** [June 6, 2020, 7:51pm UTC](https://discourse.citationstyles.org/t/versioning-csl-styles/1647/12 "2020-06-06T19:51:49Z")

</div>

I guess the point is, there’s not really any downside I can see to branching the styles, and it gives us flexibility going forward.

There’s already a 1.0 branch (though it’s currently about 8500 commits behind master!).

---

<div class="post-metadata">

**Author:** ![Denis\_Maier](https://avatars.discourse-cdn.com/v4/letter/d/8491ac/32.png) [@Denis\_Maier](https://discourse.citationstyles.org/u/Denis_Maier)\
**Post date:** [June 6, 2020, 7:53pm UTC](https://discourse.citationstyles.org/t/versioning-csl-styles/1647/13 "2020-06-06T19:53:12Z")

</div>

Ok. Good for me.  
More text…

---

<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:** [June 8, 2020, 12:33am UTC](https://discourse.citationstyles.org/t/versioning-csl-styles/1647/14 "2020-06-08T00:33:38Z")

</div>

I just branched off this discussion from the [Proposal: Make style ids immutable](https://discourse.citationstyles.org/t/proposal-make-style-ids-immutable/1478/34) thread, since it seemed to go rather off-topic. (per [https://community.smartthings.com/t/how-to-split-topics-using-discourse-forum/10687/6](https://community.smartthings.com/t/how-to-split-topics-using-discourse-forum/10687/6), this feature is rather hidden, but it’s the admin wrench icon in the right-hand column)

I think we should just branch off a “1.0.1” branch once we’re ready to start accepting 1.0.2 styles in the repo.

One thing I think we should consider is getting rid of “master” and just always work in the (current) version branch. That way consumers of our styles never have to worry about us transitioning between versions in a given branch (i.e. “master”), and they can just hop to a newer CSL version at their leisure.

I don’t think we should try to keep 1.0.1 and 1.0.2 branches synced with style updates (to the extent that those can be transferred between CSL versions), which seems like a very annoying task. For the jump from 1.0 to 1.0.1, we basically just froze “1.0” and only received and accepted pull requests to the (then 1.0.1) “master” branch. I recommend doing the same here again.

We might also want a freeze period between finalizing the 1.0.2 schema/spec and starting to accept 1.0.2 styles in the repo, to give the major CSL processors and software clients some time to catch up and prepare for the new release.

---

<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:** [June 8, 2020, 12:34am UTC](https://discourse.citationstyles.org/t/versioning-csl-styles/1647/15 "2020-06-08T00:34:58Z")

</div>

> [@Bruce\_D\_Arcus1](#):
>
> The question for me really is upon the move to 1.1, do we create a 1.1 branch and do development there.

Per above, yes, I think we should, and combine it with a removal of “master”. Could even do this at 1.0.2.

---

<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:** [June 8, 2020, 10:18am UTC](https://discourse.citationstyles.org/t/versioning-csl-styles/1647/16 "2020-06-08T10:18:52Z")

</div>

> [@Rintze\_Zelle](#):
>
> I just branched off this discussion from the [Proposal: Make style ids immutable](https://discourse.citationstyles.org/t/proposal-make-style-ids-immutable/1478/34) thread, since it seemed to go rather off-topic. (per [How to Split Topics? (using Discourse Forum) - #6 by Ben - Meta - SmartThings Community](https://community.smartthings.com/t/how-to-split-topics-using-discourse-forum/10687/6), this feature is rather hidden, but it’s the admin wrench icon in the right-hand column)

Thank you; I was wondering how to do that!

I agree with everything you posted after that, so +1.

Only question I have is about branching on x.x.x vs only x.x.

There are trade-offs to each.

If you do the former, the downside is complexity; for sanity, you want to probably say (as you do) they become frozen.

If you do the latter, the downside is you leave no easy way to access 1.0.1 vs 1.0.2 styles.

But I defer to you on this.

---

<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:** [June 8, 2020, 11:47am UTC](https://discourse.citationstyles.org/t/versioning-csl-styles/1647/17 "2020-06-08T11:47:16Z")

</div>

> [@Bruce\_D\_Arcus1](#):
>
> Only question I have is about branching on x.x.x vs only x.x.
> 
> There are trade-offs to each.
> 
> If you do the former, the downside is complexity; for sanity, you want to probably say (as you do) they become frozen.
> 
> If you do the latter, the downside is you leave no easy way to access 1.0.1 vs 1.0.2 styles.

The only added complexity is one extra branch per x.x.x release, right? I would just branch of “master” to “1.0.1”, and then rename/move “master” to “1.0.2”.

Especially as long as the specification isn’t clear what CSL processors should be able to handle in terms of new x.x.x releases (in terms of terms, new attributes, etc.), it seems like a no-brainer to keep a well-marked copy of the set of e.g. 1.0.1 styles around. We could probably also just use a version tag and convert it to a version branch if there is a need to make branch updates.

---

<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:** [June 8, 2020, 11:50am UTC](https://discourse.citationstyles.org/t/versioning-csl-styles/1647/18 "2020-06-08T11:50:00Z")

</div>

> [@Rintze\_Zelle](#):
>
> Especially as long as the specification isn’t clear what CSL processors should be able to handle in terms of new x.x.x releases (in terms of terms, new attributes, etc.), it seems like a no-brainer to keep a well-marked copy of the set of e.g. 1.0.1 styles around. We could probably also just use a version tag and convert it to a version branch if there is a need to make branch updates.

Right. I’m generally in favor of the “if in doubt, branch” approach here.

I think we should do both, though, including adding language (probably a single sentence) to the 1.0.2 specification on your first point.

---

<div class="post-metadata">

**Author:** ![bwiernik](https://yyz1.discourse-cdn.com/flex029/user_avatar/discourse.citationstyles.org/bwiernik/32/438_2.png) [@bwiernik](https://discourse.citationstyles.org/u/bwiernik)\
**Post date:** [June 8, 2020, 11:58am UTC](https://discourse.citationstyles.org/t/versioning-csl-styles/1647/19 "2020-06-08T11:58:49Z")

</div>

If we did go with a version tag, then later decided we wanted to update 1.0.1 styles, it would be easy enough to branch off from that tag (all praise the glory of git).

I’ve had technical problems with git repos not having a “master” branch in the past, so I’m a little wary of renaming master.

---

<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:** [June 8, 2020, 12:04pm UTC](https://discourse.citationstyles.org/t/versioning-csl-styles/1647/20 "2020-06-08T12:04:42Z")

</div>

> [@bwiernik](#):
>
> I’ve had technical problems with git repos not having a “master” branch in the past, so I’m a little wary of renaming master.

Not sure on the git/github details, but I think conceptually, this is a similar approach as having a separate develop and master branch, where develop becomes primary, and master is only updated for releases.

[Next page](https://discourse.citationstyles.org/t/versioning-csl-styles/1647.md?page=2)