DEV Community

Cover image for Take Your Github Repository To The Next Level 🚀️
Eluda
Eluda

Posted on • Updated on

Take Your Github Repository To The Next Level 🚀️

I’ve been using Github for a very long time now, and along the way I’ve been gathering a step-by-step guide on creating the perfect Github repository. If you haven’t guessed already, this article is an enhanced version of that guide.

So without further ado, let’s get started!

Step 0. Make Your Project More Discoverable 🚀

Topics

— Inspired from Github Docs.

To help other people find and contribute to your project, you can add topics to your repository related to your project's intended purpose, subject area, affinity groups, or other important qualities.

With topics, you can explore repositories in a particular subject area, find projects to contribute to, and discover new solutions to a specific problem.

To browse the most used topics, go to https://github.com/topics/.

Examples

👇 Share with us your Github repository in the comments and I’ll add it here!

Step 1. Choose A Name That Sticks ✏️

Naming

— Inspired from Forbes.

Finding the right name for your project can have a significant impact on your success.

The wrong name can do worse than fail to connect with users. In contrast, a clear, powerful name can be extremely helpful in your marketing and branding efforts.

Here are 12 helpful suggestions on how to come up with a winning name for your project:

  1. Avoid hard-to-spell names.

  2. Conduct a thorough Internet search.

  3. Get the .dev or .io domain name.

  4. Use a name that conveys some meaning.

  5. Get feedback on the name.

  6. Make sure the name sounds good when said aloud.

  7. Use resources available for brainstorming names:

Examples

👇 Share with us your Github repository in the comments and I’ll add it here!

Repository Name Description
chroline/well_app Well App 😀 improve your productivity and long-term happiness in just 21 days.
ai/size-limit Size Limit Calculate the real cost to run your JS app or lib to keep good performance. Show error in pull request if the cost exceeds the limit.

Step 2. Display A Beatufiul Cover Image 🤩️

Cover

There’s no doubt that projects with eye-catching images usually perform better than those without these elements.

Users are more likely to support a project that has an attention-grabbing cover image, because it creates a sense of professionalism and creativity.

But you don’t have to be a designer to create amazing visuals for your project, because there’s a dizzying amount of free graphic design tools on the Internet:

Examples

👇 Share with us your Github repository in the comments and I’ll add it here!

Repository Cover Image
chroline/well_app Well App

Step 3. Add Badges To Convey More Information 🔥

Badges

Ever noticed those small images sitting at the top of the most performing Github projects? They’re called badges, and they can be used to show more information without using any words.

Here are some examples:

Badge URL
img https://img.shields.io/badge/Medium-12100E?style=for-the-badge&logo=medium&logoColor=white
img https://img.shields.io/badge/Hashnode-2962FF?style=for-the-badge&logo=hashnode&logoColor=white
img https://img.shields.io/badge/dev.to-0A0A0A?style=for-the-badge&logo=dev.to&logoColor=white
img https://img.shields.io/badge/YouTube-FF0000?style=for-the-badge&logo=youtube&logoColor=white
img https://img.shields.io/badge/HTML-239120?style=for-the-badge&logo=html5&logoColor=white
img https://img.shields.io/badge/Dart-0175C2?style=for-the-badge&logo=dart&logoColor=white

You can find all of these and more in the Shilds.io website. You can also use Badgen to quickly generate new badges for your project!

Examples

👇 Share with us your Github repository in the comments and I’ll add it here!

Step 4. Write A Convincing Description 📄

Description

— Inspired from 18F.

This is your chance to explain the project in one paragraph. If you do this well, you can captivate the reader into exploring more of your project and eventually using it!

In general, the description should answer a short list of basic questions:

  • What is this repo or project?
  • How does it work?
  • Who will use this repo or project?
  • What is the goal of this project?

If you follow these steps, not only will it be easier for developers to know how to become involved with the project, but it will be easy for non-coders to understand what the code is designed to do, and how they too can become involved!

Examples

👇 Share with us your Github repository in the comments and I’ll add it here!

Repository Description
ai/size-limit Size Limit is a performance budget tool for JavaScript. It checks every commit on CI, calculates the real cost of your JS for end-users and throws an error if the cost exceeds the limit.
aimeos/aimeos-typo3 Aimeos is THE professional, full-featured and high performance e-commerce extension for TYPO3! You can install it in your existing TYPO3 web site within 5 minutes and can adapt, extend, overwrite and customize anything to your needs.

Step 5. Record Visuals To Attract Users 👀

Visuals

People love animated imagery! You can use GIFs to visually show many things:

  • How your program is used.
  • The best features of your program.
  • A visual guide to achieve some specific task.

And there’s a wide variety of free tools that you can use to create said videos, including but not limited to:

  • Ascii Cinema to record your terminal sessions.
  • Loom or OBS to record any part of your screen.
  • Veed to edit videos online.

Examples

👇 Share with us your Github repository in the comments and I’ll add it here!

