Search for a command to run...
Create a Winning GitHub Repository: Mastering Readme and Project Presentation
I am a developer having fun creating software.
No comments yet. Be the first to comment.
In today's digital age, GitHub has become an essential tool for developers, providing a platform to showcase their projects and collaborate with others. However, with over 100 million repositories hosted on GitHub, it's becoming increasingly challenging to stand out from the crowd. Whether you're an experienced developer or just starting, it can be challenging to create a GitHub repository that stands out. In this blog post, we'll provide you with practical tips and best practices to create an outstanding GitHub repository for your project. From setting up your repository to optimizing your README file, we'll guide you through the key elements to make your project stand out on GitHub. So, let's get started!
An organized GitHub repository can make a significant difference in attracting potential collaborators and employers to your project. A well-organized repository makes it easier for others to understand your project's purpose, how it works, and how they can contribute to it.
"Well begun is half done" - Aristotle
The process of creating an outstanding GitHub repository begins at its inception. Therefore, we will start by discussing all the options provided by GitHub when creating a new repository. However, if you already have an existing repository, you can still follow along with the entire content of this blog post.
When creating your repository, choose a name that clearly describes your project and is easy to remember. Avoid using vague or generic names, as they can make it difficult for others to find your project. The name is usually the first thing that everyone will notice about your repository, so selecting a good name is extremely important.
Include a brief description of your project that emphasizes its primary features and objectives. Your repository's name and description are indexed by GitHub to display results in their search bar, so be sure to incorporate any relevant search keywords about your project. Additionally, the first sentence of the description should enable others to swiftly grasp the nature of your project and determine if it aligns with their interests.
Initialising a new repository with a README file is always a good idea. We cover, in-depth, how to make a great README file in a later section. In the beginning, just writing a more detailed description of your project is more than enough.
A repository that is public but does not have a license feels like a code dump and not professional at all. So choose an appropriate license when you are making a public repository. A quick comparison of commonly used open-source licenses is available at choosealicense.com. Doing this will automatically add a LICENSE file to the root of your repository.
When initially creating a repository on GitHub, you have the option to select a .gitignore template based on the programming language or framework you will be working with. I recommend first searching for the primary framework or library you are using, and if you don't find it, simply choose the programming language you are using.
Think of the README file as the homepage for your repository. Usually, it is the first and only thing visitors to your repository's page will see, as people rarely examine the code directly. Therefore, it is crucial to create a strong impression by designing a well-structured and visually appealing README file.
Begin with your project title in Heading 1 font, followed by a description of your project. Your title may optionally contain the logo of your project if you have designed one for it.
From this point forward, I will guide you through each section that should be included in your README file. Use Heading 2 font for all section headings in your README. Using more than one Heading 1 font in a file often looks unappealing. The sections below are discussed in the same order as my recommendation for their placement in a README file.
# Project Title
Project description
## Screenshots (Section Heading)
Section content
## Section Heading
^ Note Heading 2 used for section heading
If your project features a user interface, include screenshots in this section. Images are effective at capturing attention, so it's beneficial to position the screenshots section where minimal scrolling is required to view it. You can display multiple images side-by-side in a GitHub README using the following code.
|  |  |  |
| :-----------------: | :-----------------: | :-----------------: |
| IBM ROM | Space Invaders | Timendus' OpCode Test |
The above example images are from one of my projects.
A simple bulleted list with hyperlinks to other sections of your README file should suffice. I recommend writing the rest of your README file first, and then adding this section only if your README becomes long enough that finding different sections through quick scrolling becomes inconvenient. However, in my modest experience, this section is not often necessary.
Create a bulleted list that highlights the most notable and unique features of your project. The content of this section will naturally be unique for each project. Emphasize what distinguishes your project apart from other similar projects in this section.
This section will contain the "hello world" of your project. If your project is a library intended for use by other developers, include some code that demonstrates the basic functionalities of your project through minimal examples. Adding a link to your library's documentation in this section is a good idea.
However, if your project is an app or website with an intuitive UI, you may want to skip this section. That being said, if your app or website is intended for advanced technical users (perhaps a CAD software), it would be a good idea to include a user manual in this section. If your user manual is lengthy, then provide a brief overview in this section and simply link to the documentation (i.e., the full user manual) of your project.
Place the installation instructions for your project in this section. If your project offers multiple installation methods, create a sub-section for each one. Within each installation method sub-section, include a list of prerequisites that features names and links to external dependencies or build tools that may be necessary.
Ensure that the instructions in this section are dead simple so that even absolute beginners can follow them. This may even include explaining basic commands like cd if your project is not specifically aimed at highly advanced users.
Common installation methods found in README files include downloading the executable from GitHub Releases, building from source, an app store link etc. You can see the installation section for one of my projects at this link.
Include this section in your README if you want to encourage others to contribute to your project. GitHub suggests creating a CONTRIBUTING file in the root of your repository, which provides a clear guide on the proper way to contribute to your project and outlines the rules and conventions that contributors must follow. Use this section to briefly encourage contributions and include a link to your CONTRIBUTING file.
## Contributing Guidelines
We always welcome contributions from developers of all skill levels. Please look at [CONTRIBUTING](./CONTRIBUTING.md) to get started!
You can refer to the official GitHub documentation website's CONTRIBUTING.md file, located at github/docs/CONTRIBUTING.md, as an example of a well-written CONTRIBUTING file.
Expressing gratitude and giving thanks is crucial. This section is dedicated to doing exactly that. List the individuals, projects, or major libraries that have played a significant role in making your project a reality. There's no need to include every library used in your project; simply mention a few of the major ones, without which building your project would have been considerably more challenging.
This section is optional. However, if you choose to include this section in your README, simply provide the name of the license under which the project is licensed, along with a link to your LICENSE file. For example:
This project is licensed under the terms of <name-of-your-chosen-license>. For more details see [LICENSE](./LICENSE.md).
Whew! That concludes the README file which is the biggest part of a GitHub repository.
If you consider your project complete, you probably won't need to perform much maintenance on your repository, except for the occasional library updates. On the other hand, you might be someone who plans on constantly adding features, fixing bugs, and working on updates for your project.
Regardless of your plans for your repository, it's very likely you'll need to make some commits. So, let's briefly discuss how to make good commits and release your project.
This section likely requires the least amount of effort. Simply adhere to some widely accepted best practices for committing code:
1. Write clear and concise commit messages 2. Commit frequently, with small, focused changes 3. Use branches for developing features and fixing bugs
The above points are largely inspired by Appflowy's code submission guidelines. These guidelines are a quick two-minute read and incredibly valuable, so I highly recommend taking the time to review them. The following is an excellent way, which is mentioned in the Appflowy guidelines, to format your commit messages:
The commit message consists of type:subject
type must be one of [build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test]
Releases are deployable iterations of your software that you can make available to a wider audience for downloading and usage. For a step-by-step guide on creating releases on GitHub, refer to this page in the GitHub documentation. Don't worry this can be done using the GitHub website's UI and is really easy.
I will provide my recommendations on how to create effective releases for your project.
Use semantic versioning to generate version numbers for your project. The following is a screenshot of the summary section on semver.org, which offers a concise explanation of what semantic versioning involves.
Changelogs are comprehensive documents that inform the end users of your project about the new features, bug fixes, and modifications made in the current release compared to the previous one. These are typically included in the release description.
Compose a changelog for each release of your project. For the initial release of your project, you may present the list of features instead of a changelog. By adhering to the suggestions in the "Committing Code" section, reviewing the commit messages since the last release can greatly assist in writing release notes.
In conclusion, creating an outstanding GitHub repository and README file for your project requires careful planning and attention to detail. By following the best practices outlined in this article, you can ensure your project stands out and attracts potential collaborators, employers, and users. Remember to focus on clear communication, organization, and visual appeal to make your repository and README file truly exceptional. Keep your project well-maintained and up-to-date, and you'll be well on your way to achieving success on GitHub.
Thank you for reading this far; I truly appreciate it. Feel free to connect with me on LinkedIn or leave a comment if you'd like to share your thoughts directly. I always welcome criticism.
If you enjoyed this post, you might want to check out my other articles at blog.sahej.io. (There aren't any others at the moment, but more will be added in the future!)
Wishing you a fantastic day ahead!