Ugh I am not going to start doing tl;dr stuff, but my intros seem to be long. I am going to invite you to try some simple github edits to a public site, come fork with me, ok?
I’ve had a GitHub account since 2010 (my guess was later, but found that on my profile). I have a pile of “stuff” there mostly my own projects, like the WordPress Theme for people to create their own version of the DS106 Daily Create or the code behind pechaflickr.net.
But I am far from being knowledgable about the ins and outs of GitHub. I don’t do any command line, I mostly sync with the desktop tool. I’ve only contributed bits to maybe 3 other projects that are not mine. And I’ve only had maybe 3 or 4 people submit any changes to my stuff. It’s lonely in there.
I have been more interested in getting some play with GitHub’s ability to generate web sites or Pages, so the entrance for your project can be something other than the repository view, which looks a bit daunting to the new to GitHub crowd. My best so far is for the flickr cc attribution helper:
It’s more than just static content, this is a tool site hosted on github, it lets you create different bookmarklet tools, and it even does the grunt work the bookmarklet tool needs to do to get information from flickr. All without a web server, or least not mine.
In fact, as I blogged it, I was not intending to create one, but I ended up making an extensible system, where other people could add a different functionality by forking and writing a new page. John Johnston added a stamper version of attribution and some guy named Glen made a version that generates CC attribution in Markdown.
Pretty good for someone not quite sure what happens with a pull.
Maybe I am not quite leveraging it. But in my new project with Creative Commons, there is something that would work well in a system where people could fork content, and either submit changes to the main site, or build their own variant versions. And I am not talking code here, but more or less our design document.
But it’s all daunting, the github screen.
There are “repos” and you “fork” things to edit or add and I as the admin of the “repo” have to accept the “pull” request and “merge” it. These become “commits”.
Is this as easy as as a home appendectomy?
So my question over the last day or two, how could I set up something to give non-programmers (well anyone can do it, but someone who knows github will giggle at the simplicity of this) a bit of GitHub editing experience (and so I could understand it too).
Thus I invite you to use GitHub to rewrite the song lyrics for the old classic, Home on the Range — chosen because it is Public Domain. I was inspired by this rewrite of Folsom Prison Blues tweeted by Ben Werdmüller
"I'm stuck in San Francisco
And time keeps dragging on"https://t.co/5X4R3zzns5
— Ben Werdmuller (@benwerd) April 2, 2016
which in fact is published in Github as a “gist” just a chunk of text (which cannot be forked or edited, it’s just meant as a way to share snippets of code or text).
I thought about using Folsom, but hey, copyright. So I first played with setting up a web page with Github pages, then realized I’m asking people to dig around in HTML. Why not give them a place to edit in a Markdown, where they just change text — just point them to the places to edit?
Enough talk, let’s get the fork out! Here is the front entrance:
This is really just to say “create and/or login to a github account”. Just because I needed to test this out, I created a separate test account https://github.com/auntysocial.
Okay, Aunysocial goes to the GitHub page I created in Markdown where the song lyrics roam:
Here’s where the language trips up. My Auntysocial account is looking at something created in my cogdog account, and if I click the pencil icon to edit, it will let me know I have to “fork” it to edit
It may seem like overkill, but to edit one line in this document, GitHub is making a copy, or forking, the entire project or repository or “repo” to my Aunty Social account. When I save, it sends back just the changes, not the whole ball of wax.
Now Auntysocial can edit their copy, maybe looking at line 41:
which I can do easily…
And when I save, I get a summary of my changes- github always tracks changes to each line in the file. Red marks lines I have deleted, and green show the additions I made- you see a lot of red and green in this place.
I could have done a lot of edits, and all would be shown in reds and greens, but I kept it simple. But my changes are just in my local copy- to send it back “home” I have to create a “pull” request. This might sound counterintuitive, you might think you are “pushing” a change, but you are asking the site owner to “pull” your changes in to theirs.
And what happens in GitHub is that programmers/writers explain what they are doing, so the comments make it clear to the person who manages the repo what you are hoping to do. The more you write, the better.
And I can see a summary of everything I (Auntysocial) has done:
As the editor/manager/cook/bottlewasher of the repo, I will get notification of a change submitted by Auntysocial, showing up as a “pull request”. I click the item…
What do you think I should do (green button! green button!)
I can review it, and if I have a problem with Auntysocial’s work, I can let them know via a comment, but since those edits look good I approve their edits by clicking Merge Pull Request, and thus I see it in my records… and this is now known as a “commit”
And the published version of the song lyrics now has Auntsocial’s new line added to it.
Now this might seem like a lot of confusing steps for just editing a document, why not just use Google docs? The thing is every single change is tracked, and we can have an interesting social dynamic among people working on projects.
Or, if Auntysocial really is antisocial, and thinks other editors are putting to many lines in, they can fork it, and do their own version, and not push the changes back. The original thus can morph into many different branches and versions of its original self.
What we get in a collaborative space is a detailed edit record:
And we get a total view of the edit activity as the “pulse” which gets more interesting with more editors and activity:
I did not even mention GitHub issues, which more or less becomes a discussion area attached to each commit. And graphs! Graphs!
All kinds of activity metrics…
This is of course, a silly useless example of GitHub editing. I’m trying to get a feel how complicated an ask is it for a small project time to take on. And the pull merging probably gets more complex as the number of people participating grows, this is what I want to learn. What if things get out of sync? How do you work out multiple versions?
but you can help me out by just going in there and making a lot of just a few changes. How much can the Home on the Range song change?
If GitHub seems bizarre/confusing/too-geeky see if this small experience can smooth the hump of entry. I want to find out if the entrance barrier can be smoothed. So please, go fork my stuff, please.
And I will followup in a next post with a different, real world change you can do.
Top / Featured Image: I hoped to find a photo of a tourist attraction featuring a giant fork, but my searches came up empty (I mostly for photos of front forks of Giant brand mountain bikes)
So I made a montage of two images licensed CC0 or public domain from pixabay — a fork PNG image and another one of the ranch buildings (it looks like the Alps but might be the Sierra Nevada too, or heck Colorado). I assembled in Photoshop and converted to black and white.