Document your GitHub repo in a professional way

You should always make sure your GitHub repo looks professional. This is one of the first things that hiring managers or potential colleagues will check when considering you for a position on their team. Your GitHub account is the equivalent of your LinkedIn profile in the software developer world.

Apply all of the basic rules in each of your GitHub repositories and remember the most important rule: you should always think about the other people that work on your code.  It is important to keep your GitHub repositories looking professional for all your development projects.

How to make sure that your repo is professional:

We prepared a few simple rules that you should follow to make sure that your repo is professional. Read them carefully:

Professional repo – basic rules

The most important rule in maintaining a professional repo is to always think about people that you share your code with: collaborators, code reviewers, programmers, recruiters, or non-technical users who might want to reuse and/or improve your project.

Ask yourself the question: what information might they need from you in order to use your repo?

Also, keep them in mind when something unexpected happens. If you realize that you made a mistake and something is not working as it should communicate it to your collaborators so that they know not to expect the normal behavior from that feature until it is fixed – you can leave a comment, open an issue, or leave a link to the specific line of code.

5 basic rules to follow in your projects

Following these five rules is a simple way to make your repo look professional:

1. Respect the rules of the code review flow that your team follows. Use descriptive names for your branches (e.g., refactor-authentication, user-content-cache-key, make-retina-avatars) and make sure that your ‘feature branch’ is up-to-date with the ‘main branch’ in your repository.

2. Write a meaningful title for your pull request and always add a short summary of changes introduced in the pull request.

3. Use descriptive commit messages – each commit should be small enough to describe in one sentence. The commit message should be written in the imperative tense and capitalized. Read more about how to write descriptive commit messages.

-> Here are some examples of descriptive commits:

-> Here are some commits that are not descriptive:

4. Do not commit files that are not related to the project. Instead, add them to a .gitignore file. A common mistake is to commit entire node_modules the directory which makes your pull request unreadable.

5. Add a descriptive README file to your project.

Useful hints:

There are a few useful hints that can help you to keep your repo professional:

1. If you need to correct your commit message you can do it for your most recent commit by using git commit --amend command.
2. If you want to make your GitHub messages more organized you can use Markdown syntax.
3. Remember that adding a file to the .gitignore cannot also be used to remove files that you added using that technique. If you committed a useless file into your repo you need to remove it manually.
4. Do not disable Eslint or Stylint using inline comments within your code if not specified in the project requirement.