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
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.
Thanks for the opportunity. I’ve made a pull request (I hope).
I’ve been dabbling a little with the other side of git following this:
Which is more, so far, working with keeping track of local changes using the terminal. I am finding it useful. I ned to figure out how to combine the two. How you would do the exersise from this post on my desktop…
Thanks for the tutorial link, that looks fantastic. I’m not too sure if the work group I am hoping to use this for will go terminal, but it’s likely useful. The part where I get tangled up is dealing with conflicts (in life too!)
Github stills scares the heck out of me using it on my own machine!
By the by, for longer works, there’s also a git environment for writing longer works, typically documentation, but I’m sure could repurpose that! https://www.gitbook.com/
Thanks Tony- it gives my pause when you are confused by something! Thanks for the rip on gitbook, that looks like a nice layer atop the Github ratworks.
Also, in my other post John Johnston provided this nice tutorial link http://rypress.com/tutorials/git/index
Github seems so simple and yet it isn’t necessarily intuitive (at least to me). For instance, I forked the Daily Create a good while ago and tried to add some detail to the directions at some point but didn’t understand that I needed to initiate a pull request (the wrong word for me instinctively but makes sense if I think harder). All my other work has been with stuff I own or co-own so I just didn’t get the process. So thanks and congratulations on the awesome dog.
Viva Cog and the Dog.
Yes, that’s my concern on how to introduce people to it who are not part of a massive code base, and just doing some simple text editing; there’s a lot of geeky overhead. I need to up my own understanding, this tutorial so far has been great (not sure if it was you who suggested it) http://rypress.com/tutorials/git/
I wonder if just having a repo with a README.md file might help with getting folk started. Although the direction are clear in the ‘fork-on-the-range’ project it might be easier if there were no other files and branches around? (The read me will be rendered in Github I think s folk can see the changes they make).
Having said that, this is the first time I’ve made any progress at all learning git and I’ve made several tries before.
That’s an idea. However, I think if the first view of your site is a repo view, I think it dis-orients people who have never seen it, which is why I aimed to make the first view a web page. But it might be worth a try.
Bit of a manual trackback, I posted a bit about this:
pushed it to medium where it got some interesting reactions:
Thanks John- I saw Ben’s response but not the others. I don’t think it’s a matter of championing GitHub itself as a “tool for education” but figuring out the ways you can leverage parts of it, and finding the ways in the lower some of the barriers.
It’s a half done prototype, but check this out http://cogdog.github.io/ccc-map/core.html It represents a giant spreadsheet of modules and objectives and subjectives, each which needs to be editable for people to contribute resources and activity ideas. I’ve got it to a single page, and most of the content we want people to edit are little stub HTML files.
I built a way to dynamically link the view to it’s source in Github; that will be for repo collaborators who can edit the HTML directly in the repo (no forking). But that’s a bit much for the public, so I am rigging the public input link to go to the issues, where I use a template to guide the input.
Not everyone needs to “get” github to make use of it.
You have been busy, looks beautiful. The logic for contributing looks lovely too.
Clicked a couple of edit button to see the issue thing working, I have a knee-jerk reaction against using ‘awesome’, but am in awe!