Status page for style repository

Thanks for spotting the error Charles; I will change that line in the
test script to make it work on 1.8. too.

Bruce, can you explain what is odd about the progress indicator?

Just that this is what I see for a long time while it’s running.

[image: Inline image 1]

Yes, it might be better to always commit to “master” and push updates from
there to a branch for the most recent CSL version (now “1.0”, soon “1.0.1”)
(I’m not sure we need to maintain styles for older CSL versions). That way
consumers of CSL styles such as Zotero can just pick a branch (e.g. “1.0”),
and upgrade when they’re ready. That will especially help once we have a
big non-backward compatible upgrade, similar as what we had when we went
from CSL 0.8.1 to 1.0.

RintzeOn Thu, Jul 19, 2012 at 5:40 PM, Sylvester Keil <@Sylvester_Keil>wrote:

Committing to version branches (1.0, 1.0.1, 1.1) would be simpler to
explain. Style maintainers could then just check changes in on the
branch of the style they have to hand, and Travis magic can work out
whether it’s a branch to which fast-forwarding in master applies etc.

Frank

If there are to be release branches, I wonder if it might be possible at some
point to contemplate hosting variants such as styles based on the MLZ
extended schema. That’s not a loaded question; it’s a matter for the CSL
development team, and not something I will push if it’s felt to be out of
order. On the plus side, it would help strengthen the perception of a
connection between the two projects. On the minus side, I suppose there
might be concern over potential confusion, and increased complexity in the
archive.

In any case, I’ll throw the idea out there to see what people think.

Frank–
View this message in context: http://xbiblio-devel.2463403.n2.nabble.com/Status-page-for-style-repository-tp7523821p7578116.html
Sent from the xbiblio-devel mailing list archive at Nabble.com.

Well, I think the elephant in the room question we probably ought to answer is:

Do we consider the use cases MLZ now covers, but CSL proper does not,
to be on the future CSL roadmap?

If yes, we should cover them in CSL, in as non-disruptive a way as
possible, so that there’s no need for a separate repo, or even branch
(aside from maybe a change in version number).

Do we consider the use cases MLZ now covers, but CSL proper does not,
to be on the future CSL roadmap?

Reading “the use cases MLZ now covers” as improving CSL support for law and
international citing, yes, I would like to keep those targets on the
roadmap. Why wouldn’t we?

If yes, we should cover them in CSL, in as non-disruptive a way as
possible, so that there’s no need for a separate repo, or even branch
(aside from maybe a change in version number).

