Open Source Diary

The following is a stream-of-consciousness account of what I did in order to create the jsext library. It is essentially the notes for Creating a Scala.js Open Source Project.
While Querki per se is kinda-sorta proprietary (the specific license hasn't been chosen as of this writing, but it will have some restrictions), in the course of developing it I'm coming up with some pieces that really should be open source. That's what the querki.org domain is officially for: it will be the namespace for all of the open-source bits that come out of Querki.
That's a bit of a black art, so I'm recording a bit of stream of consciousness here, documenting how I go about refactoring the jsext library and JQuery facade out of the Querki source code into their own open-source libraries. Eventually, this should get rewritten into a proper tutorial.

Starting out

In Gitter, @sjrd recommended publishing to Maven Central instead of Bintray -- apparently, there are a fair number of folks who strongly prefer it. He pointed me to this guide, which details the process there. He also recommends using the Scala.js build.sbt file as a when-in-doubt example for what the sbt needs to look like. (And @Voltir recommends looking at @lihaoyi's libraries as examples, which also makes sense.)

Set things up at Sonatype

As described in the above-linked guide, I first created an account with Sonatype's JIRA, which was painless, and the logged in.
Next step, again according to the guide, was to open a ticket in JIRA to create a new project for org.querki.jsext. (We'll start with the center of the onion.)
  • I left the Description blank -- not obvious what ought to go in there.
  • The groupId seems to be "org.querki".
  • The Project URL is a sticky question. The implication here is that I need to have the project first, before I open the Sonatype ticket. So I can't just refactor it out later. Pause.

Copy the code into a new repo

I have a suspicion that there is an easier way to refactor this out, but for now let's do this slowly and carefully, so as not to break Querki development while I'm at it.
So instead, we'll create a new GitHub repo for the jsext project. Clone it to my dev machine, and simply copy the existing code into it, to bootstrap the sucker, so we have something to refer to. Sync back to GitHub, and put at least the very basic text into the README.md, including the license.

Back to Sonatype

Back to creating the ticket.
Submitted that, and was assigned a ticket. Got an email a couple of days later, saying that the ticket was resolved, giving the locations of the various deployment areas, and asking for a comment on the ticket when the first release comes out. LATER: done.
Reviewed the Requirements for a Sonatype project. Need to build a checklist out of these. LATER: actually, it turns out that most of this is pretty well covered by sbt, especially if you start from, eg, scala-js-jquery.
In the jsext/project directory, created a build.properties and build.sbt, adapted from scala-js-jquery, both quite simple.
In the main jsext directory, created a build.sbt, adapted from scala-js-jquery and The relevant sbt page. Set the version to 0.1-SNAPSHOT.
Added sbt-pgp to project/build.sbt, as detailed on this page.
Opened Activator for the first time in the jsext directory. Compiled. Got an eviction warning; upgraded to 2.11.6 to make that go away. publishLocal. Confirm that it shows up under ~/.ivy2.
Created a new branch of Querki. Remove the jsext code from there. Confirm that it fails to compile.
Add a libraryDependency on the SNAPSHOT version of jsext; refresh Activator and try again. Odd; still fails, even though the jsext dependency resolved. Try cleaning Querki. No -- still fails.
I'm not sure anything actually got published. Confirmed: the project under .ivy2 doesn't actually contain anything. Maybe "compile" doesn't hack it for a JS project? Back into jsext. Do fastOptJS, then fullOptJS. publishLocal again -- nope, still nothing.
Compared with scala-js-jquery. I have an extra level of indirection in my directory tree: I have jsext/src where it only has src. Remove the extra level, clean and recompile. Yeah, that appears to do more now. publishLocal again. Confirmed that the .ivy2 directory now has real content.
Back to Querki: reload Activator and recompile. Yep, now compiles and runs. Yay!
Okay, time to generate keypairs and sign. Back to jsext in Activator. Do pgp-cmd gen-key. Fails; do set pgpReadOnly := false and try again. Okay, better.
  • Set name associated with the project: Querki Inc.
  • Set email associated with the key: justin@querki.net
  • Enter passphrase: (generated from LastPass)
  • Re-enter passphrase: (ditto)
Copy the passphrase, and the generated pubring.asc and secring.asc, to a highly secure location. pgp-cmd send-key justin@querki.net hkp://pool.sks-keyservers.net to publish the public key to an accessible location. (Note that this last needs the name, email or hex key id of the key.)
Define a sonatype.sbt file, as described in the fourth section of this page. I don't love putting my credentials out like this, but it's apparently the convention.
Change the version to 0.1, reload Activator and recompile.
publishSigned to push the package to Sonatype. This will ask for the PGP passphrase saved away earlier.
Now over to the release process, as described here.
  • Go to the Sonatype homepage and Log In.
  • Click on Staging Repositories in the left-hand menu, find the orgquerki-1000 one, and click on that.
  • Go to the Content tab, and sanity-check the contents.
  • Press the Close button at the top, and enter a description.
  • Wait a bit, then Refresh once in a while until it shows as Closed.
  • Once that is done, press the Release button, enter a description, and go.
  • Wait a while -- eventually a Nexus: Promotion Completed email should show up.
Now, delete the locally-published copy from .ivy2. Confirm that Querki will not build because of the missing SNAPSHOT dependency. Change the dependency to the released version. That fails, because it can't find the dependency. Clean and try again. Nope, still fails. Weird and annoying. Maybe I'm just trying too fast? This page says it can take up to two hours.
Ah -- commenting on the original ticket, as requested, produces an additional comment that sync is now turned on for the project. So basically, the first release is delayed until I make that comment, and then the publishing process starts.
Waited another 15 minutes or so, then tried re-entering Activator and re-compiling Querki. It works! Yay!

Beginning to create the jquery-facade library

Created a GitHub repo for the project. Cloned it locally. Copied the library code into it.
Opened a new JIRA issue to create the project on Sonatype. Next day, received an email saying that this is unnecessary: you only need the JIRA issue the first time, to create the top-level group ID, and can simply add artifacts to it afterwards.