📃 Personal Repository Guidelines (PRG)

PRG is a repository categorization and guideline framework. By harnessing the power of GitHub Actions, it automatically crafts a tier-based display, neatly categorizing your repositories for enhanced clarity and impact. Beyond mere organization, it sets forth comprehensive guidelines, templates for READMEs, and overall repository structure, ensuring each project is showcased with maximum professionalism and coherence.

• Categorized your repositories and projects into Platinum, Gold, Silver, and Bronze tiers for your GitHub Portfolio.
  • Display your repositories in a searchable and sortable HTML table, created with GitHub Actions and displayed through GitHub Pages, to organize and showcase your projects to the world.
• Follow the defined guidelines to guide your repository structure and README content.
• Utilize the predefined README templates to get your projects up and running quickly and easily so you can focus on what matters most - your code!

PRG creates a HTML table to showcase your projects in your GitHub Portfolio.

Table of Contents

• PRG Document Library
• Features
• Background Story
  • README Driven Development (RDD)
  • "The GitHub Portfolio Problem"
  • Telling a Story with your README
• Definitions
• Q&A
• Getting Started
• What's Inside?
• 1. Categories
  • PRG Connection File
  • Tier Badges
    • Platinum Tier Project Badge
    • Gold Tier Project Badge
    • Silver Tier Project Badge
    • Bronze Tier Project Badge
    • Optimized Tier Project Badge
  • Profile Badges
    • PRG Collection Badge
  • Building the Project Tier Table
• 2. Guidelines
  • Category Guidelines
  • Brand Guidelines
  • README Guidelines
  • Repository Settings Guidelines
  • Repository Structure Guidelines
• 3. Templates
  • Project Templates
    • Platinum Tier Template
    • Gold Tier Template
    • Silver Tier Template
    • Bronze Tier Template
  • License Templates
• Closing
  • PRG Showcase
• What's Next?
• Project
• Contributing
• Resources
  • General Resources
  • GitHub Portfolio Related Resources
  • UML Diagram
  • Handy Web Tools
• License
• Credits

PRG Document Library

Below is a list of all the documents and resources available for PRG.

Category Guidelines Guidelines for categorizing your repository tiers and naming conventions.	Brand Guidelines Guidelines for creating your own brand for your project.	README Guidelines Guidelines for repository READMEs.
Repository Structure Guidelines Guidelines for repository structure and files.	Repository Settings Guidelines Guidelines for repository settings.	PRG Portfolio Website An example PRG Portfolio from PRG's creator.
Table Generator Guide Guide for setting up the Python (PyRG) project tier table generator script.	Badge Reference Guide Guide for displaying the tier badges.	Template Guide Guide for using the provided templates.
Platinum Tier Template Platinum project template for your repositories.	Gold Tier Template Gold project template for your repositories.	Silver Tier Template Silver project template for your repositories.
Bronze Tier Template Bronze project template for your repositories.	PRG Connection File Connection File (PRGCF) for your repositories.	Table Generator Script Python script for generating the project tier table (PyRG).
Project Tier Table Project tier table for your projects.	Private Project Tier Table Project tier table for non-GitHub or private projects.	License Example Directory Directory for license examples for your repositories (MIT, Apache, etc.).
PRG's Official Website A website dedicated to PRG and all of those who utilize it.	PRG's Official Website Repository Submit a pull request to add your PRG Portfolio to the PRG Showcase.

🔑 Key

Icon Color	Document Type
	Guideline
	Guide
	Template
	File/Directory

Features

This README highlights the three core components of PRG:

1. Categorize your repositories into five tiers: Platinum, Gold, Silver, Bronze, and Optimized, then display them in a project tier table (built using GitHub Actions, hosted and deployed using GitHub Pages) to showcase your GitHub Portfolio.
2. Guidelines defined for repository README, files, and overall structure.
3. Templates for your READMEs and associated files. Templates are provided for each tier to help you get started quickly and easily by utilizing README Driven Development (RDD).
   > [!IMPORTANT] > Each component above will have related documents that will provide more details.

Background Story

I developed the Personal Repository Guidelines (PRG) to address the challenges of maintaining and standardizing my repositories, as well as to enhance the presentation of my GitHub Portfolio. Previously, inconsistencies in README files and folder structures across different repositories made maintenance and templating for future projects cumbersome. PRG serves as both a solution and a documentation resource.

