new styles repo at github

So long story short:

For awhile now I and others have been wanting to move styles currently
at zotero.org/styles to a more the project-agnostic
citationstyles.org.

In discussion in the CSL community, some of us came to the conclusion
that a distributed version control system would be a sensible
technical foundation on which to incrementally build a next generation
CSL distribution infrastructure. In part because of the mindshare of
git and github, I created a citation-style-language organization at
github.

http://github.com/citation-style-language

The org infrastructure of github simply makes it easier (in fact,
really easy) to define flexible permissions for org and repo
managment. So, for example, the first “Team” I created was for “Style
Editors.”

In turn, the first org repo is:

http://github.com/citation-style-language/styles

To create this repo, I just moved over 1.0 styles from the zotero
repository. I did this fairly quickly, when otherwise quite busy, so I
probably missed some. There are also some details to fix, like style
IDs, etc.

But more importantly, I want to get people to start using this. So the
next step is to actually get more people signed up for the
organization, as style editors and/or admins, and to start committing.
Is there something we can do to facilitate this?

Bruce

This looks great.

We are starting to get some users on Mendeley contributing corrections
to styles, specifically for the ACS journals. I’d like us to be able
to submit these as patches into the git repo. Is the current thinking
that we should submit through sending a patch to a signed up “style
editor”?

  • Ian

This looks great.

We are starting to get some users on Mendeley contributing corrections
to styles, specifically for the ACS journals. I’d like us to be able
to submit these as patches into the git repo. Is the current thinking
that we should submit through sending a patch to a signed up “style
editor”?

How about using the method of fork & pull request that is employed by many open source projects on github? This would make the process of incorporating patches for the editors much easier, I think.

Sylvester

PGP.sig (195 Bytes)

This is the idea.

So for Mendeley, two possible models:

  1. user submits to Mendeley, and a Mendeley CSL “style editor” just
    submits it directly to the repo

  2. more technically proficient user forks the CSL repo themselves,
    makes the change (on a branch), and issues a pull request

I just added a “develop” branch to the repo for changes we may not
ready to distribute widely initially.

Note also I setup the issue tracker.

https://github.com/citation-style-language/styles/issues

I’m happy to be pretty flexible about adding style editor team
members. So long as you prove yourself to be suitably
technically-proficient and careful, you’re in.

Bruce

BTW, if we do get this going, we are going to need a standard way to
quickly preview changes. Something built on citeproc-js; maybe a
little node.js commandline and/or web app?

Bruce

Hi Bruce,

Just as a followup, please feel to comment on this issue if you have any ideas:

https://github.com/citation-style-language/styles/issues#issue/2

I based CSL’s metadata on Atom; it’s pretty much a straight copy. For
that reason, the style id is a URI.

But if this no longer seems such a great idea given how the CSL world
has evolved, we can always look at changes or enhancements.

In any case, my main plea is that we try to realize the potential of a
collaboratively-developed, repo infrastructure.

Bruce

For some reason this keeps bouncing. Let’s try again.---------- Forwarded message ----------
From: Bruce D’Arcus <@Bruce_D_Arcus1>
Date: Tue, Mar 1, 2011 at 1:11 PM
Subject: Re: [xbiblio-devel] new styles repo at github
To: Robert Knight <@Robert_Knight>

On Tue, Mar 1, 2011 at 1:05 PM, Robert Knight <@Robert_Knight> wrote:

Hi Bruce,

On a slightly different note, are the URLs for styles on
citationstyles.org now stable?

I just added an issue for this today:

https://github.com/citation-style-language/styles/issues#issue/2

Mendeley Desktop has a system for
handling upgrades of styles (by querying a mendeley.com API for style
updates) which uses the URL of the style (the csl:id) as the
identifier for this purpose, so we’d need to be sure that these URLs
are likely to remain valid once we start including newly added or
updated styles from citationstyles.org in the repository exposed to
the client.

Right. How about using the github API itself for updating the styles?

Bruce

Right. How about using the github API itself for updating the styles?

Works for me, I just built a form (see attached) into my CiteProc
module which lists all the available styles from the github repo and
lets the user select which ones to install.

Ron.

Right. How about using the github API itself for updating the styles?

Works for me, I just built a form (see attached) into my CiteProc
module which lists all the available styles from the github repo and
lets the user select which ones to install.

So having worked with this (GitHub API) a bit, I can see that it does
have a few downsides… While it’s real easy to get a list of files
in the repository, the metadata for each file is limited (sha, name,
and mime type). It would be really nice if it returned create and
update timestamps so you could tell if the repo file is newer than the
local one, but I can’t see any way to get that information. It would
also be nice to be able to get the full title of the style without
having to download the entire CSL file.

Ron.

Yes, I was thinking that as well. I do know you can get this info from
git itself, but am not sure if it’s available through the API.

$ git log --date=iso --pretty=format:"%ad" -1 apa.csl

Bruce

That was a good hint, and in fact using the “Commits API” you can get
the time stamps, unfortunately there is another limitatin we will bump
into.

I just found this in the API docs…> On Sat, Mar 5, 2011 at 10:26 PM, Ron <@Ron_Jerome> wrote:

Right. How about using the github API itself for updating the styles?

Works for me, I just built a form (see attached) into my CiteProc
module which lists all the available styles from the github repo and
lets the user select which ones to install.

So having worked with this (GitHub API) a bit, I can see that it does
have a few downsides… While it’s real easy to get a list of files
in the repository, the metadata for each file is limited (sha, name,
and mime type). It would be really nice if it returned create and
update timestamps so you could tell if the repo file is newer than the
local one, but I can’t see any way to get that information. It would
also be nice to be able to get the full title of the style without
having to download the entire CSL file.

Yes, I was thinking that as well. I do know you can get this info from
git itself, but am not sure if it’s available through the API.

$ git log --date=iso --pretty=format:"%ad" -1 apa.csl

===========================================
Limitations

Currently we are limiting API calls to 60 per minute. This may change
in the future, or possibly per user at some point, but if you try to
access the API more than 60 times in a minute, it will start giving
you “access denied” errors.

===========================================

Given the number of style files there are in the repo, that’s going to
be a problem.

Ron.

Maybe you can more easily find out:

  • the time-stamp for the last commit
  • the files part of that commit

By stepping back like that, you could limit the requests? The styles
don’t change that frequently.

Looking again at the homebrew code …

https://github.com/mxcl/homebrew/blob/master/Library/Homebrew/update.rb

… they operate on the local git repository to pull in these sorts of
data (updated, outdated, etc.). I guess that’s conceptually similar to
what Mendeley is doing.

Bruce

Bruce