That’s obviously desirable, but for the near-term (say at least a year)
there really isn’t a way around maintaining a fork of CSL for MLZ. Frank’s
MLZ styles depend on a fair number of modification to CSL proper (see
https://github.com/rmzelle/schema/blob/master/csl-mlz.rnc for the complete
modification schema, as well as
http://gsl-nagoya-u.net/http/pub/citeproc-js-csl.html ). Adding support for
all those features in CSL will take quite a bit of time (the main reason
Frank forked CSL in the first place), and they require some progress on
several long-standing issues such as improving identifier support.

As to Frank’s question of whether MLZ styles can be added to the
citation-style-language styles repo, I would prefer not to for the time
being. I’d be happy to work with him to bring as many MLZ-CSL features to
CSL proper once we get 1.0.1 out of the door, though.

Rintze

Do we consider the use cases MLZ now covers, but CSL proper does not,
to be on the future CSL roadmap?

Reading “the use cases MLZ now covers” as improving CSL support for law and
international citing, yes, I would like to keep those targets on the
roadmap. Why wouldn’t we?

Because it’s possible the cost is too high, and the benefit too low.
I’m not saying that’s the case, but it is the calculation.

To bottomline it: can we add these in such a way that we’ll see
multiple implementations?

To me, that should be the question for any future changes really.

If yes, we should cover them in CSL, in as non-disruptive a way as
possible, so that there’s no need for a separate repo, or even branch
(aside from maybe a change in version number).

That’s obviously desirable, but for the near-term (say at least a year)
there really isn’t a way around maintaining a fork of CSL for MLZ. Frank’s
MLZ styles depend on a fair number of modification to CSL proper (see
https://github.com/rmzelle/schema/blob/master/csl-mlz.rnc for the complete
modification schema, as well as
http://gsl-nagoya-u.net/http/pub/citeproc-js-csl.html ). Adding support for
all those features in CSL will take quite a bit of time (the main reason
Frank forked CSL in the first place), and they require some progress on
several long-standing issues such as improving identifier support.

I understand that. But, per your point below, I don’t think we should
be hosting that fork.

Bruce

Because it’s possible the cost is too high, and the benefit too low.
I’m not saying that’s the case, but it is the calculation.

To bottomline it: can we add these in such a way that we’ll see
multiple implementations?

To me, that should be the question for any future changes really.
I don’t know about multiple implementations, though I’d suppose since
Frank writes citeproc and Mendeley uses citeproc, at least two
implementations are pretty likely.
But more generally about cost-benefit:
I don’t think the benefit of providing support for proper legal
citations can be overstated:

  1. It’s a distinguishing feature - no other product can really do it
    (which is why Frank got involved in it)
  2. Legal citations are a huge market - in the US alone, 45k people
    graduate law school every year and they’re expected to use correct
    bluebook citations and in many other countries law is the largest or
    one of the largest academic fields.
  3. Many other social sciences rely on correct law citations - e.g. in
    political science, economics, and sociology, the requirement of most
    citation styles is to cite legal citations according to bluebook or a
    comparable guide.

The point being - if we’re actually talking cost benefits, the
benefits of this are so huge that almost any costs in terms of
complicating csl are justified.

As for the original question - I’d personal be happy to help support
an MLZ branch of the citationstyles repository and since I don’t think
most users ever see what’s on github I don’t really see much of a
downside.

Sebastian>

Because it’s possible the cost is too high, and the benefit too low.
I’m not saying that’s the case, but it is the calculation.

To bottomline it: can we add these in such a way that we’ll see
multiple implementations?

To me, that should be the question for any future changes really.
I don’t know about multiple implementations, though I’d suppose since
Frank writes citeproc and Mendeley uses citeproc, at least two
implementations are pretty likely.

Those don’t count: citeproc-js is one. Mendeley and Zotero are simply consumers.

Sylvester’s is another, as is Andrea’s, as is the one used in Papers.

The “multiple implementations” criterion is a very common measure for
standards, because it insures the specification is clear and
reasonable (otherwise, there’s not much reason to have a spec to begin
with).

But more generally about cost-benefit:
I don’t think the benefit of providing support for proper legal
citations can be overstated:

  1. It’s a distinguishing feature - no other product can really do it
    (which is why Frank got involved in it)
  2. Legal citations are a huge market - in the US alone, 45k people
    graduate law school every year and they’re expected to use correct
    bluebook citations and in many other countries law is the largest or
    one of the largest academic fields.
  3. Many other social sciences rely on correct law citations - e.g. in
    political science, economics, and sociology, the requirement of most
    citation styles is to cite legal citations according to bluebook or a
    comparable guide.

The point being - if we’re actually talking cost benefits, the
benefits of this are so huge that almost any costs in terms of
complicating csl are justified.

Tell that to the implementors (beyond Frank). If they find the
argument compelling and are willing to put in the resources
(time/cash) to seek out these opportunities, then that makes your
case.

If they won’t, then we have a problem.

As for the original question - I’d personal be happy to help support
an MLZ branch of the citationstyles repository and since I don’t think
most users ever see what’s on github I don’t really see much of a
downside.

I of course disagree. MLZ is a fork, and so are its styles. I don’t
like the idea of incorporating those styles, particularly if we’re
going to be supporting these features in the not-too-distant future
(if we don’t, then that’s another matter, and bears some thought).

In any case, I suggest we first get some agreement on the bigger and
more fundamental point before we discuss further what to do in the
short run with the MLZ styles. The same issue applies to any other
significant changes we want to make to the spec, and therefore the
styles.

Charles, Sylvester, Andrea (who is a legal scholar as well, but as
such, has other responsibilities); what do you think?

Bruce

PS - I’ll be on vacation soon; feel free to talk among yourselves :slight_smile:

The point being - if we’re actually talking cost benefits, the
benefits of this are so huge that almost any costs in terms of
complicating csl are justified.

Tell that to the implementors (beyond Frank). If they find the
argument compelling and are willing to put in the resources
(time/cash) to seek out these opportunities, then that makes your
case.

If they won’t, then we have a problem.

…(snip)…

Charles, Sylvester, Andrea (who is a legal scholar as well, but as
such, has other responsibilities); what do you think?

It looks like MLZ would be a great addition to CSL, for exactly the reasons stated by Sebastian. We have a number of Papers user that work in law departments or firms, and improved support for citations in this field would be very welcomed. We would definitely start adding support for whatever changes to CSL are necessary. In general, we will follow the CSL improvements and integrate them in Papers asap as they develop.

In short: MLZ FTW.

I also agree that it is better to keep it as a separate repository for now. It will make sense to integrate it as a version branch when the time comes.

charles

Agreed that the MLZ extended schema should remain in a fork for the
present. Thanks to Rintze, Sebastian and Charles for words of support,
and for contributions to date. Legal and multilingual styles are a
tall order, but we’ll get them into the mainstream eventually.

Frank

I think nobody objects against having separate branches for the different
CSL releases. The minimal branch structure would then be: “0.8.1”, “1.0”,
“1.0.1” (and so on), “master”.

To enable people to subscribe to a CSL branch without having to worry that
this cloned branch changes version (which would happen in “master” with our
current setup ), we would need a branch for the current CSL release, in
addition to branches for older CSL releases.

That arrangement by itself however doesn’t solve the problem of preventing
invalid styles from ending up in the version branches, and we’ll likely
want to be able to accept patches for older CSL versions. I can think of
two options here:

a) we keep using “master” for accepting CSL styles of the most recent CSL
version, and allow direct commits and merging of pull requests with invalid
CSL styles. We also accept pull requests to version branches of older CSL
releases, but only once Travis CI has checked them. A GitHub service hook
can be used to check the “master” branch after each commit, and push the
commit to the most recent CSL version branch if there are no errors (the
service hook script can either wait for Travis CI or run the tests itself).

b) we keep using “master” for accepting CSL styles of the most recent CSL
version, but only accept pull requests. We also accept pull requests to
version branches of older CSL releases. In both cases, we would only merge
pull requests once Travis CI has checked them. A GitHub service hook can be
used to automatically push any changes made to “master” to the most recent
CSL version branch.

