thoughts on "style editor" team role and repo maintenance

So basic idea behind the style editor team role is these are users who
have authority to write (say by pulling from other repos) changes to
the main csl repo. Ideally, I’d like 10 or so good people, from a
variety of projects.

I think to do that well, we need two things:

  1. obviously some technical competence on the part of the team members

  2. a common standard to assess patches from potentially disparate
    sources (Mendeley, Zotero, pandoc/citeproc, etc.). I think to do this,
    in general (including for a nice GUI web app), we need standard input
    data, and some way to easily diff the output results in preview.
    Perhaps this could be achieved using a simple little JS app that uses
    some standard JSON input data and builds on Frank’s code?

Bruce

Two things related to this, which essentially boil down to "how to
replace and extend feature at zotero.org/styles."

First, Rintze and I were working on a little detail off-list, which is
figuring out how to deal with the csl:updated value in styles in the
context of a DVCS.

In SVN/CSL, you might do this sort of thing with keyword expansion,
but this doesn’t really make sense in a DVCS for a variety of reasons.
At the same time, it doesn’t really make sense to make people manually
update these values: for the person doing it, it’s a hassle certainly,
but it’s also conceptually problematic because you’re tracking content
that really should be maintained by the VCS.

So, Rintze came across some information about workarounds in git:

http://progit.org/book/ch7-2.html

… and I figured out something basic, which is how to get git to
return the last modified date for a file, in iso date-time format:

$ git log --date=iso --pretty=format:"%ad" -1 style.csl
2010-12-18 20:06:10 -0500

The second point is the related preview and diff issue.

With the VCS, we can know the change history of a style: when changes
were applied, and what they were. So we can use that to visually
compare output results of patches. I think I conclude the best way to
do this is to able to use something like the preview code in the csl
editor in conjunction with some sort of HTML diff library that shows
how CSL changes are impacting output results.

Bruce

Another random thought:

GitHub actually has a pretty nice UI for forking and pulling code
changes. What it doesn’t have is any dedicated way to visualize
changes with CSL styles.

I wonder if, as the simplest possible approach that could work now,
with no infrastructure, it’d be feasible to write a little
bookmarklet* that allowed one to click on it when on a pull request
page, and have it drop down the rendered preview diff?

So the workflow for style editor teams would be:

  1. click on pull request to view changes and comments**
  2. click “preview changes” bookmarklet to check if they make sense; if
    no, add comment; if yes
  3. pull changes

Bruce

OTOH, it’s simple enough, and the API rich enough*, that it shouldn’t
be hard to recreate.

Bruce

Hello,

So basic idea behind the style editor team role is these are users who
have authority to write (say by pulling from other repos) changes to
the main csl repo. Ideally, I’d like 10 or so good people, from a
variety of projects.

I think to do that well, we need two things:

  1. obviously some technical competence on the part of the team members

  2. a common standard to assess patches from potentially disparate
    sources (Mendeley, Zotero, pandoc/citeproc, etc.). I think to do this,
    in general (including for a nice GUI web app), we need standard input
    data, and some way to easily diff the output results in preview.
    Perhaps this could be achieved using a simple little JS app that uses
    some standard JSON input data and builds on Frank’s code?

Two things related to this, which essentially boil down to "how to
replace and extend feature at zotero.org/styles."

First, Rintze and I were working on a little detail off-list, which is
figuring out how to deal with the csl:updated value in styles in the
context of a DVCS.

In SVN/CSL, you might do this sort of thing with keyword expansion,
but this doesn’t really make sense in a DVCS for a variety of reasons.
At the same time, it doesn’t really make sense to make people manually
update these values: for the person doing it, it’s a hassle certainly,
but it’s also conceptually problematic because you’re tracking content
that really should be maintained by the VCS.

So, Rintze came across some information about workarounds in git:

http://stackoverflow.com/questions/2316677/can-git-automatically-switch-between-spaces-and-tabs

http://progit.org/book/ch7-2.html

http://stackoverflow.com/questions/2315771/writing-a-git-hook-to-automatically-modify-code-during-local-commits

… and I figured out something basic, which is how to get git to
return the last modified date for a file, in iso date-time format:

$ git log --date=iso --pretty=format:"%ad" -1 style.csl
2010-12-18 20:06:10 -0500

The second point is the related preview and diff issue.

that nice for the updated, I liked.
Do we want to run the hooks in server side, right? Github does support it?
(if it’s client side we will need some way to enforce the clients to
setup the hooks)