• This document is primarily tailored for GitHub's version control system, but its principles can be adapted for use with other version control systems.
• The PRG repository is subject to the same standards it sets, thereby exemplifying its own guidelines.
• The two main goals of PRG are to:
  1. Provide a system to categorize repositories to solve the GitHub Portfolio Problem.
  2. Provide guidelines for repository READMEs, files, and overall structure by utilizing README Driven Development (RDD).

README Driven Development (RDD)

PRG is based on the concept of README Driven Development (RDD) by GitHub founder Tom Preston-Werner.

• README Driven Development is a methodology that forces you to think about what you're trying to build before you begin writing code.
• The practice of RDD is to write the README before writing any code.

"Consider the process of writing the Readme for your project as the true act of creation. This is where all your brilliant ideas should be expressed. This document should stand on its own as a testament to your creativity and expressiveness. The Readme should be the single most important document in your codebase; writing it first is the proper thing to do." - Tom Preston-Werner

The GitHub Portfolio Problem

Another reason I created PRG was to solve the "GitHub Portfolio Problem" (as I like to call it):

Below is a good summary of the problem:

GitHub is being used to showcase my portfolio, but I don't want to showcase every single repository I have created. I want to showcase my best work, but I also want to showcase my other work that I am proud of. How do I do that?

• Noticing the Problem #1: I noticed this problem by reading Quora Articles (here and here) and Reddit Discussions (here) around this topic.
• Noticing the Problem #2: I also noticed that people make multiple accounts on GitHub, in some cases to showcase their best work on one account and their other, less important, work on another account. I didn't want to do that, and I hope this solution can cut down on the number of extra accounts people have to create to solve this problem.
• Noticing the Problem #3: Some users solved this problem by creating organizations on GitHub to showcase their work. I didn't want to do that either, and I hope this solution can cut down on the number of extra organizations people have to create to solve this problem.

As one GitHub user points out in this great article on the problem, How I Organize my GitHub Repositories:

"The issue is that all of these repositories are on the same level. There is no order, no differentiation between them. They just sort of exist on the user profile." -Andrei Cioara

PRG was designed to solve this problem by categorizing your repositories into five tiers and then showcasing them in a project tier table for your PRG Portfolio.

[!IMPORTANT] View the Resources section for more information around GitHub Portfolios.

Telling a Story with your README

Your README is the first thing people see when they visit your repository, it should be clear and concise, but also tell a story about your project. It should be a living document that is updated as your project evolves. Don't make people guess what your project does. Tell them.

"You only get one chance to make a first impression," the old saying goes. It's cliche, but nevertheless sound, practical advice. -Lauri Apple via Opensource.com

Definitions

Here are some definitions to help you understand the terminology used in this document:

• PRG: An acronym for Personal Repository Guidelines.
• PRG Optimized: A repository/project that is categorized using the PRG framework.
• PRG Collection (aka PRG Portfolio): The entire collection of repositories that are categorized using PRG.
• PRG Connection File (aka PRGCF): A special markdown file placed in the root of each of your repositories that is used to categorize your repositories using PRG.
• PRG Showcase: A showcase of publically known users who are using PRG to categorize their repositories. Visit The Official PRG Website to view and add your name to the showcase.
• Project Tier: A tier/rank that is assigned to a repository based on the information in the PRG Connection File file.
• Project Tier Table: A table that is automatically generated using GitHub Actions and hosted using GitHub Pages that displays your PRG Collection.
• Project Tier Table Generator (PyRG): A Python script and GitHub Action that is used to automatically generate a Project Tier Table for your PRG Collection.
• Tier Badge: A badge that is placed at the top of each repository README to indicate the tier of the repository.
• Tier Template: A template for your repositories that is used to standardize your README and repository structure.
• GitHub Portfolio: Your entire collection of repositories on GitHub that you want to showcase for your developer portfolio (PRG and non-PRG repositories).
• GitHub Portfolio Problem: The problem of showcasing and categorizing specific repositories for your GitHub Portfolio.
• README Driven Development (RDD): A methodology that forces you to think about what you're trying to build before you begin writing code. The practice of RDD is to write the README before writing any code.
• README: A markdown file that is placed in the root of each of your repositories that is used to describe your project.
• Guideline: A guideline document that provides guidance for your README, files, and overall repository structure.
• Guide: A guide document that provides instructions for using a feature component.
• GitHub Actions: A feature of GitHub that allows you to automate tasks within your repositories.
• GitHub Pages: A feature of GitHub that allows you to host and deploy your repositories.