The downside of only relying on pull requests is that fixing small errors
can be cumbersome (you have to download the file(s) by hand via the GitHub
web interface), because the CSL team members typically won’t have commit
access to the fork of the person making the pull request. In some cases it
might be easier to accept broken styles and fix them up after merging.

RintzeOn Thu, Jul 19, 2012 at 5:40 PM, Sylvester Keil <@Sylvester_Keil>wrote:

I like the second approach, but in that case, I’m not sure a master branch is necessary at all. GitHub allows you to rename the master branch and set a different default branch for a repository. The master branch could also be a symbolic-ref to the most recent version branch.

You can fix small errors before pushing to the repository if you merge pull requests the command line way:

git fetch git://github.com/<>/styles.git
git merge <>>

Fix and commit fixes

git push

Simon

Good to know, and I agree that mirroring “master” against the most recent
CSL release is unnecessary. However, we might want one additional branch
(which can be either “master”, “development”, or “experimental”) to accept
styles that validate against the schema trunk. It might be handy to have
some styles available for testing before an official CSL release (the
current policy is to reject CSL 1.0.1 styles, since everything in the
"master" branch should validate against the CSL 1.0 schema).

RintzeOn Tue, Jul 24, 2012 at 12:49 PM, Simon Kornblith <@Simon_Kornblith>wrote:

I think it is indeed important to have that discussion, because it would be nice to start building a 1.0.1 library of styles.

It is also true that the ‘master’ branch almost looks like it has no role other than an alias for the official stable version. But in a way, that is exactly what master is supposed to be, so it’s not necessarily a bad thing to keep it around for that role.

