model for style repository changes?

CSL Development
1

I was just playing around with Google Maps for some teaching purposes
entirely unrelated to our work here, but in the process, came across
something interesting. Here’s a screenshot:
[image: Picture 17.png]

So the idea here is that individual users can edit the map data. But the
edits are separated between “my edits” (the user changes) and “community
edits” (the ones approved for addition to the general database). The former
then get cued for approval (which is an obvious bottleneck here; tons of
stuff pending).

It strikes me this is really consistent with my thoughts about the CSL
repository. The main differences would be in how we visualize the changes. I
could imagine a standard set of metadata, and the changes would be rendered
on the finished references and citations.

Bruce

2

If you had problems viewing this, you can see it here:

http://img262.imageshack.us/img262/7969/80908691.png

Bruce

3

Hello,

I’m/we are trying to think how Mendeley users (or any application that
uses CSL and a style editor) can interact with the style repository
and how, to try to keep the things centralized and so on. This is
connected to your initial idea of community edits.

I’ll comment a use case, we can model from here on. It’s not what I’ve
done, it’s just what I thought that I could do.

1.- The application has the style “styleId”. The user wants to edit it
to improve the style.
2.- The user presses “Edit” to edit the style and the style editor
appears with the style.
3.- The user makes some changes (and writes a “commit” message)
4.- Press "Save"
5.- ??

In step 5: what do you think that should happen? This is like a
community edit. I can think, just brainstorming:

  • The new style is sent to some PHP script that will fork the base
    style in the repository. Somebody will look into that and maybe merge
    with the base style.
  • Changes to the main style: I discourage it

-not a really long brainstorming-

And, after pressing “Save”: which styleId should have the new style?
like the old one and a suffix using the user-name? (e.g.
styleId-Carles1)

If another user asks for the new styleId-Carles1 in
www.citationstyles.org, will citationstyles.org send it back? (it
should do, so the users can share the styles). But then, there is a
problem when it’s merged: the development will happen in styleId and
not in styleId-Carles1 so the users needs to change to styleId. Unless
we start sending styleId when a user requests for styleId-Carles1 but
changing the styleId on the fly? (I think that this is getting messy).

Another use case is to get a styleId and then create styleId2 (for a
different journal). Comments on that are welcomed too, else I’ll write
about it soon.

Ideas for this workflow?
I’m also trying to think some other application in some field that
works like this but I don’t have any example.

Thanks,

4

Hello,

I’m/we are trying to think how Mendeley users (or any application that
uses CSL and a style editor) can interact with the style repository
and how, to try to keep the things centralized and so on. This is
connected to your initial idea of community edits.

I’ll comment a use case, we can model from here on. It’s not what I’ve
done, it’s just what I thought that I could do.

1.- The application has the style “styleId”. The user wants to edit it
to improve the style.
2.- The user presses “Edit” to edit the style and the style editor
appears with the style.
3.- The user makes some changes (and writes a “commit” message)
4.- Press “Save”
5.- ??

In step 5: what do you think that should happen? This is like a
community edit. I can think, just brainstorming:

  • The new style is sent to some PHP script that will fork the base
    style in the repository. Somebody will look into that and maybe merge
    with the base style.
  • Changes to the main style: I discourage it

-not a really long brainstorming-

And, after pressing “Save”: which styleId should have the new style?
like the old one and a suffix using the user-name? (e.g.
styleId-Carles1)

If another user asks for the new styleId-Carles1 in
www.citationstyles.org, will citationstyles.org send it back? (it
should do, so the users can share the styles). But then, there is a
problem when it’s merged: the development will happen in styleId and
not in styleId-Carles1 so the users needs to change to styleId. Unless
we start sending styleId when a user requests for styleId-Carles1 but
changing the styleId on the fly? (I think that this is getting messy).

Another use case is to get a styleId and then create styleId2 (for a
different journal). Comments on that are welcomed too, else I’ll write
about it soon.

For the past few years, I’ve been saying the interface really needs to
be wizard-based, and that early in that process, the user should be
prompted to base a new style on an existing style. Those that require
subsequent minor edits become standalone styles. Those that don’t
become dependent styles.

So I actually think this is a) the most important/common use case, and
b) fairly easy to resolve.

Ideas for this workflow?
I’m also trying to think some other application in some field that
works like this but I don’t have any example.