Have you thought about the id and how to handle it in different
branches of the same style?
I think that we talked about it but we didn’t have a final solution.

I hadn’t gotten to the details, given that I’ve yet to see anyone (say
from Mendeley, or Zotero) sign up for the org team, or commit a change
:wink:

I guess I’d probably lean towards adopting an approach consistent with
git/github. So I would expect, for example, that a style that in that
system is …

citation-style-language/styles/apa.csl

… might, if forked, become:

jdoe/styles/apa.csl

But OTOH, this is also similar to the updated issue in that it might
be odd to be messing with the id. I guess we’re going to have to think
about this more and consider exactly what we need to achieve (most
importantly is probably just knowing when two files are the same
style).

Bruce

Hi,

Have you thought about the id and how to handle it in different
branches of the same style?
I think that we talked about it but we didn’t have a final solution.

I hadn’t gotten to the details, given that I’ve yet to see anyone (say
from Mendeley, or Zotero) sign up for the org team, or commit a change
:wink:

I’ll fix it soon :slight_smile:

I guess I’d probably lean towards adopting an approach consistent with
git/github. So I would expect, for example, that a style that in that
system is …

citation-style-language/styles/apa.csl

… might, if forked, become:

jdoe/styles/apa.csl

But OTOH, this is also similar to the updated issue in that it might
be odd to be messing with the id. I guess we’re going to have to think
about this more and consider exactly what we need to achieve (most
importantly is probably just knowing when two files are the same
style).

Also important: what is the same style.

And how to handle pull requests/merges from forked styles.

As I think that I said before here, let’s say that I fork apa.csl
because I want to change something. Then my colleagues starts using
cpina/styles/apa.csl. So far, so good.

Then, the committee decides to pull my changes because it’s “approved”.

In that point, me and my colleagues will be still using
cpina/styles/apa.csl but should use apa.csl.

I’m not sure how to handle this case. Any ideas?

Hi,

Have you thought about the id and how to handle it in different
branches of the same style?
I think that we talked about it but we didn’t have a final solution.

I hadn’t gotten to the details, given that I’ve yet to see anyone (say
from Mendeley, or Zotero) sign up for the org team, or commit a change
:wink:

I’ll fix it soon :slight_smile:

I guess I’d probably lean towards adopting an approach consistent with
git/github. So I would expect, for example, that a style that in that
system is …

citation-style-language/styles/apa.csl

… might, if forked, become:

jdoe/styles/apa.csl

But OTOH, this is also similar to the updated issue in that it might
be odd to be messing with the id. I guess we’re going to have to think
about this more and consider exactly what we need to achieve (most
importantly is probably just knowing when two files are the same
style).

Also important: what is the same style.

And how to handle pull requests/merges from forked styles.

As I think that I said before here, let’s say that I fork apa.csl
because I want to change something. Then my colleagues starts using
cpina/styles/apa.csl. So far, so good.

Then, the committee decides to pull my changes because it’s “approved”.

In that point, me and my colleagues will be still using
cpina/styles/apa.csl but should use apa.csl.

I’m not sure how to handle this case. Any ideas?

So ideally, we really need the client software to have some concept of
a fork and merge.

From the git perspective, the github api exposes network information.
An example of a fork (the schacon/grit repo of the mojombo/grit
source) from their docs (I assume git itself stores similar info, but
am not sure):

$ curl http://github.com/api/v2/json/repos/show/schacon/grit
{
“repository”: {
“url”: “https://github.com/schacon/grit”,
“has_issues”: true,
“homepage”: “http://grit.rubyforge.org/”,
“watchers”: 106,
“source”: “mojombo/grit”,
“parent”: “mojombo/grit”,
“has_downloads”: true,
“created_at”: “2008/04/18 16:14:24 -0700”,
“forks”: 11,
“fork”: true,
“has_wiki”: true,
“private”: false,
“pushed_at”: “2010/05/05 15:28:38 -0700”,
“name”: “grit”,
“description”: “Grit is a Ruby library for extracting information
from a git repository in an object oriented manner - this fork tries
to intergrate as much pure-ruby functionality as possible”,
“owner”: “schacon”,
“open_issues”: 0
}
}

Bruce

I just tested this with a fork repo I have, and from what I can tell
(looking through the contents of the .git directory), it does not
store information about the source of the fork.

Bruce