Repository Visuals
create-go-app/cli Create Go App Visuals
Rebilly/redoc Redoc Visuals

Step 6. Create A Detailed Installation Guide ✅ (optional)

Installation

If the user has to install your program before using it, you should add a detailed section that explains how the user can do it. Here are some general rules to follow:

  • Don’t jump any steps.
  • Have different sections for each operation system (Linux, macOS, Windows).
  • Show how the user can fix the most common errors.

I also recommend using the HTML <details> tag to create a collapsing menu. It results in a much cleaner README file!

Examples

👇 Share with us your Github repository in the comments and I’ll add it here!

Step 7. Create A Practical Usage Guide 🏁

Usage

You should show the user examples of how they can use your software, and the expected outputs too if you can. This will help prevent confusion about how your program works, and create a better bond between your software and its users.

Examples

👇 Share with us your Github repository in the comments and I’ll add it here!

Step 8. Answer Common Questions 🤔

FAQ

This section, also called the “FAQ” (frequently asked questions), should be left to contain the most common questions that your users ask. Too many people asking where to find the settings panel? Put the answer in here so no one has to ask again.

Examples

👇 Share with us your Github repository in the comments and I’ll add it here!

Repository FAQ
choojs/choo Why is it called Choo?
Is it called Choo, Choo.js or...?
Does Choo use a virtual-dom?

Step 9. Build A Supportive Community 🤗

Community

There’s nothing better than a nice community! If the user ever needs help, they can reach out, ask a question, and get a valuable answer to their problem!

Here are 3 general steps towards building a great community for your project:

Step 9.1 - Let’s Connect!

Add a “Let’s Connect!” section to your README, where you reveal several links to the platforms where your community resides: Discord, Gitter, Slack, or even simply an email address!

Step 9.2 - Discussions (optional)

You can use GitHub Discussions in a repository as a place for your community to have conversations, ask questions, and post answers without scoping work in an issue.

Here’s a guide on how to enable discussions for your repository.

Step 9.3 - Code of Conduct

— Taken from Github Docs.

Adopt a code of conduct to define community standards, signal a welcoming and inclusive project, and outline procedures for handling abuse.

A code of conduct defines standards for how to engage in a community. It signals an inclusive environment that respects all contributions.

You should have a CODE_OF_CONDUCT.md file in your repo that explains all the details that need to be known.

Here’s a guide on how to create a code of conduct for your community.

And here’s a template of a CODE_OF_CONDUCT.md file that you can freely use in your own work.

Examples

👇 Share with us your Github repository in the comments and I’ll add it here!

Step 10. Create Contribution Guidelines 👷

Contributions

— Inspired from 18F.

Since open-source inherently welcomes outside contributors, it’s important to explicitly state how they can help and what they can help with. This document should answer the following question: How can outside contributors become involved?

You should include a CONTRIBUTING.md file in your repo, which outlines the following:

  • If there are any additional setup steps specific for development.
  • Whether there are explicit Instructions for running tests before contributions are accepted.
  • Whether potential contributors should ask before they make significant changes.

Here’s a template of a CONTRIBUTIONS.md file.

Examples

👇 Share with us your Github repository in the comments and I’ll add it here!

Step 11. Choose The Right License ©️

License

— Inspired from Github Docs.

Public repositories on GitHub are often used to share open source software. For your repository to truly be open source, you'll need to license it so that others are free to use, change, and distribute the software.

There’s a choosealicense.com tool online that can freely help you choose a license for your project. You should include a LICENSE file (file extension is optional) that includes the legal excerpt that’s accompagnied by your chosen license.

But remember that you're under no obligation to choose a license. However, without a license, the default copyright laws apply, meaning that you retain all rights to your source code and no one may reproduce, distribute, or create derivative works from your work.

Examples

👇 Share with us your Github repository in the comments and I’ll add it here!

Step 12. Plan Your Future Roadmap 🚗

Roadmap

You should add a page to your project’s wikis that describes your plans for the future. This is your chance to specify your upcoming plans, and to show that your project has a long-term future. Be ambitious within the bounds of realism.

What features are you going to add in the next version? When do you plan to release those features that users can’t wait for? Answer all these questions in the roadmap.

Examples

👇 Share with us your Github repository in the comments and I’ll add it here!

Step 13. Create Github Releases 📌

Releases

Github has a releases feature that lets you show a history of your project’s versions. In every release, you should write a changelog that describes what’s new and what was removed from that version.

How do I make a good changelog?

Guiding Principles

  • Changelogs are for humans, not machines.
  • There should be an entry for every single version.
  • The same types of changes should be grouped.
  • Versions and sections should be linkable.
  • The latest version comes first.
  • The release date of each version is displayed.
  • Mention whether you follow Semantic Versioning.

Types of changes

  • Added for new features.

  • Changed for changes in existing functionality.

  • Deprecated for soon-to-be removed features.

  • Removed for now removed features.

  • Fixed for any bug fixes.

  • Security in case of vulnerabilities.

