Styles and locales as Java jar in Maven Central

CSL Development
1

Hi folks,

This message is a follow-up to my pull request:

I’m currently working on a project called citeproc-java. It’s a wrapper
around citeproc-js with a little extra stuff. You can find the draft
documentation of the yet unfinished library here:
http://michel-kraemer.github.io/citeproc-java/

In my pull request I was asking to include a pom.xml file to be able to
upload the styles and locales as jar files to Maven Central. So I could
use them in citeproc-java as regular Maven dependencies.

I understand that the CC BY-SA 3.0 license generally allows me to
distribute the files myself. However I first wanted to get your feedback
on this. In particular I wanted to ask if I should upload the files to
Maven Central using my existing user id (which would be a matter of a
couple of minutes) or if citationstyles.org has already got its own one.
Basically there are three ways to go:

  • I can upload the files under my own group id “de.undercouch”
    or “de.fhg.igd” with an artifact id of
    “citation-style-language-styles” or something like this
    (I don’t prefer this way)
  • I ask the Maven Central guys to assign the group id
    “org.citationstyles” to my user id, so I would be the
    maintainer and can upload files whenever I want (this would
    be the easiest one for me, but here I need your permission.
    Of course it’s always possible to add more maintainers in
    the future)
  • Someone of you already is the maintainer of this group id
    or volunteers to become one. (this may be the preferred
    option for you, but updating the files in Maven Central
    might also mean more work for you)

As I said, I’m absolutely OK with being the maintainer of
org.citationstyles in Maven Central, if this is also OK for you. I will
regularly update the files there. Of course the pom.xml files will
contain the correct license information and a link back to the project.
I even created a small Gradle script that adds all contributors from the
.csl files to the pom.xml file:
https://github.com/michel-kraemer/styles/blob/gradle/build.gradle

What do you think?

Cheers,
Michel

2

Awesome effort Michel!

My first thought is to take you up on your offer setup and maintain
the org.citationstyles group (which doesn’t exist, since nobody here
does Java).

Any objections out there?

3

Awesome effort Michel!

Agreed. Great documentation, too, for such a young project!

My first thought is to take you up on your offer setup and maintain
the org.citationstyles group (which doesn’t exist, since nobody here
does Java).

Any objections out there?

We had a bit of a discussion at
Added pom.xml to distribute the CSL styles via Maven by michel-kraemer · Pull Request #690 · citation-style-language/styles · GitHub on whether
it would be a good idea to add a pom.xml file to the official style
repo, or whether it would be better if Michel added one to his own
fork. I’m not familiar with the Maven workflow, though, so I’m not
really sure what the different options entail.

Michel, is Datum Edge: Publishing from GitHub to Maven Central
still true? This seems to suggest that it requires a server running
either a service hook
(About webhooks - GitHub Docs) or cron job to
keep the copy of the styles repository on Maven Central up to date
with GitHub. Things could be manually updated as well, but the styles
repository is ever-evolving, and your downstream users might expect
changes to the GitHub styles repo to end up in Maven in a timely
manner. How do you envision this?

As for your listed options, I think (2) would probably be the best, as
long as you include one or two of us as maintainers so we can manage
the project if you ever happen to abandon it for whatever reason.

Rintze

4

as I said in the original discussion, I also like version 2, i.e. the
org.citationstyles maintained by you. With yes from Bruce, Rintze, and me I
think you can go ahead with this.

Rintze is probably right that it would be a good idea to add two of us -
probably him and me as we’re currently most active in repo maintenance - as
maintainers for contingencies, though we won’t actually do anything unless
you need us to ;). But I certainly wouldn’t insist - just seems to make
sense.

Obviously pulling updates automatically would be best, but while, sure, the
repository changes quite a bit,if you pull in changes manually once every
couple of week you’d still be fine. In either case it’d be good to know
what you end up deciding in case someone asks us about updates on the maven
repo.

And, like Bruce - congratulations, this looks great! Welcome to CSL. Let us
know when you think this is done enough to list it as an implementation on

Is there any specific use case you’re setting this up for?

Sebastian

