Beautify your GitHub repo
Tags: github, license, readme, improvement
Published: 2022-04-17 15:36:55

Whether you like it or not, GitHub has become the primary provider to host one's code. You or your company is probably using GitHub. I want to highlight some files to beautify your GitHub repository in this post.

## README

I hope that by now, everybody is familiar with READMES. If one places a README file at the root of one's repo, GitHub will display its content on the repo's homepage.

However, here are a couple of tips you may not know.

The README may be in different formats:

<table>
<thead>
  <tr>
    <th>File name
    <th>Format
<tbody>
  <tr>
    <td><code>README</code>
    <td rowspan="2">Raw text
  <tr>
    <td><code>README.txt</code>
  <tr>
    <td><code>README.md</code>
    <td>(GitHub-flavored) <a href="https://github.github.com/gfm/">Markdown</a>
  <tr>
    <td><code>README.adoc</code>
    <td><a href="https://asciidoctor.org/">Asciidoctor
</table>

Note that HTML doesn't work: GitHub displays the raw HTML code, not the "rendered" HTML.

Additionally, one can set a README for an organization. You first need to create a repository named like the organization. Then, create the README file you want under the `/.github/profile/` directory. For an example, check this blog's organization that shows [a custom page](https://github.com/ajavageek).

For more details, check the [documentation](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes).

## LICENSE

If you want people to use your code, you should tell them under which terms they can use it. It's precisely the goal of licensing your code. Traditionally, most packages have a `LICENSE` (or `LICENSE.txt`) file at their root. GitHub has adopted this practice.

You can choose any license you want, but the GitHub <abbr title="User Interface">UI</abbr> provides a good help for Open Source ones. Go to _Add file > Create new file_. If you name the new file `LICENSE`, a new button will pop up: _Choose a license template_. When you click on it, GitHub offers the following choice:

* **Apache License 2.0**
* **GNU General Public License v3.0**
* **MIT License**
* BSD 2-Clause "Simplified" License
* BSD 3-Clause "New" or "Revised" License
* Boost Software License 1.0
* Creative Commons Zero v1.0 Universal
* Eclipse Public License 2.0
* GNU Affero General Public License v3.0
* GNU General Public License v2.0
* GNU Lesser General Public License v2.1
* Mozilla Public License 2.0
* The Unlicense 

You can choose one to check its content. GitHub displays its permissions, limitations, and conditions:

![GitHub license properties](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/f29fmg45vy9ppiucnok7.jpg)

You can now _Review and submit_. At this point, you are faced with three choices:

1. _Cancel changes_ cancels everything
2. _Choose a license template_ gets back to the license choice
3. _Commit new file_... commits the newly-chosen license to the repository

After adding the license, GitHub displays it on the right of the repository's page.

![GitHub repository sidebar displaying the license](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/iirnki97u6swvdi31ntp.jpg)

For more details, check the [documentation](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/licensing-a-repository).

## CODEOWNERS

GitHub automatically adds the configured code owners to pull requests. You define them in a `CODEOWNERS` file, whose format is somewhat similar to `.gitignore`.

Here's a quick sum-up of how GitHub handles it:

* You can set `CODEOWNERS` at the root or in a `.github` subfolder
* You can have a different file per branch
* A general configuration line consists of a pattern and an owner:

    ```
    *.txt    @nfrankel
    ```

    `@nfrankel` owns all `txt` files

* As with `.gitignore`, the configuration is applied sequentially. Bottom lines override top ones:

    ```
             @johndoe
    docs     @nfrankel
    ```

    `@johndoe` owns everything, but `@nfrankel` owns the `docs` folder

* You can set multiple owners:

    ```
             @johndoe @nfrankel
    ```

