v0.0.1: Open Source GitHub repo review (/idrinth-api-bench/issues)
A series on learning from different GitHub Repos. In this first post we look at /idrinth-api-bench/issues.
I recently held a TwitterSpace, which attended by around 1.5k people, where I asked them to submit their Open Source project for my first Substack survey. There were only two questions:
Asking them to submit their repo url. I was keen to limit each submission to a single url. When I have carried out this exercise on other platforms in the past, I have on occasion received over ten repo submissions from a single person.
Asking them to pick whether they were the owner, maintainer, contributor or user for that project. Whilst this wouldn't be a deciding factor as to whether I picked a particular project to review, I was interested to see if people only submitted their own project or they submitted someone else’s.
Here is a screenshot of the Substack survey:
If you would like your Open Source repo featured in a future post, then you can find the Substack survey here.
From the many results I received, I have selected one repo to review in this blog post. We can learn a lot by looking at how different projects do things. As this is a series, don’t forget to subscribe for free to also read future posts of GitHub repo reviews…
Repo homepage/landing page
My first impressions of this repo are good. I see a clear and concise description at the top right of the GitHub repo, followed by a url, five lines of topics and SEMVER releases.
After the repo meta data on the right column, my eyes are naturally drawn to the README, which only has text and badges. I think something visual would help, such as a screenshot from the deployed repo. Yes, I appreciate this can get out of date, but this is not meant to be the latest and greatest screenshot, but an indication of what it looks like - which I believe has a massive impact on a good first impression.
What are your first impressions?
Next I like to go to the Insights tab at the top and then look at the Community tab on the left. These give me another quick overview of the repo’s setup, for example: Code of Conduct, License etc.
It looks like a full house of completed items! That is what we like to see! 🥳 These are the tasks recommended by GitHub that every project should complete to be friendly. I personally have a list of about 20 items which keeps growing, so I recently decided to make an Open Source (no surprise) project on it called “The Open Source HealthCheck” - but that’s a story for another time, let me know i you would like to hear more about it https://github.com/EddieHubCommunity/HealthCheck
Why are these items so important to every project?
Description: this always being at the top right of the repo homepage, and gives users a quick and concise place to get a brief understanding of the project.
README: this is the most important file in the repo, it will always show on the repo’s landing/homepage, plus contains all the necessary information about the project.
Code of Conduct: it is important for projects to have this but also enforce it, so that the project collaboration is friendly to everyone. This does not need to be written from scratch, there are templates available, and GitHub presents you with a button here on this Community Insights page when there is no existing CoC.
Contributing: this is a Markdown file with the project’s details on how to get started contributing to the project.
License: there are different licenses to select from. The MiT licence is popular because as it is short, to the point and permissive. You can learn more about popular licenses here at https://choosealicense.com by GitHub.
Security policy: it is important if a security vulnerability is found that it is not shared publicly until it is fixed to avoid it getting exploited. This file explains how to contact the maintainers privately with the details.
Issue template: it is daunting for people to correctly fill out a blank issue, but if there is a standard template people can use depending on the type of issue being raised, then this is helpful to them and to you. Common templates are: bug, documentation and feature suggestion.
Pull Request template: similar to the Issue template mentioned above, this will help contributors correctly include the information the maintainer requires. Unlike with the Issue templates where there will be several types, there is only one PR template.
Branch
Usually, the default branch is “main” (previously “master”), so to see “the-one” does confuse me slightly. There is nothing wrong with not using “main” but it is what we have all got used to. Maybe one line reason in the README might help clear that up?
Releases
Releases are built on top of git tags, this allows additional information to be included. Releases are what makes a project go from hobby to pro. Ok, not the only reason, but I do believe it really helps the project look more professional. Great to see this feature being used here and following the standard SEMVER format (in this case the latest version is v2.7.4).
SEMVER stands for Semantic Versioning. A brief overview of SEMVER, is the format of 0.0.0, which is created from “major.minor.patch”. But what is major, minor and build?
major: when a breaking change is made
minor: new functionality but still works with backward functionality
patch: bug fix that should will not effect any existing functionality
Project Boards
Great to see Project Boards being used on this project, I find they are a great way to visualise issues. I even use Project Boards for my content creation plan as well as client work, as it helps keep transparency with the progress of the project. However I do always recommend hiding this if it is not being used, to avoid distracting the user with an extra main tab but would add no value if it was empty.
Issues + Labels
Many project use Issues in a basic way. Having a title and description are good ways to keep track of tasks, but these quickly becomes a sea of the same items which makes it difficult to find anything. This can be solved by using Labels, as we can scan through the list more easily. Plus we can use the Labels to filter the Issue list down further to items we are more interested in.
This repo has made great use of Labels not just in the wording of the labels themselves but also in the colouring to differentiate them.
Support the project by giving it a star
https://github.com/idrinth-api-bench/issues
What do you look for when visiting a GitHub repo? What makes you want to look further into it and what makes you think, “hmm…I’m going move on to another GitHub repo?”.
If you have got to the end of this blog post, I appreciate you supporting me and also the project mentioned in this blog post. You can continue to support me by sharing my publication or a specific post with your network. Thank you!
Nice one, Eddie