---
title: "[old] how to use github like a proper human being"
date: "2016-08-01"
tags: 
  - "coding"
  - "english"
  - "github"
  - "programming"
  - "tech"
---

> **disclaimer:** this post is really old, from when i first started writing technical articles. it's from 2016.

<figure>

![](images/474c4-1kqhihffhcr2ewixsov13wg.png)

<figcaption>

[Founding Father Octocat v2 by James Kang](https://octodex.github.com/foundingfather_v2)

</figcaption>

</figure>

#### Learn some etiquette, man.

Our repo organization can suck sometimes. Here’s how to make it less sucky.

#### Commits

I’ve seen (and made) so many bad commit messages at [devAcademy](https://medium.com/u/e90784f3811e). We should really start to charge 10 cents for each bad commit someone makes one. We’d make [millions](https://www.youtube.com/watch?v=EJR1H5tf5wE).

<figure>

![](images/f6b85-1_cjzykncqyesud_hlogc0a.png)

<figcaption>

100 million dollars, to be exact

</figcaption>

</figure>

We can settle this once and for all, though, by remembering a few guidelines when we commit anything on GitHub. And I mean **ANYTHING.** Personal projects, projects at work, even projects that you think will never see the light of day.

Once you get the habit of making awesome commit messages you’ll start doing them reflexively. You won’t have to put effort into making them. Your coworkers might like you more, too. _Might_.

<figure>

![](images/9c11c-1t8rlsnjffiarxbaah6ioew.gif)

<figcaption>

reflexive\_commits.gif

</figcaption>

</figure>

When making a commit, I normally follow [this short list of guidelines by Chris Beams](http://chris.beams.io/posts/git-commit/), along with the [git style guide](https://github.com/agis-/git-style-guide). Here’s what I’ve learned:

- **Keep your commits atomic.** What’s this mean? [Fresh Consulting says](http://www.freshconsulting.com/atomic-commits/) that you should apply changes as you make them. Your commit should revolve around ONE change or fix. If you have to add an “and” in your commit message, you’ve already committed too much.

- **Keep your commit message under 50 characters.** Why? Shorter things are easier to read, like this sentence. Short and to the point.

- **Capitalize the first word your commit message.** This is seen as generally good conduct by most gitsperts. Sentence case is also more professional looking and easier to read. (See a pattern here?)

- **Don’t end your commit message with a period.** Leave people in suspense. Leave them wanting more. Also, you want to make sure your 50 characters are well spent.

- **Use an imperative commit message.** Make your commits sound like you gave a command to someone. Programming is normally defined as “ordering your computer to do things”, so might as well keep that reputation up, right?

- **Use the same language in your commit messages.** Most people seem to use English as their preferred language, but it doesn’t mean you have to. What you do have to do is be consistent. Don’t mix phrases in one language with another language.

<figure>

![](images/2836b-16utifimt4z-d80ulvdsgaa.png)

<figcaption>

DON’T DO THIS. PLEASE. NOBODY LIKES SPANGLISH.

</figcaption>

</figure>

“_Refactor mediumExample() function”, “Remove unnecessary line in bot.js”,_ and _“Add SASS gem to gemfile_” are all good examples of easy to understand atomic commits that describe the action you’re doing in 50 characters or less. They might seem like unnecessary fluff to you, but when you or someone else needs to find a specific change you made in the past, they’ll thank you endlessly.

#### READMEs

I’ve seen so many projects with lackluster READMEs it kind of makes me sick. This is supposed to sell your project. When someone reads it, they have to be interested in your project in seconds. Only after that, they’ll consider reading further into it.

Here’s what I deem are necessary elements in a README:

- **A header image (_somewhat optional_).** Give people something to look at. They need to know what your project is at a glance. Maybe show them a screenshot with a logo placed on top, those are cool.

- **A title**. People need to know what your project is called. Make it obvious and make it stand out so people will remember it.

- **Some badges (_optional_)**. [Badges are cool, right?](http://forthebadge.com/) These should be important things like a Travis build status, Code Coverage or a David DM check or something like that.

- **A short description.** Twenty words or less. This small sentence should summarize everything that your project’s about. It’s your tagline, basically. Sell your project.

- **A small list of features.** Four to five things that say “Hey, this is what’s cool about this project!”. Get people interested in your project with some radical things that your product does.

- **A _short_ summary of installation and/or usage.** Your app should not take 10 paragraphs to describe how to install and/or use it, and you shouldn’t have to write an entire manual to quickly show some people how it works. Write up the quick, TL;DR version of installing and/or using your project. Nothing fancy, just enough to get people up and running.

- **External links to more documentation.** You wrote documentation for your project, right? _Right?_ **_RIGHT?!_** If so, _please_ don’t include the entirety of it here. GitHub has Wikis for your project, which makes for a much better method of presenting content, as opposed to one huge Markdown file. Link to some important articles here in a nice bullet list.

#### Branches

This is simple. Keep your branch names somewhat descriptive of what’s in them. GitHub automatically names your fixes after a patch if you edit them online, so whatever, but when you’re offline and you’re using git on your machine, give a nice, descriptive name to your branch that’s less than 30 characters.

[This git style guide](https://github.com/agis-/git-style-guide) says that **you should use “short and descriptive” names**, and I feel that’s a good benchmark for naming. Use something like “rails-5-upgrade” or use it to refer to a specific issue on GitHub, like “issue-57”. Make your branch name tell a story with as few characters as possible and give a _super_ quick synopsis of what you’re doing on it.

Also, for the love of Torvalds, **keep your branches up to date with the master branch**. I don’t care if it’s a pain to do. Make sure that when you submit a PR, the owner doesn’t have to go through a million hoops just to merge your branch to master. Merge conflict? Fix it.

#### Issues

Let’s talk bug reports for a moment here. Have you ever tried to fix something without knowing what the problem was in the first place? Huh? What’s, that, you say?

<figure>

![](images/af1d6-19sx8dn-bz3srv-g1o0hlwg.png)

<figcaption>

That’s you. [That’s how dumb you sound.](https://www.youtube.com/watch?v=2nm5jl7aM08)

</figcaption>

</figure>

> You can’t possibly expect me to fix something without knowing what the problem was in the first place.

Exactly! So many people submit issue reports on GitHub without describing a damn thing. Be descriptive with your issues. It helps everyone out.

How do you honestly expect someone to help you out with your problem if you can’t even take the time to describe it? Here are some things you should include in a bug report to make everyone’s lives easier:

- **What you were trying to do.** What were the conditions that produced this error? Were you trying to run a command or navigate to a page? So many questions, so little time. Include some screenshots or a log, if you can.

- **What actually happened.** You know, how things messed up.

- **What you think went wrong (_optional_).** This screwed up somehow, right? Take a guess as to why.

- **How to reproduce your issue.**

- **Other _important_ details.** OS, Version of whatever you were using, some logs if you have them, some screenshots. Help us help you.

Now that we’ve got that out of the way, let’s talk about _replying_ to issues. Be nice. Say “please” and “thank you”. Just because someone submitted a bad issue doesn’t mean they’re a bad person. Being nice to people is the first step to getting them to cooperate. Try to solve their problem while asking for more information. Offer solutions, not more problems.

Project maintainers should probably use [issue templates](https://help.github.com/articles/creating-an-issue-template-for-your-repository/) on their projects with the above issue suggestions. They’re there for a reason. It’ll help your users make better issues and get you better bug reports/suggestions. Help them help you.

#### Pull Requests

Everyone likes a helping hand. Most of the time, though, people would like knowing _how_ you’re helping them. This applies to Pull Requests, too. By using your descriptive commit style and **adding a quick bullet list of the changes you made to their code**, you’ll catch the owner’s attention and make them want to merge your branch faster.

I mean, why am I going to add your code to my awesome project if I have no idea what it does? You don’t have to write an essay on why these changes are for the better, but at least **give a short description on why your code is going to benefit the project.**

Also, project maintainers. **_Thank your contributors_**_._ It’s a simple gesture that goes a long way. This person put time and effort into helping your project, and even if it was only one line of code, _thank them._ Doesn’t matter if their code is awful, thank them for the time that they took to help out with your project. [We’re all in this together](https://www.youtube.com/watch?v=gbrbUfYSt0E), right?

#### Now…

I’m betting you’re going to go to [my repos on GitHub](https://github.com/thattacoguy) and start [yelling at me on Twitter](https://twitter.com/that_taco_guy) about how I don’t follow my own guide. You’re right, I’m not right now; I wrote this up as a guide to follow to make better commits based on what seems to be hip and trendy now. Let’s get better together!

* * *

### If you really liked this post, be sure to click that little green heart so that others can find it!

<figure>

![](images/755a8-1xs_n7ruqrbe-eszcs4oxrg.gif)

<figcaption>

Just do it. You know you want to. ❤

</figcaption>

</figure>