In general, my preference is to start with the simple and the social,
but leave room for the more complex case to develop as needed. So,
e.g., maybe we start with a basic repository running that allows
anyone to submit comments on a style page, and then we have 5-10 power
users of sorts (ones who know how to edit the raw CSL files) who can
create those changes. This would allow us to test this forking/merging
infrastructure you’re discussing above.

Even here I can see some oddities. Say you have a styles repo that is
a fork of mine. You make a minor changes in apa.csl and issue a pull
request, which I accept. If we change the id for each edit or editor,
then a big part of the change history for the repository will just be
id changes?

Bruce

5

Hello,

For the past few years, I’ve been saying the interface really needs to
be wizard-based, and that early in that process, the user should be
prompted to base a new style on an existing style. Those that require

I agree. Some time ago we had here some brainstorming on that.

subsequent minor edits become standalone styles. Those that don’t
become dependent styles.

To give some more context: I’m focusing now how to integrate the Style
Editor in $your_product, and how it’s connected with the main CSL
repository. My particular case is Mendeley, but I think that the
discussion is product agnostic.

Ideas for this workflow?
I’m also trying to think some other application in some field that
works like this but I don’t have any example.

In general, my preference is to start with the simple and the social,
but leave room for the more complex case to develop as needed. So,
e.g., maybe we start with a basic repository running that allows
anyone to submit comments on a style page, and then we have 5-10 power
users of sorts (ones who know how to edit the raw CSL files) who can
create those changes. This would allow us to test this forking/merging

I do understand what you say. But I’m thinking “around” the style
editor and how it fits in the ecosystem, not how to edit raw CSL
files. In particular, the typical cases like “I want X style but
instead of square brackets I want parenthesis” and similar small
changes and that the user is up to do it himself and now (and not to
go to a webpage to leave a comment).

I can see different use cases:
a) user wants to create a dependant style
b) user wants to fix some bug in some style
c) user wants to create a new style based in some existing style
d) user wants to create a new style from the scratch

Case by case:
a) user wants to create a dependant style: if the user edits a style
and only changes the metadata, the output of the style editor should
be a dependant style.

b) user wants to fix some bug in some style: the user would edit it
(with the style editor), mark as a bugfix, and write some commit
message. Somebody should review this change and if it’s accepted merge
to the main style. But, meanwhile, the user wants to use “his”
version. And maybe the user wants to share “his” version with
colleagues and collaborators, the plugins will fetch it automatically,
etc.

c) is similar to b, but instead of “merging” later on it will be
needed to be added.

d) similar to c), but the style editor would start blank instead of
with some things there.

For starting, and looking in the case b): which styleId should have
the temporary style? and which name? I say temporary style, but maybe
it’s never merged but still useful for this user for some reason. And
when it’s merged: citationstyles.org should keep serving the old
version or because has been merged should serve the last version of
the main style?

Even here I can see some oddities. Say you have a styles repo that is
a fork of mine. You make a minor changes in apa.csl and issue a pull
request, which I accept. If we change the id for each edit or editor,
then a big part of the change history for the repository will just be
id changes?

I think that everyone agrees that the style ID has to be as stable as
possible. Other thing is that I create my APA (apa-Carles) until it’s
pulled by the main style. The StyleId of the main style should not
change when pulls modifications.

6

Hello,

For the past few years, I’ve been saying the interface really needs to
be wizard-based, and that early in that process, the user should be
prompted to base a new style on an existing style. Those that require

I agree. Some time ago we had here some brainstorming on that.

subsequent minor edits become standalone styles. Those that don’t
become dependent styles.

To give some more context: I’m focusing now how to integrate the Style
Editor in $your_product, and how it’s connected with the main CSL
repository. My particular case is Mendeley, but I think that the
discussion is product agnostic.

Not exactly sure it is, and I remain very skeptical the approach you
guys are taking (focusing on the individual user and client side)
makes the best sense. I have serious worries it will end up being
counter-productive.

But I’ll leave that aside and see if we can just focus on the
“agnostic” aspects of this.

Ideas for this workflow?
I’m also trying to think some other application in some field that
works like this but I don’t have any example.

In general, my preference is to start with the simple and the social,
but leave room for the more complex case to develop as needed. So,
e.g., maybe we start with a basic repository running that allows
anyone to submit comments on a style page, and then we have 5-10 power
users of sorts (ones who know how to edit the raw CSL files) who can
create those changes. This would allow us to test this forking/merging

I do understand what you say. But I’m thinking “around” the style
editor and how it fits in the ecosystem, not how to edit raw CSL
files. In particular, the typical cases like “I want X style but
instead of square brackets I want parenthesis” and similar small
changes and that the user is up to do it himself and now (and not to
go to a webpage to leave a comment).