With the Travis CI stuff in place, I think we can have the following setup (sorry it’s again different from the proposals so far):

  • one branch for each version, where only Travis-approved commits go, thus for instance:

    • branch “1.0”
    • branch “1.0.1”
    • branch “1.1”
    • branch “master” = same as 1.0 for now, and soon same as 1.0.1, etc…
  • …and one branch for each version, that will be the development branch for each, thus for instance:

    • branch “dev-1.0”
    • branch “dev-1.0.1”
    • branch “dev-1.1”

Those latter branches are the ones being tested by Travis, with the Travis config files pointing at the different schemas for validation, and the extra checks potentially also version-dependent (maybe we enforce more things as versions evolve, in addition to the pure XML validation).

As part of the Travis-CI run, validated commits are automatically pushed to the non-dev branch for that version. Thus any commit valid in “dev-1.0” goes into “1.0”, any commit valid in “dev-1.0.1” goes into “1.0.1”, etc… And for the current stable version, also pushed to “master”. So for now, any commit valid in “dev-1.0” goes into “master” as well.

The workflows are then very straightforward:

  • The bulk of the style tweaks and additions is done on the current stable version of CSL, e.g. soon “dev-1.0-1”
  • Work on future versions for styles are done in the corresponding branches, e.g. “dev-1.1”
  • Put older versions on maintenance mode, and keep them consistent with current version during a transition period
  • Clients can pull from the non-dev branches of their choice, e.g. maybe pull from “1.0”, or from “1.0.1” if they are ready

In this context, assuming for instance that 1.0.1 has become the current stable version (soon!), we can do all the following things:

  1. work on the current dev branch “dev-1.0.1”, where most of the modifications are supposed to take place, including merging pull requests; fix errors after the fact when reported by Travis-CI

  2. work on future versions on “dev-1.1”, including pull requests; fix errors after the fact when reported by Travis-CI

  3. on a regular basis, merge changes from “dev-1.0.1” into “dev-1.1” so style tweaks are properly applied to the future styles as well; this requires to manually check that we are not overriding elements or properties that take advantage of the new version; deprecated stuff, or bigger schema changes would also be caught by the Travis validation

  4. on a regular basis, but only during the transition, also merge changes from “dev-1.0.1” back into “dev-1.0”, so style tweaks are applied to older versions; note that this process does not need to be manually checked, since any incompatible feature will be flagged by Travis and can then be corrected before it gets into the “1.0” branch

  5. pull requests on older styles can be accepted into “dev-1.0”, but we never merge 1.0 into 1.0.1 (the situation is different from point 3 above); fix errors after the fact when reported by Travis-CI; such direct changes should be the exception, because it’s likely that any tweaks to the 1.0 style should also apply to 1.0.1

I think it’s the best way to take full advantage of the set up with Travis CI. IMO, the tricky part is point (3), because it’s possible to inadvertently remove an element or property taking advantage of a new feature. It should be very straightforward for the 1.0 to 1.0.1 transition. However, the transition from 1.0.1 to 1.1 might be trickier, as the structure of the CSL could have significant changes, enough to break things more often. But no matter what we do, it’s going to be tricky to maintain styles that take advantage of new features, and at the same time merging the everyday changes we make to those styles. The merging strategy may or may not be the best way to achieve that, but having a separate branch will always help.

Those were my 2 cents :slight_smile:

charles

Not following this closely ATM, but do we really want to have branches for
every minor release (like 1.01)? I think not.

Yes we do.

Rintze

I think a separate branch would be useful. But Bruce, I think the question is also how to manage the transition.

In the case of Papers, it will honestly be very easy, as the current CSL engine will just work and ignore unknown attributes or elements. But for other clients, having a separate branch is the only way to provide a transition path, no?

charles

Then call it 1.1.

Charles: I think you’re exactly right. Perhaps this suggests the spec
should say something about this, and we ought to avoid the potential
situation of having a plethora of named branches in a few years, which
would be bad for everyone: developers, users, style maintainers.