keepachangelog.com

Examples

👇 Share with us your Github repository in the comments and I’ll add it here!

Step 14. Customize Your Social Media Preview 🤩️

Social Preview

— Inspired from CSS Docs.

You can customize the image displayed on social media platforms when someone links to your repository.

Until you add an image, repository links expand to show basic information about the repository and the owner's avatar, but you can customize it to look more attractive!

Examples

👇 Share with us your Github repository in the comments and I’ll add it here!

Repository Social Preview
saikou-app/saikou Saikou
vercel/next.js Next.js the react framework for production

Step 15. Launch A Website 🚀

Pages

After doing all of the above tasks, there’s really only one step left that can really take your repository to the next level: launching a website!

You can use Github Pages to freely host a website straight from your repository. Creating a custom webpage for your project allows you to be more creative, and dramatically increases your chances to be discovered by search engines.

Don’t miss your chance to get that extra traffic!

Examples

👇 Share with us your Github repository in the comments and I’ll add it here!


Credits: ❤️

Those were 15 steps towards creating a killer Github repository. They’re not rocket science, but they can have a great effect on the success of your project!

Top comments (44)

Collapse
 
bennycode profile image
Benny Code

You picked great live examples! Thank you very much for sharing.

What also makes a GitHub repository attractive to me is when they are using GitHub releases and proper changelogs. Example: github.com/mui/material-ui/release...

Using GitHub pages for API documentation is also important. Example: github.com/vazco/uniforms/tree/gh-...

Collapse
 
eludadev profile image
Eluda • Edited

Thank you for these suggestions! 👍
I will be updating the article, and giving you the credits!

Collapse
 
bennycode profile image
Benny Code

Oh, that's cool! Thank you. 😊

Collapse
 
dhanushnehru profile image
Dhanush N

You can add much more such as profile viewer count etc.

You can have a look at my GitHub repository as well regarding stats & github actions 🙂

Collapse
 
eludadev profile image
Eluda

Very interesting, thanks!

Collapse
 
jcubic profile image
Jakub T. Jankiewicz

They are not actually for repositories only for profiles, it will look odd if you do the same on your project.

Collapse
 
dhruv194 profile image
Dhruv Mehta

Damn this is really a great article. I know that readmes are important and they make the project even better. But here you mentioned a few things about which I was completely unaware of. Thanks for sharing!

Collapse
 
eludadev profile image
Eluda

I'm glad you liked it! 👍️

Collapse
 
paulmcgann profile image
Paul McGann

Nice write up and something I will be using for future projects. There is another piece of screen recording software I thought useful to mention it is called Open Broadcaster Software (OBS) obsproject.com/. You can capture a whole screen or specific windows or a section of a screen. Best of all it is free and open source.

Collapse
 
eludadev profile image
Eluda

Thanks for the suggestion! 👍
I'll add it to the article and give you the credits for suggesting it.

Collapse
 
crunchstack profile image
CRUNCHSTACK

Thanks for the tips, they are good points overall

Collapse
 
eludadev profile image
Eluda • Edited

I'm glad you liked it! 🤗

Collapse
 
star_trooper profile image
Atharva Shirdhankar

Awesome collection of tools for GitHub readme 🔥.

Collapse
 
eludadev profile image
Eluda

Thanks! 🤗

Collapse
 
vulcanwm profile image
Medea

This is really nice! Bookmarked!

Collapse
 
eludadev profile image
Eluda

I'm glad you found it useful! 🤗

Collapse
 
bellatrix profile image
Sakshi

A big thanks to you!

Collapse
 
eludadev profile image
Eluda

And a massive thanks to YOU! 🤗️

Collapse
 
timhuang profile image
Timothy Huang

Very useful post! Thanks for your sharing.

Collapse
 
eludadev profile image
Eluda

Thanks for reading! ❤️

Collapse
 
adriens profile image
adriens

💡 Adding VHS to "Step 5. Record Visuals To Attract Users 👀 " mays also be a very nice option.

Collapse
 
noviicee profile image
Anamika

Awesome! 👏 🎉

Collapse
 
eludadev profile image
Eluda

Thanks a lot! 🤗️

Collapse
 
itshi32 profile image
itshi

preposterous project? 😳

Collapse
 
eludadev profile image
Eluda

Fixed! Thanks for pointing it out! 👍️

Collapse
 
beelen74584087 profile image
beelen

Fascinating innovative publication Shared information is of great motivation that I helped get understanding expertise greetings you have my support and I hope the following publications.

Collapse
 
princesp profile image
PrinceSP

Grwat explanation. Thank you very much.

Collapse
 
eludadev profile image
Eluda

I'm glad you found it useful! 👍️

Collapse
 
fabiosouzadev profile image
Fábio Souza

Awesome!!!!!

Collapse
 
eludadev profile image
Eluda

YOU'RE AWESOME! 🤗