The Best GitHub Feature You Never Knew Existed

It turns out that there are a few really cool GitHub features that most people didn’t even know existed. And when I say most people, I mean me. So if you work with GitHub or Bitbucket there is a good chance that this article will be really helpful to you—and I mean really helpful.

I’ll assume that most of you reading this already use Git to manage your code. Whether you’re part of a team in a large company or a lone developer, we all need some version control in our lives and Git is the industry standard at this point in time. While there are some who manage their own Git server, a very large percentage of users use GitHub, be it on GitHub Enterprise, paid GitHub or GitHub for free. One way or the other, it’s GitHub or Bitbucket and the mystery feature we’re talking about exists in both of them.

This critical feature that I want to talk about is CONTRIBUTING.md. Say what?

What we’re talking about is a document that is supposed to contain instructions and/or comments about contributing code to your repository. This could be technical explanations about the environment, onboarding, troubleshooting—anything relevant really. In the world of open source, it’s common practice to put in a ‘code of conduct’ which is a binding set of rules about how one can make use of the project.

In a project in my company, we’ve got everything in there: technical explanations, onboarding, and even rules about respectful conduct. Here’s an example:

# Contributing

When contributing to this repository, Make sure that your change is documented in JIRA item. please first discuss the change you wish to make via Slack,
email, or any other method with the owners of this repository before making a change. 

## Git process
We are using git and we are using git over ssh\https. In order to setup Git Enterprise, please  [Read git documentation](docs/git.md). You can find there information on the git flow as well.

## Pull Request Process
1. Ensure any install or build dependencies are removed before the end of the layer when doing a 
  build.
2. Update the documentation with details of changes to the interface, this includes new environment 
  variables, exposed ports, useful file locations and container parameters.
3. Follow the [versions policy](docs/versions.md).
4. You may merge the Pull Request in once you have the sign-off of other developers, if you 
  do not have permission to do that, you may request the reviewer to merge it for you.

## Best practice
We have a [best practice](docs/best-practice.md) guide that you should read before development. The guide is focused on code readability, clarity, and security.

## Build
We use Jenkins for our build system. If the build fails, please read [the guide on what to do in case of build failure](docs/build-help.md). 

## Best practice
We have a [best practice](docs/best-practice.md) guide that you should read before development. The guide is focused on code readability, clarity, and security.

## Code of Conduct
All pull requests and communications around this project should be in compliance with the company code of conduct. Please remember to maintain positive environment.

- Using welcoming and inclusive language
- Being respectful of differing viewpoints and experiences
- Gracefully accepting constructive criticism
- Showing empathy towards other contributers.

So as you can see, we’re talking about a nice little document that organizes and links to other documents. Once I put it into the directory, any developer, junior or senior, can access it. If you go into an open source project, find this document right away. Okay, okay—but what’s the big deal already? In GitHub, if you try to run a pull request to a repository that has a document like this, you’ll see this amazing little piece of text:

Now go ahead and admit that this is pretty great. Especially if you’re managing an infrastructure project that has several teams using it. It really takes your project documentation to the next level. Shall we continue?

Displaying a Checklist During a Pull Request

I believe that every time there is a pull request there will be a point at which another developer (not necessarily more senior) reads your code. When it comes to CONTRIBUTING.md, the head of the team I work on likes to say “this isn’t a confirmation, but an additional required reading.”

This is actually quite an important part of contributing code. If my CI process is good enough, I don’t have to worry about things like spaces, semi-colons, and comments in my pull request because the static code analysis takes care of it. But there are other things which are important for other developers who read the code to pay attention to. For example, that the pull request will have content and meaning. Or that there’s no eslint-disable in the code—whatever is important to any given project.

If you put a file called docs/pull_request_template.md in the docs folder, that template will appear on every pull request. But wait, there’s more. If you put a checklist:

- [ ] The pull request has at least a `What's New?` text and make sure that the subject has meaning.
- [ ] Never allow unnecessary use of `eslint-disable`.
- [ ] Tests are added to all new functionality.

it will appear in the request. Whoever made the pull request can fill it out and you can see in the pull request if they checked the items on the list or not. OK, now try to say that this isn’t genius.

There are a few other really great features that I didn’t know about, but this one right here just rocked my world. It’s not really code, but I believe that good documentation and good procedures are an essential component of good code.

About the author: Ran Bar-Zik is an experienced web developer whose personal blog, Internet Israel, features articles and guides on Node.js, MongoDB, Git, SASS, jQuery, HTML 5, MySQL, and more. Translation of the original article by Aaron Raizen.