5

Hi!

Thank you very much for your positive answers. Seems to be a really
great community!

So, as everybody seems to agree, I will go for option 2. I will create a
org.citationstyles group at Maven Central. In the meantime, everyone who
wants to become a maintainer too should create a username at
https://issues.sonatype.org/. Please send me your username and I will
add you to the list of maintainers. (I hope I can do this myself. Let’s
see … J)

Michel, is Datum Edge: Publishing from GitHub to Maven Central
still true?

This is generally valid. However, as you can see, there are some
variables that need to be filled in. The most important one is the
password to a GPG key store. This is related to the fact that artifacts
have to be GPG signed before they can be uploaded. You need a key store
and a password for this. Apart from that, you need a password for the
Sonatype OSS. You really shouldn’t put that into GitHub :slight_smile: So a manual
step is unavoidable and automatically uploading artifacts with a Git
hook won’t work.

For everone who’s interested, there is a guide on how to correctly
upload artifacts to Maven Central:
https://docs.sonatype.org/display/Repository/Sonatype+OSS+Maven+Repository+Usage+Guide

repository is ever-evolving, and your downstream users might expect
changes to the GitHub styles repo to end up in Maven in a timely
manner. How do you envision this?

You usually only publish releases to Maven Central. There’s a special
area for snapshots that can be uploaded on a day-to-day basis or every
week or so, but AFAIK they will be deleted after some time (I’m not
quite sure about this).

I will try to upload changes from time to time, but I would suggest to
think about a better versioning scheme, because once an artifact is
released under a specific version it should not be changed anymore
(unless you want to break clients that use it). Something like
1.0.1.DATE (i.e. 1.0.1.20130910) would work, for example. But I guess it
would be better to create “real” releases from time to time (1.1, 1.2,
2.0, etc.).

Rintze is probably right that it would be a good idea to add two of us -
probably him and me as we’re currently most active in repo maintenance - as
maintainers for contingencies, though we won’t actually do anything unless
you need us to ;). But I certainly wouldn’t insist - just seems to make
sense.

Of course, I will do that. Please sign up to the Sonatype issue tracker
and send me your usernames.

And, like Bruce - congratulations, this looks great! Welcome to CSL. Let us
know when you think this is done enough to list it as an implementation on
citationstyles.org

Thanks a lot!!

Is there any specific use case you’re setting this up for?

I’m working on my PhD thesis, so yes :slight_smile:

Agreed. Great documentation, too, for such a young project!

Thanks a lot, I’m currently on vacation, so I have some free time :slight_smile:

Cheers,
Michel

6

…

I will try to upload changes from time to time, but I would suggest to
think about a better versioning scheme, because once an artifact is
released under a specific version it should not be changed anymore
(unless you want to break clients that use it). Something like
1.0.1.DATE (i.e. 1.0.1.20130910) would work, for example. But I guess it
would be better to create “real” releases from time to time (1.1, 1.2,
2.0, etc.).

Although, it may be worth reminding ourselves that CSL (and git) is
designed to be distributed, which rather conflicts with the notion of
a centralized, versioned, repository.

…

Bruce

7

Just some background: we currently always validate the “master” branch
of the style repository against the latest release of the CSL schema.
Upon a new release, we create a new branch for the previous version
(e.g. I created a “1.0” branch when we released CSL 1.0.1), and update
styles in the “master” branch as necessary to validate against the new
schema. In practice, we only ever get contributions for the "master"
branch.

To avoid confusion among your users, I’d strongly suggest avoiding a
versioning scheme that looks like a CSL version number, but isn’t one
(as would be the case with a “1.1”, “1.2”, … scheme). I like the
1.0.1.DATE much better.

Rintze

8

Hi!

As far as I understand your message you have two levels of versioning.
Maven has the concept of releases and snapshots. So, when you release a
new version of the CSL from time to time and you create a branch (or
tag) in the style repository, there should also be a new release to
Maven central with a version number such as 1.0, 1.1, or whatever.
Snapshots, however, can be based on the master branch and can be
uploaded daily or weekly or something like that. Please have a look here
for a description how snapshots work:

