mestizo.monster/content/posts/old/how-to-use-github-like-a-proper-human-being/index.md at e4dda25041b8bee86aab0f7c07ad0d06b68d8681

TacoWolf/mestizo.monster

Fork 0

taco e4dda25041

create theme

2024-03-02 17:44:53 -05:00

10 KiB

Raw Blame History

title

date

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. We should really start to charge 10 cents for each bad commit someone makes one. We’d make millions.

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.

When making a commit, I normally follow this short list of guidelines by Chris Beams, along with the git style guide. Here’s what I’ve learned:

Keep your commits atomic. What’s this mean? Fresh Consulting says 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.

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

“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? 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 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?

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 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, right?

Now…

I’m betting you’re going to go to my repos on GitHub and start yelling at me on Twitter 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!

10 KiB Raw Blame History Unescape Escape