GitHub Repository Structure Best Practices

Whether we start a new project for private or for open source, we can follow some best practices to organize the repository for better team contribution and more elegant project structure.

  • We have created a repo that contains all the mentioned files and folders, please feel free to use it as a starting template. Please note that you can also use the repo as template (Use this template button).
Code Factory Berlin: OpenSourceRepoTemplate on GitHub

And now let’s describe the structure:

Basic Folder Structure

  • src Folder: The source code folder! However, in languages that use headers (or if you have a framework for your application) don’t put those files in here.
  • test Folder: Unit tests, integration tests… go here.
  • .config Folder: It should local configuration related to setup on local machine.
  • .build Folder: This folder should contain all scripts related to build process (PowerShell, Docker compose…).
  • dep Folder: This is the directory where all your dependencies should be stored.
  • doc Folder: The documentation folder
  • res Folder: For all static resources in your project. For example, images.
  • samples Folder: Providing “Hello World” & Co code that supports the documentation.
  • tools Folder: Convenience directory for your use. Should contain scripts to automate tasks in the project, for example, build scripts, rename scripts. Usually contains .sh, .cmd files for example.
Repo folder structure

Git Special Files

  • .gitignore: List of blobs for git to ignore. Affects commands like git add and git clean. You may use gitignore.io to generate a clean and useful gitignore file.
  • .gitattributes: Let’s you define attributes on files (e.g., to change how files look in a diff).
  • .mailmap: Lets you tell git that duplicate names or emails in the history are actually the same person.
  • .gitmodules: Let’s you define submodules (subdirectories of your git repository which are checkouts of other git repositories).

GitHub Special Files & Folders

  • README File: README or README.txt or README.md etc. is a file that answer the What, Why and How of the project. GitHub will recognize and automatically surface the README to repository visitors. Here is an awesome list for more professional readme files.
  • LICENSE File: LICENSE or LICENSE.txt or LICENSE.md etc. is a file that explains the legal licensing, such as any rights, any restrictions, any regulations, etc. GitHub has developed a tool to help you to choose the right license:
  • CHANGELOG File: CHANGELOG or CHANGELOG.txt or CHANGELOG.md etc. is a file that describes what's happening in the repo. Version number increases, software updates, bug fixes… are examples of the file’s content.
  • CONTRIBUTORS File: CONTRIBUTORS or CONTRIBUTORS.txt or CONTRIBUTORS.md etc. is a file that lists people who have contributed to the repo.
  • AUTHORS File: AUTHORS or AUTHORS.txt or AUTHORS.md etc. is a file that lists people who are significant authors of the project, such as the people who are legally related to the work.
  • SUPPORT File: SUPPORT or SUPPORT.txt or SUPPORT.md etc. is a file that explains how a reader can get help with the repository. GitHub links this file on the page "New Issue".
  • SECURITY File: SECURITY describes your project's security policies, including a list of versions that are currently being maintained with security updates. It also gives instructions on how your users can submit a report of a vulnerability. Fore more details, check the following link.
  • CODE_OF_CONDUCT File: CODE_OF_CONDUCT is a file that explains how to engage in a community and how to address any problems among members of your project's community. Here is some examples.
  • CONTRIBUTING File: CONTRIBUTING is a file that explains how people should contribute, and that can help verify people are submitting well-formed pull requests and opening useful issues. GitHub links this file on page "New Issue" and the page "New Pull Request". This helps people understand how to contribute.
  • ACKNOWLEDGMENTS File: ACKNOWLEDGMENTS or ACKNOWLEDGMENTS.txt or ACKNOWLEDGMENTS.md etc. is a file that describes related work, such as other projects that are dependencies, or libraries, or modules, or have their own copyrights or licenses that you want to include in your project.
  • CODEOWNERS File: CODEOWNERS is a file that defines individuals or teams that are responsible for code in a repository. Code owners are automatically requested for review when someone opens a pull request that modifies code that they own. When someone with admin or owner permissions has enabled required reviews, they also can optionally require approval from a code owner before the author can merge a pull request in the repository.
  • FUNDING File: funding.yml is a file to raise funding for or support your project.
  • ISSUE_TEMPLATE File: When you add an issue template to your repository, project contributors will automatically see the template’s contents in the issue body. Templates customize and standardize the information you’d like included when contributors open issues. To add multiple issue templates to a repository create an ISSUE_TEMPLATE/ directory in your project root. Within that ISSUE_TEMPLATE/ directory you can create as many issue templates as you need, for example ISSUE_TEMPLATE/bugs.md. This list contains multiple templates for issues and pull requests.
  • PULL_REQUEST_TEMPLATE File: When you add a PULL_REQUEST_TEMPLATE file to your repository, project contributors will automatically see the template's contents in the pull request body. Templates customize and standardize the information you'd like included when contributors create pull requests. You can create a PULL_REQUEST_TEMPLATE/ subdirectory in any of the supported folders to contain multiple pull request templates.

.github Folder

This folder is just a convention folder used to place GitHub related stuff inside it. GitHub handles some of these files even when you place it in root of your project (CONTRIBUTING.md, CODE_OF_CONDUCT.md etc).

Some of the most used files in .github folder:

  1. CODE_OF_CONDUCT.md
  2. CONTRIBUTING.md
  3. FUNDING.yml
  4. SECURITY.md
  5. PULL_REQUEST_TEMPLATE.md
  6. ISSUE_TEMPLATE
  7. CODEOWNERS
  8. workflows: configuration folder containing Yaml files for GitHub Actions

Real world Repos

GitHub is full of open source projects. However, I can recommend the followings 2 projects as a starting point to watch and learn the repo structure as well as contributing best practices:

  1. Microsoft Terminal project.
  2. The OpenTelemetry .NET Client (CNCF project).

--

--

--

Code Factory Berlin is building tailored made DevOps and developers tools for the enterprise. We love & do open source.

Recommended from Medium

Observability Guide#03

Network inventory and resource management with Lansweeper

FIPS Compliance — What Does It Take?

The PCIE M.2 S11 Pro and SX8200 Pro, which one is better?

Azure IoT Hub Device Simulation with .Net C#

Installing and Initializing Ubuntu VMs using Cloud-init on vSphere 7.

How to rotate a range of pages in a PDF in Python

Time and Time Zone Headaches! (JS and more)

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Soulaiman Ghanem

Soulaiman Ghanem

Writes about technology, products and productivity

More from Medium

Connecting to MS Sql Server from a Mac with Windows Authentication

How To Update Your GitHub Repository in Visual Studio Code

GitHub repository pushing and pulling to/from the local copy of the GitHub repository

10 Quick SQL Tips After Writing Daily in SQL for 3 Years

Django vs Fast API: A Detailed Comparison