Getting and submitting FreeGeek code and assets

FreeGeek Chicago uses  Mercurial, a distributed version control system, and Bitbucket.org, a hosted code sharing system, to allow participants in our programs to get and submit code and assets related to FreeGeek.

Huh?

Basically, what this means is that we have a place on the web for anyone interested to get various kinds of stuff that we create -- from the code that drives our website to our logo and promotional materials. To get that stuff on your computer, you need a program called Mercurial.

Mercurial also provides a way of changing and submitting stuff back to FreeGeek.

Let's say the community decides the time has come for a new logo, and you, the intrepid volunteer, have been chosen to update the logo design. Someone at FreeGeek could send you the file via email and wait for you to email them back some file named my-logo-05-25-2010.svg, and then the person on staff could forward it to the staff and talk email lists, and people could make some comments, and then you'd send another email with my-logo-06-17-2010-dees-suggestions-3.svg... pretty soon, you are stuck in Gmail threading hell.

Or, you could check out the file from FreeGeek's repository, make your changes, and commit a new version. Want to make another change? Make another change -- just commit a new version. Wash, rinse, repeat. Once you've settled on a set of changes you like, push the changes back to the official FreeGeek repository. It sounds complicated, until you consider the alternatives. And when it works, it is pretty magical.

Let's look at how you get this stuff, how you share it, and how we all can talk about it via Bitbucket.

Using Mercurial to check out FreeGeek assets

Installing Mercurial

If you run Ubuntu, open a terminal and type:

# (~) sudo apt-get install mercurial

(Additional installation resources)

Getting stuff with Mercurial

Let's say you'd like to download our logo and other graphical assets. In the same terminal, type:

# (~) mkdir Repos
# (~) cd Repos
# (~/Repos) hg clone https://freegeekchicago.org/freegeekchicago-assets

Your terminal should reply:

destination directory: freegeekchicago-assets
requesting all changes
adding changesets
adding manifests
adding file changes

Now, let's take a peek inside:

# (~/Repos) cd freegeekchicago-assets
# (~/Repos/freegeekchicago-assets) ls

You should see something like:

total 24
drwxr-xr-x 2 user user 4096 2010-07-14 22:12 docs
drwxr-xr-x 2 user user 4096 2010-07-13 05:48 fliers
-rw-r--r-- 1 user user  470 2010-07-13 05:48 LICENSE
drwxr-xr-x 2 user user 4096 2010-09-11 21:11 logo
-rw-r--r-- 1 user user 1478 2010-07-13 05:48 README.rst
drwxr-xr-x 2 user user 4096 2010-07-13 05:48 signs

WHAT DOES THIS MEAN??? It means that the files in some repository out there (this one lives at  http://code.freegeekchicago.org/freegeekchicag-asset) have been copied to your computer, and you can now view and edit them to your heart's content.

Editing files

So it turns out that in 2013, a FreeGeek volunteer will wind up developing a new kind of genetically engineered goat which can eat old consumer electronics and separate the precious metals from the PCBs in its many stomachs. Don't ask me how I know. The upshot is that when Community Council voted on a new logo, they told you that you needed to integrate an image of our new responsible recycling goat with our old logo.

So, that isn't hard, you say to yourself. Fire up the gimp, a little cut and paste, and all will be better. Open up your file browser and navigate to the file:

SIDE-BY-SIDE NAUTILUS WINDOWS

Something about where file lives...

We won't go into the gory detail of how you did it -- after all, you're the expert -- but you managed to create a new version of the logo with our new goat:

Now that you have a new version, let's go back to the terminal. Make sure you are in the correct directory, then ask Mercurial for the status of your files:

# (~) cd ~/Repos/freegeekchicago-assets
# (~/Repos/freegeekchicago-assets) hg status
M logo/logo.svg

By running the hg status command, you've ask Mercurial to tell you what's changed in the repository. Mercurial dutifully lists files that have changed, added, removed, or remain untracked. In this case, the M means that logo.svg was modified, and you should do something about it. You should create a new revision.

# (~/Repos/freegeekchicago-assets) hg com -m "Added the goat to the logo."

What happened?!

# (~/Repos/freegeekchicago-assets) hg log

...log output...

You just committed your changes -- you made a new version.

Show push...

Direct reader to hginit for more.

Using Mercurial to check out a development version of the FreeGeek website

Assumes you dig it, a little. But even if you don't, you can get a dev version up and running...

Subrepos: a way of stitching together multiple repositories.

Why is this good? Mercurial's development model -- which emphasizes changesets, allows local commits,