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?
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?
The practical question is what happens to APA when we move to 1.1; do we:
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:
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?
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.
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?
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.
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.
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.
Are you working on a processor?
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…
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!).
Ok. Good for me.
More text…
I just branched off this discussion from the Proposal: Make style ids immutable thread, since it seemed to go rather off-topic. (per 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.
Per above, yes, I think we should, and combine it with a removal of “master”. Could even do this at 1.0.2.
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.
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.
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.
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.
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.