Skip to content

Latest commit

 

History

History
396 lines (281 loc) · 18 KB

repository_structure_guidelines.md

File metadata and controls

396 lines (281 loc) · 18 KB
Raw

Repository Structure Guidelines

This guideline details necessary files and overall structure for your repository.

Important

This guidelines also details the GitHub specific files and folders that can be included in your repository. Examples for key files are located in the root of this repository and within the .github/ folder. Utilize these files as templates to craft your GitHub special/specific files.

Table of Contents

README File

Note

REQUIRED file for ALL tiers.

  • A README file describes your project and provides information on how to use it.
  • The README file should be named README.md.
  • The README file should be located in the root of your repository.
  • Use the templates in the Template Guide as a starting point for your profile README (especially if you're using PRG).

Tip

Consult the README Guidelines for more resources and information on how to write a README file.

LICENSE File

Note

REQUIRED file for ALL tiers.

  • This file contains the license for your project.

Resources:

Adding a License to a Repository Choose a License Open Source Licenses

.github/CREDITS File

Note

OPTIONAL file for ALL tiers.

  • This file should contain a list of people who have contributed to your project.
  • Compare this file to AUTHORS, CONTRIBUTORS, and ACKNOWLEDGMENTS files below.

Resources:

.github/CHANGELOG.md File

Note

OPTIONAL file for ALL tiers.

  • This file contains a list of changes for each version of your project.
  • Follow Semantic Versioning guidelines.
    • Given a version number MAJOR.MINOR.PATCH (e.g. 1.0.0), increment the:
      • MAJOR version when you make incompatible API changes
      • MINOR version when you add functionality in a backward compatible manner
      • PATCH version when you make backward compatible bug fixes
      • Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.
    • For pre-release and build metadata, use the labels alpha, beta, rc, and build using the format MAJOR.MINOR.PATCH-label.build.
    • Examples:
      • 1.0.0-alpha.1
      • 1.0.0-beta.2
      • 1.0.0-rc.1
        • rc stands for release candidate, which is a beta version with potential to be a final product, which is ready to release unless significant bugs emerge.
        • alpha and beta are used for pre-release versions
        • build is used to identify a build
        • This scheme is not strictly enforced, but it is recommended by the Semantic Versioning (SemVer) specification, highlighted in their 2.0.0 release here.
  • Use the Keep a Changelog format for your changelog

Resources:

Semantic Versioning Semantic Versioning HOWTO Software Versioning What do the numbers in a version typically represent How do version numbers work? Keep a Changelog

.github/CONTRIBUTING.md File

Note

OPTIONAL file for ALL tiers.

  • This file contains information on how to contribute to your project.
  • See the Contributing-Gen Template to generate a contributing file for your project.
    • Reference the GitHub Repository here and the UI Frontend repository for it here.

Resources:

Setting Guidelines for Repository Contributors Awesome Contributing List Hall-Of-Fame README Widget Contributing-Gen Template How to Build a CONTRIBUTING.md - Best Practices Good-CONTRIBUTING.md-template.md

.github/CODE_OF_CONDUCT.md File

Note

OPTIONAL file for ALL tiers.

  • This file contains a code of conduct for your project.
  • See the Contributing-Gen Template to generate a code of conduct for your project.
    • Reference the GitHub Repository here and the UI Frontend repository for it here.

Resources:

Adding a Code of Conduct to your project Awesome Code of Conduct List Debian Code of Conduct
Contributing-Gen Template
CODE_OF_CONDUCT Example Contributor Covenant

.github/SECURITY.md File

Note

OPTIONAL file for ALL tiers.

  • This file contains information on the security policy for your project.

Resources:

Adding a security policy to your repository

.github/SUPPORT.md File

Note

OPTIONAL file for ALL tiers.

  • This file contains information on how to get support for your project.

Resources:

Adding a support file to your repository SUPPORT Example

.github/CODEOWNERS File

Note

OPTIONAL file for ALL tiers.

  • This file contains information on who owns the code for your project.

Resources:

About code owners

.github/ISSUE_TEMPLATE.md File

Note

OPTIONAL file for ALL tiers.

  • This file contains information on how to create a pull request for your project.
  • This can also be a folder/directory called ISSUE_TEMPLATE with multiple templates for different types of pull requests.
    • e.g. ISSUE_TEMPLATE/bug_report.md, ISSUE_TEMPLATE/feature_request.md, ISSUE_TEMPLATE/custom.md

Resources:

Creating a issue template for your repository About issue and pull request templates Multiple issue and pull request templates (Blog Post) Awesome Template Lists Creating an issue Manually creating a single issue template for your repository

.github/PULL_REQUEST_TEMPLATE.md File

Note

OPTIONAL file for ALL tiers.

  • This file contains information on how to create a pull request for your project.
  • This can also be a folder/directory called PULL_REQUEST_TEMPLATE with multiple templates for different types of pull requests.

Resources:

Creating a pull request template for your repository About issue and pull request templates Awesome Template Lists About automation for issues and pull requests with query parameters Manually creating a single issue template for your repository

FUNDING.yml File

Note

OPTIONAL file for ALL tiers.

  • This file contains information on how to fund your project.

Resources:

Displaying a sponsor button in your repository

CITATION.cff File

Note

OPTIONAL file for ALL tiers.

  • This file contains information on how to cite your project.

Resources:

What is a CITATION.cff file? About Citation Files

Other GitHub Special Files

Note

OPTIONAL files for ALL tiers.

Below are some other popular files used in GitHub repositories:

  • AUTHORS file in your repository for more detailed information on the authors for your project.
  • CONTRIBUTORS a file in your repository for more detailed information on the contributors for your project.
  • ACKNOWLEDGMENTS file in your repository for more detailed information on the acknowledgments for your project.
  • ROADMAP file in your repository for more detailed information on the roadmap for your project.
  • GOVERNANCE file in your repository for more detailed information on the governance for your project.

Resources:

GitHub Special Files and Paths Common special files found in the root directory of a repository

.gitignore File

Note

REQUIRED file for ALL tiers.

  • This file should contain a list of files and folders that should be ignored by Git.
  • Its recommended to ignore your vscode workspace files, virtual environment files, and any sensitive information files.
    • e.g. .vscode/, venv/, .env

.gitattributes File

Note

OPTIONAL file for ALL tiers.

  • One reason I use this file, is to adjust the linguist language statistics on GitHub.

Resources:

Linguist -

.editorconfig File

Note

OPTIONAL file for ALL tiers.

  • This file contains information on how to configure your editor.

Resources:

EditorConfig

.prettierrc File

Note

OPTIONAL file for ALL tiers.

  • This file contains information on how to configure your code formatting.

Resources:

Prettier

.eslintrc File

Note

OPTIONAL file for ALL tiers.

  • This file contains information on how to configure your code linting.

Resources:

ESLint

.stylelintrc File

Note

OPTIONAL file for ALL tiers.

  • This file contains information on how to configure your style linting.

Resources:

Stylelint

.huskyrc File

Note

OPTIONAL file for ALL tiers.

  • This file contains information on how to configure your git hooks.

Resources:

Husky

.github Folder

Note

OPTIONAL folder for ALL tiers.

  • This folder contains information on how to configure your GitHub repository.

Resources:

GitHub Docs

.github/workflows Folder

Note

OPTIONAL folder for ALL tiers.

  • This folder contains information on how to configure your GitHub Actions.

Resources:

GitHub Actions Docs

.github/dependabot.yml File

Note

OPTIONAL file for ALL tiers.

  • This file contains information on how to configure your GitHub Dependabot.

Resources:

Dependabot Docs

api Folder

Note

OPTIONAL folder for ALL tiers.

  • This folder contains information on how to configure your API.
  • Include any API documentation in this folder.
  • Include any postman collections in this folder.

Misc. Folders

Note

OPTIONAL folders for ALL tiers.

  • Add any other folders as needed.
  • A lot of projects, especially web frameworks, have a src/ folder and other related folders.

Important

It's important to follow your frameworks conventions and programming style guides.

Images, GIFs, Videos, and Documents

Note

OPTIONAL files for ALL tiers.

  • Include repo images and GIFs in a docs/images folder.
  • Include repo videos in a docs/videos folder.
  • Add important documents to the docs folder.
  • Add more folders as needed.

Resources:

GiFox - Paid GIF recording tool for macOS. Snagit - Paid screen capture tool for macOS and Windows.

Resources