* An owner can be either an individual or [a team](https://docs.github.com/en/organizations/organizing-members-into-teams/about-teams). To define a team, use the org's name suffixed with the team's name:

    ```
             @ajavageek/developers
    ```

* You can't review the pull requests that you opened yourself! GitHub skips you if you're the one opening the pull request to test the configuration (cf. [StackOverflow](https://stackoverflow.com/questions/61903008/codeowners-file-in-github-repo-not-working)).

GitHub skips invalid configuration lines. To verify, you can use the UI:

![GitHub validates the CODEOWNERS file when you open it](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/b6r7d74su7c42efaxzuy.jpg)

## SECURITY

Projects want people to report security issues. But the communication channel(s) needs to be private so that hackers don't learn about the issue before it can be mitigated, fixed, or both. For this, GitHub offers a custom SECURITY file:

<ul>
  <li>Like the README file, it can adopt different formats:
<table>
<thead>
  <tr>
    <th>File name
    <th>Format
<tbody>
  <tr>
    <td><code>SECURITY</code>
    <td rowspan="2">Raw text
  <tr>
    <td><code>SECURITY.txt</code>
  <tr>
    <td><code>SECURITY.md</code>
    <td>(GitHub-flavored) <a href="https://github.github.com/gfm/">Markdown</a>
  <tr>
    <td><code>README.adoc</code>
    <td><a href="https://asciidoctor.org/">Asciidoctor
</table>
  <li>Like the CODEOWNERS files, you can put it at the repo's root or in a <code>.github</code> subfolder
</ul>

The easiest way to set up a SECURITY file is via the UI. Go to the _Security_ tab and click on the _Setup a security policy_ button. Click on the _Start setup_ button in the new window.

GitHub provides a default Markdown template, but of course, you can choose to change the format and the content. The important part is to tell users how they should report security vulnerabilities.

The newly-created file appears in _Security > View security policy_. Here's a [sample](https://github.com/ajavageek/beautifygithub/security/policy) in Asciidoctor format.

## Citations

If your project is good, other projects will likely use it. The project may be cited in academic works, even more so if it's of an academic nature itself. The CITATION file allows you to answer the following questions:

* What is the name of the software?
* What label should I use to uniquely identify the version of the software I have used?
* What is the appropriate set of people that should be cited as authors?

The standard CITATION format is the [Citation File Format](https://citation-file-format.github.io/), proposed by GitHub:

>`CITATION.cff` files are plain text files with human- and machine-readable citation information for software (and datasets). Code developers can include them in their repositories to let others know how to correctly cite their software.

You can non only choose how to format the citation but also cite an alternative source, _e.g._ a related academic article.

Again, GitHub's UI helps one create a `CITATION.cff` file. When you create one, it offers you to add a sample, which you can edit to your heart's content.

```yaml
cff-version: 1.2.0
title: Beautify GitHub sample repository
message: If you really want to cite this repository, here's how you should cite it.
type: software
authors:
  - given-names: Nicolas
    family-names: Fränkel
repository-code: 'https://github.com/ajavageek/beautifygithub'
license: Unlicense
```

After adding the file, a new _Cite this repository_ link appears on the right sidebar. You can choose which format you want to copy, APA or BibTeX when you click it.

![Citation link on the sidebar](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ay12pfmnfas5hybfo5gw.jpg)

## Sponsorship

Last but not least, let's look at how to configure sponsorship. If you provide value to third parties via your Open Source project, it makes sense to let them reward you. Note that you shouldn't count on it, though, or you're in for a surprise.

GitHub allows displaying sponsorship options via a dedicated `FUNDING.yml` in the `.github` repository. Once more, the UI helps. Go to _Settings_ and click on the _Set up sponsor button_. It opens the usual window to create a new file with a template. Here's how I changed it:

```yaml
github:
  - nfrankel
custom:
  - https://paypal.me/nicofrankel
```

The preview tab validates your input.

![Validation of the funding configuration file](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/2pwmvltes742dpxqxrru.jpg)

In this case, the validation fails by telling that user `nfrankel` (me) didn't enroll in the GitHub sponsors program.

A new "Sponsor this project" section appears on the right sidebar on the repo's homepage.

You need to check the "Sponsorships" checkbox in _Settings_ for it to appear. Thus, you can prepare everything in the repo and only activate it when you're ready.

## Conclusion

GitHub offers multiple ways to improve your repository's display and usability. A LICENSE and a README should be mandatory for any repository you want to share with others. Besides them, you should provide the other beautifications listed in this post.

The complete source code for this post can be found on GitHub:

{% embed https://github.com/ajavageek/beautifygithub %} 

**To go further:**

* [Customizing your repository](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository)
* [Adding a security policy to your repository](https://docs.github.com/en/code-security/getting-started/adding-a-security-policy-to-your-repository)
* [Citation File Format (CFF)](https://citation-file-format.github.io/)
* [About CITATION files](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-citation-files)
* [GitHub special files and paths](https://github.com/joelparkerhenderson/github-special-files-and-paths)

_Originally published at [A Java Geek](https://blog.frankel.ch/beautify-github-repo/) on April 17<sup>th</sup>, 2022_