I can see different use cases:
a) user wants to create a dependant style
b) user wants to fix some bug in some style
c) user wants to create a new style based in some existing style
d) user wants to create a new style from the scratch

Case by case:
a) user wants to create a dependant style: if the user edits a style
and only changes the metadata, the output of the style editor should
be a dependant style.

Right.

b) user wants to fix some bug in some style: the user would edit it
(with the style editor), mark as a bugfix, and write some commit
message. Somebody should review this change and if it’s accepted merge
to the main style. But, meanwhile, the user wants to use “his”
version. And maybe the user wants to share “his” version with
colleagues and collaborators, the plugins will fetch it automatically,
etc.

I think sharing needs to be:

a) default (with strong barriers to opting out)

b) transparent (users need to know they’re contributing to a community
effort; goes back to a)

c) is similar to b, but instead of “merging” later on it will be
needed to be added.

d) similar to c), but the style editor would start blank instead of
with some things there.

Right, and also likely to be an incredibly uncommon use case. And note
that the current state of the editor assumes this as the primary use
case.

For starting, and looking in the case b): which styleId should have
the temporary style? and which name? I say temporary style, but maybe
it’s never merged but still useful for this user for some reason. And
when it’s merged: citationstyles.org should keep serving the old
version or because has been merged should serve the last version of
the main style?

Am in a bit of a hurry ATM, but wonder if we ought to ask this
question another way: if we assume git as the basis of the repository
model, how would one answer this question from git’s standpoint? I
fork and change a file in git: how does git establish its identity,
and the relationship between versions?

If you think this question is off-base, feel free to tell me. But I
thought it might give us some insight.

Even here I can see some oddities. Say you have a styles repo that is
a fork of mine. You make a minor changes in apa.csl and issue a pull
request, which I accept. If we change the id for each edit or editor,
then a big part of the change history for the repository will just be
id changes?

I think that everyone agrees that the style ID has to be as stable as
possible. Other thing is that I create my APA (apa-Carles) until it’s
pulled by the main style. The StyleId of the main style should not
change when pulls modifications.

Bruce

7

Hi,

I can see different use cases:
a) user wants to create a dependant style
b) user wants to fix some bug in some style
c) user wants to create a new style based in some existing style
d) user wants to create a new style from the scratch

b) user wants to fix some bug in some style: the user would edit it
(with the style editor), mark as a bugfix, and write some commit
message. Somebody should review this change and if it’s accepted merge
to the main style. But, meanwhile, the user wants to use “his”
version. And maybe the user wants to share “his” version with
colleagues and collaborators, the plugins will fetch it automatically,
etc.

I think sharing needs to be:

a) default (with strong barriers to opting out)

b) transparent (users need to know they’re contributing to a community
effort; goes back to a)

I think the same.

d) similar to c), but the style editor would start blank instead of
with some things there.

Right, and also likely to be an incredibly uncommon use case. And note
that the current state of the editor assumes this as the primary use
case.

I know, it needs lot of work in UI and UX. As it’s now it’s not useful.
I wrote the case d) just for completeness, I even thought to not write
about it now.

For starting, and looking in the case b): which styleId should have
the temporary style? and which name? I say temporary style, but maybe
it’s never merged but still useful for this user for some reason. And
when it’s merged: citationstyles.org should keep serving the old
version or because has been merged should serve the last version of
the main style?

Am in a bit of a hurry ATM, but wonder if we ought to ask this
question another way: if we assume git as the basis of the repository
model, how would one answer this question from git’s standpoint? I
fork and change a file in git: how does git establish its identity,
and the relationship between versions?

If you think this question is off-base, feel free to tell me. But I
thought it might give us some insight.

Sadly I’m not an advanced git user. Someone with more git experience
could comment on it?

Anyway, I try: identity is based on a sha1id of the commit. And each
git “commit” (identified by this sha1id) has a Parent commit (sha1
identified) and Child commit.

I have the feeling that technically I’m answering the question but
it’s helping to what you wanted to know. Maybe there is another
answer.

8

I started to add something on the git object model when your note came
through, so will add that below …

Hi,

I can see different use cases:
a) user wants to create a dependant style
b) user wants to fix some bug in some style
c) user wants to create a new style based in some existing style
d) user wants to create a new style from the scratch

