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.
- Display your repositories in a searchable and sortable
- 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 Document Library
- Features
- Background Story
- Definitions
- Q&A
- Getting Started
- What's Inside?
- 1. Categories
- 2. Guidelines
- 3. Templates
- Closing
- What's Next?
- Project
- Contributing
- Resources
- License
- Credits
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. |
Icon Color | Document Type |
---|---|
Guideline | |
Guide | |
Template | |
File/Directory |
This README
highlights the three core components of PRG:
- 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.
- Guidelines defined for repository
README
, files, and overall structure. - 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.
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:
- Provide a system to categorize repositories to solve the GitHub Portfolio Problem.
- Provide guidelines for repository
READMEs
, files, and overall structure by utilizing 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
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.
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
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.
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.
To begin, follow these steps:
- Fork this repository.
- 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.
- Add your custom domain name or GitHub pages URL to the
- 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.
- Ensure your connection file is updated with the correct repository tier and other relevant information.
- Place a optional logo for your repository in the
docs/images
folder namedPRG.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.
- 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
. - Implement GitHub Actions to automate the creation of your project tier table.
Additional guidance is available in the Table Generator Guide - GitHub Actions Workflow.
- 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.
- 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.
- 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.
- Templates are provided for each tier to help you get started quickly and easily.
- 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!
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
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 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.
- 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.
- 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.
![PRG Optimized Logo](/scottgriv/PRG-Personal-Repository-Guidelines/raw/main/docs/images/prg_optimized.png)
![PRG Collection Logo](/scottgriv/PRG-Personal-Repository-Guidelines/raw/main/docs/images/prg_collection.png)
![PRG Portfolio Logo](/scottgriv/PRG-Personal-Repository-Guidelines/raw/main/docs/images/prg_portfolio.png)
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.
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
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.
Review the Category Guidelines for more details on how to categorize your repositories.
Review the Brand Guidelines for more details on how to create your own brand for your project.
Review the README Guidelines for more details on how to structure your repository README
.
Review the Repository Structure Guidelines for more details on how to structure your overall repository.
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
The following templates are provided for you to use in your repositories. These templates are designed to be used with the PRG framework.
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 |
---|---|---|
![]() |
PRG-Platinum-Tier-Template | |
![]() |
PRG-Gold-Tier-Template | |
![]() |
PRG-Silver-Tier-Template | |
![]() |
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.
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
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.
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.
- 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.
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!
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:
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/PRG-Personal-Repository-Guidelines
) - Commit your Changes (
git commit -m 'Add new feature'
) - Push to the Branch (
git push origin feature/PRG-Personal-Repository-Guidelines
) - Open a Pull Request
Please reference the CONTRIBUTING file in this repository for more details.
Below are some external resources I found helpful when creating my repositories and PRG in general:
- 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".
- 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
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.
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. |
![]() Binary Converter Convert text to binary and vice versa. |
![]() PWA - Demo Application PWA demo and tutorial application. |
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.
Author: Scott Grivner
Email: scott.grivner@gmail.com
Website: scottgrivner.dev
Reference: Main Branch