And with Git in General

So you’ve gotten ok with scripts, or at least have tasked yourself with sorting through and in some cases slinging around plain text files. You’ve even heard about this Github thing, maybe you’ve already made an account, maybe you’re even digging in to it more often. What could go wrong? Instead of me just being critical of strangers on Twitter, here’s a few things you may want to avoid when starting out, with some other background to get a better handle on things. Let me know what I’m overlooking or am just plain wrong about in the comments!

Get the gist

I’m not going to provide a full introduction to code sharing sites, but it comes up often enough that you can also paste code you’re working on at Github’s associated gist.github.com site. Even anonymously, this is a quick and easy way to let others see log files or code you’re working on, stack multiple files behind one URL, and keep it ‘private’ so only folks you give the URL to can see it. Versus advertising-heavy (or unfortunately easily misspelled *ahem* sites,) gist.github.com is just generally cleaner, and is therefore recommended.
Now onto the main event.

Everybody is a star

Github is, first and foremost, a code sharing site for individuals, sometimes grouped as part of ‘organizations’, commercial or otherwise. It puts its users first, though, like a social network. Admire the projects a particular person is involved in or code they generate? ‘Follow’ them, and just like on other social networks, you’ll see their public activity in a ‘newsfeed’-like section. You may want to understand what Stars means, in comparison to ‘Favorites’ or ‘Likes’ in other networks. By starring a project (or even a gist, as mentioned above) you can, at the simplest level, bookmark it and recall it based on your login. Further, you can opt-in to ‘watch'(recieve notifications) for changes or updates to projects, including issues others are having or features folks are requesting. Why am I clarifying its use? Because you should use this more often.
Srsly. Do this. As often as you want.

So far this is sounding like a very social experience, and there are norms, just like any other society. It’s a common theme in open source to dig into other peoples work, let people see what’s going on in your project so they can help you, or decide for themselves if they want to take advantage of it. Where folks that are unfamiliar with these norms run into issues is when they think they want to photocopy the internet into their own three-ring binder. By which I mean, folks who use the Fork functionality to copy the contents of a project/repository and put it under their user, but then make no changes to that code. Instead, just download the code and star the project, it helps the person whose code you’re taking an interest in. Often people posting code to sites like github are more interested in writing and debugging code rather than putting restrictive licenses on their work. I see a lot of people extending code but keep the original license in it, which makes it confusing as to how that code came to be. Wrote it yourself? Feel free to make your own license(just like I’m of the mind patents shouldn’t have such a negative effect on things, I’d recommend Apache 2.0, but it’s completely up to you,) and include it in the text.

Fork me?

Didn’t write it originally and/or don’t need to substantially modify it? Just download and/or star it.
Don’t just copy the entire content out of somebody elses script and paste it into a new file in your ‘scripts’ repo, that’s just tacky. Extending somebody else’s code? Fork to keep their commit history & ownership(it may help you to review their thought process/blame them later!), attribute their contributions in a comment or README(or don’t, depending on the license or lack thereof on the original code, you may be allowed to just consider it ‘adopted‘,) and take it from there!

Pulled out on a limb

Git makes a branch called master when initializing the tracking of a repo, which is just the convention for something called a HEAD reference(pointer.) Asleep yet? DID I JUST BLOW YOUR MIND? Don’t worry about all that, really, but do take into account the following. If you fork someone’s repo and then create a new branch to work in, your literal ‘branching-off’ point is well defined. If it has a logical name like ‘add-lsbom-functionality-to-pkgbuild’, you can even keep an eye on the scope of the changes you’ll be implementing. Project maintainers usually want separate fixes or features addressed in different branches, so they can evaluate the effect on the code base separately.
Branches are cheap and easy, you can start back at that branching off point if things go awry, or catch yourself up to the current state after a failed attempt you tossed aside. I’m obviously not getting deep into specifics, but this leads to the concept of Pull Requests, which is the main currency on Github for passing around(hopefully working) code when contributing to a project – you will want to learn how to create a named branch, make your changes as commits to that branch(maybe rewriting some of your commit history if you did embarrasing stuff… not that that ever happens) and send a request to have the project maintainer merge your code into the branch of their project that they find applicable, which may very well be ‘master’.
Moral of that story is: make your changes in a named branch of the forked project so who did what is clearer when the project maintainer goes to merge it.

Then let’s begin

And my final thought for this piece is: it may seem like you’re interaction with a project finishes once you’ve worked on your code and submitted a Pull Request, but that is actually often just the beginning of a conversation. It’s all open source, and while we’d all like to have the best, most active project with everyone on the same page helping it win the most mindshare by merging our brilliant code, maintainers may be reluctant to just take anything that’s thrown at them. Likewise, folks can fork as they see fit, but just because they’ve decided to put in the effort to interact with others and contribute back doesn’t mean it will be evaluated as worthwhile, or included without any tweaks. The core dev group may decide to spin off the pull request into its own branch and take their own swing at the problem or feature. Hopefully all of this is socializing is worth it, and turns out to be a positive learning experience where egos remain unbruised and everyone works to speed up shipping good code. And it may even be code that gets work done for us and our customers.

1 Comment

This is a good article, Allister. As a relative GitHub newbie, I’d like to add one topic that has been useful to me in better understanding GitHub: posting bug reports (Issues, in GitHub parlance). If you take time to document issues clearly (à la Mike Boylan) and test when the developer asks, you can make a contribution to the project even if you are not a coder.