b) user wants to fix some bug in some style: the user would edit it
(with the style editor), mark as a bugfix, and write some commit
message. Somebody should review this change and if it’s accepted merge
to the main style. But, meanwhile, the user wants to use “his”
version. And maybe the user wants to share “his” version with
colleagues and collaborators, the plugins will fetch it automatically,
etc.

I think sharing needs to be:

a) default (with strong barriers to opting out)

b) transparent (users need to know they’re contributing to a community
effort; goes back to a)

I think the same.

d) similar to c), but the style editor would start blank instead of
with some things there.

Right, and also likely to be an incredibly uncommon use case. And note
that the current state of the editor assumes this as the primary use
case.

I know, it needs lot of work in UI and UX. As it’s now it’s not useful.
I wrote the case d) just for completeness, I even thought to not write
about it now.

For starting, and looking in the case b): which styleId should have
the temporary style? and which name? I say temporary style, but maybe
it’s never merged but still useful for this user for some reason. And
when it’s merged: citationstyles.org should keep serving the old
version or because has been merged should serve the last version of
the main style?

Am in a bit of a hurry ATM, but wonder if we ought to ask this
question another way: if we assume git as the basis of the repository
model, how would one answer this question from git’s standpoint? I
fork and change a file in git: how does git establish its identity,
and the relationship between versions?

If you think this question is off-base, feel free to tell me. But I
thought it might give us some insight.

Sadly I’m not an advanced git user. Someone with more git experience
could comment on it?

Anyway, I try: identity is based on a sha1id of the commit. And each
git “commit” (identified by this sha1id) has a Parent commit (sha1
identified) and Child commit.

I have the feeling that technically I’m answering the question but
it’s helping to what you wanted to know. Maybe there is another
answer.

So a description of the object model is at:

http://book.git-scm.com/1_the_git_object_model.html

So from a git perspective, a CSL style would be a blob. The blob has a
sha1 hash. For example, I have a style with a sha1 of:

ef55dfaadeaf1bef297e5f7a4365dd348906bd96

I then make a trivial change in the style, and the new sha1 is:

105fc650926051178132f852927faeaaf74d470a

The git book then explains a commit as “points to a single tree,
marking it as what the project looked like at a certain point in time.
It contains meta-information about that point in time, such as a
timestamp, the author of the changes since the last commit, a pointer
to the previous commit(s), etc.”

OK, so what, if anything, can we do with this knowledge?

Bruce

9

probably the users will not use the repository straight away. So we
could take advantage of that having the styleId as a metadata of the
file, and when serving the style file to the application we (the PHP
script git wraper) could replace $styleId by “something” from the git
metadata.

Problem: I have no idea if it’s possible to attach arbitrary metadata
to a git file. Any experience?

It could fix some things here and there when merging different
versions of styles, or testing versions (like I want to use apa-Bruce
to compare with apa).

10

I started to add something on the git object model when your note came
through, so will add that below …

I have the feeling that technically I’m answering the question but
it’s helping to what you wanted to know. Maybe there is another
answer.

So a description of the object model is at:

http://book.git-scm.com/1_the_git_object_model.html

So from a git perspective, a CSL style would be a blob. The blob has a
sha1 hash. For example, I have a style with a sha1 of:

ef55dfaadeaf1bef297e5f7a4365dd348906bd96

I then make a trivial change in the style, and the new sha1 is:

105fc650926051178132f852927faeaaf74d470a

The git book then explains a commit as “points to a single tree,
marking it as what the project looked like at a certain point in time.
It contains meta-information about that point in time, such as a
timestamp, the author of the changes since the last commit, a pointer
to the previous commit(s), etc.”

OK, so what, if anything, can we do with this knowledge?

probably the users will not use the repository straight away. So we
could take advantage of that having the styleId as a metadata of the
file, and when serving the style file to the application we (the PHP
script git wraper) could replace $styleId by “something” from the git
metadata.

Problem: I have no idea if it’s possible to attach arbitrary metadata
to a git file. Any experience?

No, but google turns up “notes”:

http://kernel.org/pub/software/scm/git/docs/git-notes.html
http://progit.org/2010/08/25/notes.html
<Git Notes Display - The GitHub Blog

11

…

Problem: I have no idea if it’s possible to attach arbitrary metadata
to a git file. Any experience?

No, but google turns up “notes”:

http://kernel.org/pub/software/scm/git/docs/git-notes.html
http://progit.org/2010/08/25/notes.html
https://github.com/blog/707-git-notes-display

… although it’s not clear if you can attach notes to files per se.

Bruce