Q&A

Below are some common questions and answers about PRG:

• Q: How do I determine the tier/category of my repository?
• A: See the Category Guidelines for more information.
• Q: What if I don't want to categorize my repository?
• A: You can leave your repository uncategorized (by not including a PRG Connection File), and it will be brought into the tier table as Optimized.
• A: If you want to exclude it from the tier table completely, you can configure the flags in the tier table generator script for this purpose. See the Table Generator Guide - Configuration for more information.
• Q: You keep saying "Optimized", what does that mean?
• A: Optimized simply means: a repository that is categorized using PRG.
• Q: What kind of repositories can I categorize using PRG?
• A: You don't need an open source project to use PRG, it can be closed source.
• A: In fact, you can categorize any repository/product/project you want, including private repositories or products you have published (or plan to publish) elsewhere; PRG is not limited to GitHub, although it is primarily tailored for GitHub's version control system.
• A: See the Category Guidelines for more information.

Getting Started

To begin, follow these steps:

1. Fork this repository.
2. In the Project Tier Table Generator script, modify the Required Configurations section.
   • Add your custom domain name or GitHub pages URL to the TIER_TABLE_URL variable.

     For more information, see the Table Generator Guide - PRG Connection File.

3. Place a PRG Connection File in the root of each repository you want to categorize using PRG.
   • Ensure your connection file is updated with the correct repository tier and other relevant information.

     Detailed instructions are in the PRG Connection File section. Information on how to determine your repository tier/category is in the Category Guidelines.

4. Place a optional logo for your repository in the docs/images folder named PRG.png.

   See the Table Generator Guide - PRG Project Logo for more details about the logo. Consult the Brand Guidelines for more details about designing your logo.

5. Affix the appropriate tier badge at the top of your repository README to showcase the category of your repo/project.

   Reference the Badge Reference Guide - Tier Badges to gather the appropriate badge for your repository. The tier you chose to use in the PRG Connection File should match the tier badge you use in your README.

6. Implement GitHub Actions to automate the creation of your project tier table.

   Additional guidance is available in the Table Generator Guide - GitHub Actions Workflow.

7. Set up and deploy GitHub Pages to display your project tier table for your PRG Portfolio.

   Refer to the Table Generator Guide - GitHub Pages Deployment for setup instructions.

8. Incorporate the PRG Collection Badge into your GitHub profile README.

   Reference the Badge Reference Guide - Profile Badges to gather the appropriate badge for your repository.

9. For new project repositories, utilize the provided templates to unify your README and project structures.
   • Templates are provided for each tier to help you get started quickly and easily.

     For template usage, see the Template Guide.

10. Feel free to contribute, join the discussion, star, or share this repository to help others solve the GitHub Portfolio Problem.

[!IMPORTANT] If you choose to fork or clone this repository and make modifications, please ensure to give appropriate credit. This can be done by including a link back to the main branch of this repository in your documentation or project in a clear and proper manner. Thank you and good luck with your GitHub Portfolio!

What's Inside?

Below is a list of the main files and folders in this repository and their specific purposes:

