Skip to content

πŸ“ƒ Revolutionize your GitHub Portfolio with the PRG framework. Utilizing GitHub Actions, it auto-generates a categorized display for organized, impactful repository presentation. Includes essential guidelines and templates for READMEs and repository structure.

License

Notifications You must be signed in to change notification settings

scottgriv/PRG-Personal-Repository-Guidelines

Repository files navigation

Banner Large

Markdown Badge Jekyll Badge Data Tables Badge Python Badge
GitHub API Badge GitHub Workflow Status (with event) GitHub Workflow Status (with event)
GitHub Badge Email Badge BuyMeACoffee Badge
PRG Version Badge PRG Website Gold


Personal Repository Guidelines (PRG)

PRG is a system that transforms the way repositories are organized and presented in your GitHub portfolio. 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 #E5E4E2 Platinum, #FFD700 Gold, #C0C0C0 Silver, and #CD7F32 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!
Demo_1
PRG creates a HTML table to showcase your projects in your GitHub Portfolio.

Table of Contents

PRG Document Library

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

Category Guidelines
Category Guidelines

Guidelines for categorizing your repository tiers and naming conventions.

Brand Guidelines
Brand Guidelines

Guidelines for creating your own brand for your project.

README Guidelines
README Guidelines

Guidelines for repository READMEs.

Repository Structure Guidelines
Repository Structure Guidelines

Guidelines for repository structure and files.

Repository Settings Guidelines
Repository Settings Guidelines

Guidelines for repository settings.

PRG Portfolio Website
PRG Portfolio Website

An example PRG Portfolio from PRG's creator.

Table Generator Guide
Table Generator Guide

Guide for setting up the Python (PyRG) project tier table generator script.

Badge Reference Guide
Badge Reference Guide

Guide for displaying the tier badges.

Template Guide
Template Guide

Guide for using the provided templates.

Platinum Tier Template
Platinum Tier Template

Platinum project template for your repositories.

Gold Tier Template
Gold Tier Template

Gold project template for your repositories.

Silver Tier Template
Silver Tier Template

Silver project template for your repositories.

Bronze Tier Template
Bronze Tier Template

Bronze project template for your repositories.

PRG Connection File
PRG Connection File

Connection File (PRGCF) for your repositories.

Project Tier Table Generator Script
Table Generator Script

Python script for generating the project tier table (PyRG).

Project Tier Table
Project Tier Table

Project tier table for your projects.

Private Project Tier Table
Private Project Tier Table

Project tier table for non-GitHub or private projects.

License Example Directory
License Example Directory

Directory for license examples for your repositories (MIT, Apache, etc.).

PRG's Official Website
PRG's Official Website

A website dedicated to PRG and all of those who utilize it.

PRG's Official Website Repository
PRG's Official Website Repository

Submit a pull request to add your PRG Portfolio to the PRG Showcase.

Key

Color Document Type
#6236FF Guideline
#680F7F Guide
#E5E4E2 #FFD700 #C0C0C0 #CD7F32 Template
#FFFFFF File/Directory

Features

This README highlights the three core components of PRG:

  1. Categorize your repositories into five tiers: #E5E4E2 Platinum, #FFD700 Gold, #C0C0C0 Silver, #CD7F32 Bronze, and #6236FF 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 system.
  • 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.
  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 READMEx.

    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:

#E5E4E2 Platinum
#FFD700 Gold
#C0C0C0 Silver
#CD7F32 Bronze

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

Tier Graphic
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.

#E5E4E2 Platinum Tier Project Badge

Platinum PRG Badge

#FFD700 Gold Tier Project Badge

Gold

#C0C0C0 Silver Tier Project Badge

Silver

#CD7F32 Bronze Tier Project Badge

Bronze

#6236FF Optimized Tier Project Badge

Optimized

Profile Badges

#680F7F 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.
PRG Optimized Logo

PRG Collection Logo

PRG Portfolio Logo

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 system. 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 system.

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: #E5E4E2 Platinum, #FFD700 Gold, #C0C0C0 Silver, and #CD7F32 Bronze.
  • See the following related template repositories for each tier:
Icon Tier Template Repository
Platinum Template Logo #E5E4E2 Platinum PRG-Platinum-Tier-Template
Gold Template Logo #FFD700 Gold PRG-Gold-Tier-Template
Silver Template Logo #C0C0C0 Silver PRG-Silver-Tier-Template
Bronze Template Logo #CD7F32 Bronze PRG-Bronze-Tier-Template
  • #6236FF Optimized tier projects are uncategorized and do not have a template. Use the template that best fits your project.

Note

For example, I use this 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 rhw 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 Portfolio Related Resources:

License

This project is released under the terms of the GNU General Public License, version 3 (GPLv3).

  • The 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: scott.grivner@gmail.com
Website: scottgrivner.dev
Reference: Main Branch