How to make your GitHub repository look and feel professional ✈🌍

🕺 What makes a professional repository?

Nearly all professional repositories meet the following criteria:

• Is nicely organized
• Contains numerous files in the root directory
• A detailed README
• A security policy
• LICENSE file
• Workflows
• A good description and About section

⚡ Creating workflows

What is GitHub Actions?

According to the official documentation:

GitHub Actions is a continuous integration and continuous delivery (CI/CD) platform that allows you to automate your build, test, and deployment pipeline. You can create workflows that build and test every pull request to your repository, or deploy merged pull requests to production.

I use GitHub Actions for all of the features listed above, but also for the workflow badges! (we'll cover those later)

1. In your repository homepage, press the Actions tab.

2. Browse workflows and configure those which meet your needs. I use the Rust and clippy-check actions on all of my important Rust repositories.

If you're using Rust, your rust.yml workflow file may look like this:

name: Rust

on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]

env:
  CARGO_TERM_COLOR: always

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v3
    - name: Build
      run: cargo build --verbose
    - name: Run tests
      run: cargo test --verbose

📚 README.md, LICENSE, and SECURITY.md

These files are a must have in any repository. But what are they?

README.md

This file provides a landing-page like experience for those who visit your repository. It the first thing you are greeted with when viewing a repository.

Delivering a detailed README.md is crucial to keep a visitor's attention and introduce potential users to your software.

Earlier we set up workflows, which also provide status badges! You can find your badge here:

https://github.com/<OWNER>/<REPOSITORY>/actions/workflows/<WORKFLOW_FILE>/badge.svg

Try adding this to the top of your README.md and see the difference it makes:

<div align="center">
    <h1>MYPROJECT</h1>
    <img src="https://github.com/<OWNER>/<REPOSITORY>/actions/workflows/<WORKFLOW_FILE>/badge.svg" alt="Workflow status badge">
</div>

LICENSE

The LICENSE file defines the license of your software.
If you are having trouble picking a license, https://choosealicense.com/ may help you out.

Possibly the most common open-source software license is the MIT license.

Copyright <YEAR> <COPYRIGHT HOLDER>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

SECURITY.md

The SECURITY.md file informs users on how to report security concerns and/or vulnerabilities.

You can view an example security policy here.

📝 Open source community standards

There are even more policies and guidelines you can setup for your repository. Your repository should check all of the recommended community standards.

To see what your repository is missing, visit the Insights/Community Standards page.

🎇 About section

Topics

Be sure to list the most relevant topics your repository falls under.
Picking good topics will make it easier for your repository to be discovered in GitHub's Explore tab.

Description

A good repository description informs users of what the repository is about.
Bad example, (bear with me), but if you were exploring on GitHub and stumbled across a repository named Oven, you'd expect it to have a description maybe along the lines of:

Oven is a lightweight Javascript library (~20kb) exposing hidden Javascript functions.
View the Wiki section for more information.

You would not want to see:

Oven is a library made in Javascript. It is my first repository. Please star it.

⛔ Disabling unused features

Don't bloat your repository! Removing bloat starts with removing unused features.

For example, if you aren't using the Wiki tab, remove it!

In Eddie Jaoude's video about getting more GitHub stars, he makes a really good point. If you are going to have documentation, you may not want to use the Wiki tab. You most definitely want to farm all of those pull requests that come with holding documentation within the repository itself. Consider using a docs/ folder.

You can disable select features by entering your repository's Settings page and scrolling down. There, you can check/uncheck the features of your choice.

👋 Conclusion

I hope this article helped you in some way. If it did, make sure to react with this post and share it! I make these articles for free to try and improve the open source community, and give beginners the resources I didn't have when starting out. _{This article took 5 hours to write. 🕔}

Follow me for more awesome articles! 🎉