PRG-Personal-Repository-Guidelines # Root folder
├─ _layouts # Jekyll layouts for the site
│  └─ default.html # Default layout for the site
├─ _site # Jekyll site build folder
├─ assets # Site assets
│  ├─ css # Site CSS
│  │  └─ style.css # Site CSS file
│  ├─ fonts # Site fonts
│  └─ images # Site images
│     ├─ favicons # Site favicons
│     ├─ banner_large.png # Large banner
│     ├─ banner_social.png # Small banner
│     └─ search.png # Search icon
├─ categories # Category folders
│  ├─ table_generator_guide.md # Table generator guide
│  ├─ badge_reference_guide.md # Badge reference guide
│  ├─ project_tier_table.md # Project tier table
│  └─ project_tier_table_private.md # Project tier table for private repos
├─ docs # Site documentation
│  ├─ api # Postman API collection
│  └─ images # Documentation images
├─ guidelines # Guidelines for repository READMEs, files, and structure
│  ├─ category_guidelines.md # Category guidelines
│  ├─ brand_guidelines.md # Brand guidelines
│  ├─ readme_guidelines.md # README guidelines
│  ├─ repository_settings_guidelines.md # Repository settings guidelines
│  └─ repository_structure_guidelines.md # Repository structure guidelines
├─ scripts # Python build scripts
│  ├─ project_tier_table_generator.py # Project tier table generator
│  └─ requirements.txt # Python requirements
├─ templates # README templates
│  ├─ license_examples # License examples
│  └─ template_guide.md # Template guide
├─ _config.yml # Jekyll configuration file
├─ index.md # Site index file
├─ CITATION.cff # Citation file
├─ CNAME # Custom domain file
├─ .gitignore # Git ignore file
├─ .gitattributes # Git attributes file
├─ .github # GitHub folder
├─ PRG.md # PRG Connection File
├─ LICENSE # License file
└─ README # This file

1. Categories

To solve the "GitHub Portfolio Problem" above and to distinguished the quality of the project, PRG categorizes repositories into five tiers:

Platinum
Gold
Silver
Bronze

Optimized (included in PRG, but not within a specific tier)
None (uncategorized, your average non-PRG repo on GitHub)

PRG uses project tiers to categorize your repositories for your PRG Portfolio.

PRG Connection File

PRG achieves this by utilizing GitHub Actions to automatically create a project tier table based on a simple markdown file (PRG Connection File) or (PRGCF for short) placed in the root of each of your repositories.

Tier Badges

• The categorized tier badge should be prominently displayed at the top of each repository to align with PRG standards.
• This is what links your repository to your overall PRG Collection.

Platinum Tier Project Badge

Gold Tier Project Badge

Silver Tier Project Badge

Bronze Tier Project Badge

Optimized Tier Project Badge

Profile Badges

PRG Collection Badge

• The PRG Collection Badge should be prominently displayed in your GitHub profile README to indicate that you are using PRG to categorize your repositories.
• This badge will link to your project tier table for your PRG Portfolio, clearly displaying your categorized repositories and closing the loop on the GitHub Portfolio Problem.

Consult the Category Guidelines for more details on how to categorize your repositories.

• This guide will break down what each tier means and how to categorize your repositories.
• It will also explain repository naming conventions and how to display the tier badges.

Building the Project Tier Table

PyRG: PRG teams up with Python to create your project table.

PyRG is a Python implementation of the PRG framework. It is a simple Python script that allows you to easily create a project tier table for your PRG Portfolio. Also included is a GitHub Action CI/CD workflow that will automatically generate a table of all your repositories and their PRG tiers to deploy to GitHub Pages in order to showcase your projects/portfolio.

Consult the Table Generator Guide for more details on how to setup the project tier table generator using GitHub Actions and GitHub Pages.

Related Component Documents:

Category Guidelines
Table Generator Guide
Badge Reference Guide
Project Tier Table
Private Project Tier Table
PRG Connection File

2. Guidelines

Below are the guidelines for repository READMEs, files, and overall structure. This applies to ALL tiers.

[!NOTE] PRG contains a lot of guidelines and guides to help you get started. You do not need to conform all of your repositories to these guidelines in order to use PRG or adhere to it. If you just want to use PRG for the portfolio table, feel free to do so. The guidelines are there to help you create a better overall repository and portfolio.

[!WARNING] Some Guidelines are used for other PRG components but are located in the guidelines folder for convenience. e.g. Category Guidelines is for the Category component but is located in the guidelines folder.

Category Guidelines

Review the Category Guidelines for more details on how to categorize your repositories.

Brand Guidelines

Review the Brand Guidelines for more details on how to create your own brand for your project.

README Guidelines

Review the README Guidelines for more details on how to structure your repository README.

Repository Structure Guidelines

Review the Repository Structure Guidelines for more details on how to structure your overall repository.

Repository Settings Guidelines

Review the Repository Settings Guidelines for more details on how to configure your repository settings.

Related Component Documents:

Category Guidelines
> Brand Guidelines
> README Guidelines
> Repository Structure Guidelines
> Repository Settings Guidelines

3. Templates

The following templates are provided for you to use in your repositories. These templates are designed to be used with the PRG framework.