As you can see a snapshot’s version number is usually the next release
version plus “-SNAPSHOT”. Of course, snapshots are volatile and can be
changed at any time (even the name/version can change).

However, the good thing about this is that users have access to the
latest updates in the master branch almost immediately through snapshots
and if they need something more stable they will have the releases.

I’ve done a little research and it seems you don’t have to GPG sign
shapshots when you upload them to Maven Central. This means that we can
install something like Jenkins/Hudson to automate publishing snapshots
every night or every week or so (we should agree on something). I can do
this on my server if you like. A Git hook still won’t work because you
need the user credentials saved somewhere.

What do you think? Releases plus snapshots? What versioning scheme would
you prefer for both of them?

Cheers,
Michel

9

As far as I understand your message you have two levels of versioning.
Maven has the concept of releases and snapshots. So, when you release a
new version of the CSL from time to time and you create a branch (or
tag) in the style repository, there should also be a new release to
Maven central with a version number such as 1.0, 1.1, or whatever.
Snapshots, however, can be based on the master branch and can be
uploaded daily or weekly or something like that. Please have a look here
for a description how snapshots work:
java - What exactly is a Maven Snapshot and why do we need it? - Stack Overflow

As you can see a snapshot’s version number is usually the next release
version plus “-SNAPSHOT”.

I convinced you that “1.0.2-SNAPSHOT” would be a confusing name for a
current copy of the “master” branch of the styles repository, right?
Because we don’t accept styles in the “master” branch that use
unreleased CSL features, and all accepted styles must validate against
the released CSL 1.0.1 schema. There is no CSL development going on in
the styles repository.

What do you think? Releases plus snapshots? What versioning scheme would
you prefer for both of them?

Is there any significant drawback to only having snapshots? How about
only having a “1.0.1-SNAPSHOT” for now. You can then turn that into a
“1.0.1” release once we release CSL 1.0.2 and we switch to accepting
CSL 1.0.2 styles in our “master” branch. You can then create a new
“1.0.2-SNAPSHOT” into which you start pulling new updates to the
“master” branch.

Rintze

10

Is there any significant drawback to only having snapshots? How about
only having a “1.0.1-SNAPSHOT” for now.

Sounds great. I would create a 1.0 release for the 1.0 branch in GitHub
and a 1.0.1-SNAPSHOT that is updated daily or weekly or so. Later when
1.0.2 has been released we can create a 1.0.1 release and a
1.0.2-SNAPSHOT. Sounds reasonable to me.

Michel

11

It would be good to provide guidance to JAR users indicating that the
snapshot is usually the best version to use, since a so-called release
happens only upon revision of the specification.

12

Yes, although with my proposed scheme there would always be a snapshot
of a higher version than any of the releases, so it would be clear
that the snapshot would be the “tip”.

Rintze

13

Yes, although with my proposed scheme there would always be a snapshot
of a higher version than any of the releases, so it would be clear
that the snapshot would be the “tip”.

I totally agree.

@all: should I do it like this now?

Michel

14

Any objections? Otherwise I would upload the files as suggested by Rintze.

Cheers,
Michel

15

I’m busy, so lost the thread. But if you, Rintze, and Sebastian agree,
that’s fine by me.

16

Go ahead, Michel. Alles klar.

Rintze

17

OK. Done.

Snapshots (1.0.1-SNAPSHOT) are now available at
https://oss.sonatype.org/content/groups/public/org/citationstyles/

A “release” (1.0) is available at
http://central.maven.org/maven2/org/citationstyles/

The snapshots will be updated automatically through a cron job running
on my server every night (02:30 CEST). I don’t know how long the daily
snapshots will stay on the server. Let’s see what happens.

Just for the record: currently Rintze and I have access to the
repository. If you want to create a snapshot yourself, clone my GitHub
fork and checkout the branch “gradle”. Then run ‘./gradlew upload’. You
need a Sonatype username and password which you have to provide through
the environment variables sonatypeUsername and sonatypePassword.
Currently, only Rintze and I have such an account.

Cheers,
Michel