How to make your GitHub repository look and feel professional ✈🌍
Tags: github, tutorial, codequality, programming
Published: 2022-11-12 17:00:00

> A good looking and nicely organized repository leaves a huge first impression on potential stargazers. 🌟

## 🕺 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](https://docs.github.com/en/actions/learn-github-actions/understanding-github-actions):
> 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. ![Highlighting the Actions tab](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ab1ibr7rde9qukpim13k.png)

2. Browse workflows and configure those which meet your needs.
I use the `Rust` and [clippy-check](https://github.com/marketplace/actions/rust-clippy-check) actions on all of my important Rust repositories.

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

```yml
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
```

![README file preview](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/kc3b8bhvmd5x7mup9do5.png)

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

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

![Preview](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/aft9yda3v4nwzbyw6bj4.png)

### `LICENSE`

The `LICENSE` file defines the license of your software.<br>
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.

```txt
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](https://github.com/atomist/samples/blob/master/SECURITY.md).

## 📝 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.


![Community Standards page](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/bzrdjcl57p05l9yzyzm4.png)

## 🎇 About section

![About section](https://i.ibb.co/spTjy8Z/about.png)

### Topics

Be sure to list the most relevant topics your repository falls under.<br>
Picking good topics will make it easier for your repository to be discovered in GitHub's [Explore](https://github.com/explore) tab.

### Description

A good repository description informs users of what the repository is about.<br>
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:
```txt
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.

![A bloated repository tab](https://i.ibb.co/ckcNGKr/top.png)

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

In [Eddie Jaoude's video](https://www.youtube.com/watch?v=HCXT3tBW3sU) 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.
<sub>This article took 5 hours to write. 🕔</sub>

Follow me for more awesome articles! 🎉