Project Templates

Consult the Template Guide for more details on how to use the provided templates.

• Templates are broken down by the four (main) tiers of projects: Platinum, Gold, Silver, and Bronze.
• See the following related template repositories for each tier:

Icon	Tier	Template Repository
	Platinum	PRG-Platinum-Tier-Template
	Gold	PRG-Gold-Tier-Template
	Silver	PRG-Silver-Tier-Template
	Bronze	PRG-Bronze-Tier-Template

• Optimized tier projects are uncategorized and do not have a template. Use the template that best fits your project.

[!NOTE] For example, I use the Optimized tier for my personal and organization profile READMEs since they don't fit into any of the other tiers.

License Templates

Use or add more licenses to the License Example Directory located here: templates/license_examples.

• Each license should be in its own folder.

Related Component Documents:

Template Guide
Platinum Tier Template
Gold Tier Template
Silver Tier Template
Bronze Tier Template
License Example Directory

Closing

Thank you for taking the time to read through this document and I hope you find it useful! If you have any questions or suggestions, please feel free to reach out to me!

Please reference the SUPPORT file in this repository for more details.

PRG Showcase

If you would like to add your PRG Portfolio to the PRG Showcase, please open a pull request with your information added to the PRG Official Website Repository in order to be viewed on the The Official PRG Website.

What's Next?

• Conform all of my repositories to PRG.
• Official version release v1.0.0 of PRG.
• Write about the GitHub Portfolio Problem and the benefits of using PRG to solve it on Medium.

I'm looking forward to seeing how this project evolves over time and how it can help others with their GitHub portfolio.

Please reference the CHANGELOG file in this repository for more details.

Project

Please reference the GitHub Project tab inside this repository to get a good understanding of where I'm currently at with the overall project.

• Issues and Enhancements will also be tracked there as well.

  Please join the PRG Discussions to discuss this project!

Contributing

Feel free to submit a pull request if you find any issues or have any suggestions on how to improve this project. You can also open an issue with the tag "bug" or "enhancement".

• How to contribute:

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/PRG-Personal-Repository-Guidelines)
3. Commit your Changes (git commit -m 'Add new feature')
4. Push to the Branch (git push origin feature/PRG-Personal-Repository-Guidelines)
5. Open a Pull Request

Please reference the CONTRIBUTING file in this repository for more details.

Resources

Below are some external resources I found helpful when creating my repositories and PRG in general:

General Resources

• GitHub Docs - GitHub documentation.
• Einstellung effect - Don't let your past experiences limit your creativity.
• README Driven Development - The original article on README Driven Development by Tom Preston-Werner.
• The power of README Development - Great article on README Driven Development.
• What your code repository says about you - Great article on how your repository can tell a story.
• How I Organize my GitHub Repositories - Great article on how some people have tried to solve the "GitHub Portfolio Problem".

GitHub Portfolio Related Resources

• Using GitHub as your portfolio
• How to present a GitHub project for your resume
• Using GitHub to Land a Job
• What do job-seeking developers need in their GitHub?
• Hiring Indicators, OSS, and the Value of GitHub
• How To Create a GitHub Portfolio
• How to efficiently build a portfolio on Github?
• How To Create A GitHub Portfolio

UML Diagram

Below is a UML Package Diagram of the PRG framework:

[!NOTE] The diagram was created using PlantUML. The source code for the diagram can be found here and the generated image can be found here. Both are located in the docs/diagrams folder.

• PlantUML - PlantUML is an open-source tool allowing users to create UML diagrams from a plain text language.

Handy Web Tools

Below is a list of handy web applications I built that you can use to help develop your repositories and projects.

CREDITS Generator Generate CREDITS.md files for your projects.

Resolution Scale Calculator Scale design dimension up or down from/to @1x, @2x, @3x.

GitHub User Info Find relevant info about GitHub users or organizations.

License

This project is released under the terms of the GNU General Public License, version 3 (GNU GPLv3), which ensures that derivatives of the software remain open source.

• The GNU GPLv3 is a "copyleft" license, ensuring that derivatives of the software remain open source and under the GPL.
• For more details and to understand all requirements and conditions, see the LICENSE file in this repository.

Credits

Author: Scott Grivner
Email: [email protected]
Website: scottgrivner.dev
Reference: Main Branch