How to Publish Open-Source Code


Once upon a time there was a man. A small business owner man. A small man who owned a business. He was moving on up. His name was George Jefferson. And he was small man who danced.

In addition to dancing and purchasing dry cleaners throughout the New York City area, George like to make video games.

A couple of months ago I refactored some code and out popped a little animation helper.

What was I gonna do with it?

var canvas = document.querySelector("canvas");
var loop = RunLoop(canvas, function(context, tick) {
  context.fillStyle = "hsla(5,90%,40%,1.0)";
  context.fillRect(Math.sin(tick/5)*20 + 100, 20, 40, 40);
});
canvas.addEventListener("mouseover", loop.play);
canvas.addEventListener("mouseout", loop.pause);

I decided that I needed to share this code with the world, instead of having it float around in an old project on my filesystem.

I ruled out a Gist or a JSFiddle beacuse I wanted it to be better packaged for distribution.

So I made a repository on GitHub.

$ curl -u 'williamcotton' https://api.github.com/user/repos -d '{"name":"RunLoop"}'

Since I wanted to instill a sense of stability and reliability with my code, I decided that I needed to write some tests, but first I had to learn Jasmine.

it("should make a context from a canvas", function() {

  runs(function() {
    RunLoop(canvas, function(ctx, tick) {
      expect(ctx).toBeDefined();
    }).play();
  });

});

Then I needed to learn how run those tests. And because Karma and PhantomJS looked like the best way, I needed to install node.js.

But then I had a thing or two to learn about npm...

{
  "name": "RunLoop",
  "version": "0.1.0",
  "devDependencies": {
    "karma": "*",
    "phantomjs": "*"
  },
  "scripts": {
     "test": "./node_modules/.bin/karma start --single-run --browsers PhantomJS"
  }
}
  

...before I could even think about installing my dependencies.

$ npm install

I then had to learn how to make a Karma configuration file that works with RequireJS and finally I could run my tests.

$ karma start

Oh, I had to learn how to connect Karma to Travis CI so I could get my little badge of reliability.

I wanted my code to be easily understood by others so I had to learn how to make README for GitHub in Markdown. I also made some wiki pages and made a demonstration of the code in use.

A very lightweight animation engine.
---

### Install
```bash
bower install RunLoop
```
### Barebones Example
```javascript
RunLoop(document.querySelector("canvas"), function(context, tick) {
  context.fillRect(Math.sin(tick/5)*20 + 100, 20, 40, 40);
}).play();
```

Because I wanted to make it easy for other people to use my code, I wanted to use bower. I learned how to write a package definition and register the package.

{
  "name": "RunLoop",
  "version": "0.8.0",
  "main": "RunLoop.js"
}

$ bower register RunLoop https://github.com/williamcotton/RunLoop.git

At the end of the day, I was left with a directory full of configuration files, dependencies, and instructions. That is, I had found myself with a lot of extra baggage.

.git/
.gitignore
.travis.yml
README.md
RunLoop.js
bower.json
karma.conf.js
node_modules/
package.json
test/

I had spent hours and hours learning a handful of new tools.

Even with these new skills I realized that it was still going to be a lot of work to do this again the next time I wanted to share some code.

All that I really wanted to do was share my code with the world, instill a sense of stability and reliability, have it be easily understood, and to make it easy for other people to use.

George Jefferson was angry and when he gets angry, he takes it out on the help.

It's a good thing that I was already familiar with git, bash, the Terminal, Homebrew, my editor, installing XCode, and probably a dozen or so other things I take for granted, because imagine the learning curve if I was a new developer who had to learn all of this stuff from scratch!

Let's not forget the HTML, Javascript, and CSS that actually make up the code itself that I was trying to publish.

Something had to be done about this!

What if you could publish your code right from your editor? Any editor?

lit({"name":"RunLoop"}, [], function() {
  
  var RunLoop = function(context_or_canvas, callback) {
    // ...
  });
  
  return RunLoop;

});

What if you could very easily use it anywhere, even on third-party sites like JSFiddle, Neocities, or JunoJS?

lit(["williamcotton/RunLoop"], function(RunLoop) {

  RunLoop(document.querySelector("canvas"), function(context, tick) {
    context.fillStyle = "green";
    context.fillRect(Math.sin(tick/5)*20 + 100, 20, 40, 40);
  }).play();

});

What if you had to keep scrolling down in order to learn more about what I'm talking about?

Introducing