Skip to content

Latest commit

 

History

History
440 lines (315 loc) · 20.5 KB

repository_structure_guidelines.md

File metadata and controls

440 lines (315 loc) · 20.5 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.

Resources:

.github/CHANGELOG.md File

Note

OPTIONAL file for ALL tiers.

  • This file contains a list of changes for each version of your project.
  • Use the Keep a Changelog format for your changelog.
  • Follow Semantic Versioning guidelines.

    • Given a version number X.Y.Z (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.
      • A normal version number MUST take the form X.Y.Z where X, Y, and Z are non-negative integers, and MUST NOT contain leading zeroes.
      • 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.0.0-beta
      • 1.0.0-rc
        • 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.

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.

These are supported funding model platforms

github: # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]
patreon: # Replace with a single Patreon username
open_collective: # Replace with a single Open Collective username
ko_fi: # Replace with a single Ko-fi username
tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
liberapay: # Replace with a single Liberapay username
issuehunt: # Replace with a single IssueHunt username
otechie: # Replace with a single Otechie username
custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']

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, build folders, and any sensitive information files.
    • e.g. .vscode/, venv/, .env
  • This will dramatically reduce the size of your repository, making it easier to download.

Tip

Use the .gitignore file in the root of this repository as a good example and starting point for a .gitignore template for your projects.

Note

It's good practice to research what the best files are to add to your .gitignore file based on the technology you're using to develop.

.gitkeep File

Note

OPTIONAL file for ALL tiers.

  • Sometimes you may want to include an empty directory as a resource in your project (say, a place to dump image files from an upload process).
  • Well, by default, git will ignore empty folders from being uploaded to your repository.
    • This is because git can't track empty directories. It can only track files.
    • Thus, no files/changes, no tracking.
  • Adding this file (with no content inside of it), will ensure that git will not ignore the file since a change has taken place.

Resources:

What is .gitkeep? How to Track and Push Empty Folders in Git

.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, Diagrams, 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.
  • Include diagrams (such as UML diagrams) in a docs/diagrams 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