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!

Importance & Benefits of a Well-organized GitHub Repository

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.

Repository setup

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

Choose a descriptive name

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.

Add a concise description

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.

Add a README

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.

Choose an appropriate license

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.

Select a relevant .gitignore template

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.

README file

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.

Project title and description

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

Screenshots

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.

| ![alt-1](img-1.png) | ![alt-2](img-2.png) | ![alt-3](img-3.png) |
| :-----------------: | :-----------------: | :-----------------: |
|       IBM ROM       |   Space Invaders    | Timendus' OpCode Test |

The above example images are from one of my projects.

Table of contents

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.

Features

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.

Usage

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.

Installation

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.

Contributing Guidelines

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.

Acknowledgements

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.

License

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.

Maintenance

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.

Committing Code

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]

Versioning and Releases

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.

Semantic Versioning

• 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

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.

Conclusion

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!

I occasionally browse GitHub like scrolling through a social media app. A few days ago I stumbled upon an issue that I thought I could solve. This was in a project called AppFlowy.

I initially found out about AppFlowy about a month before the time of writing. I loved it but I did not start using it because it did not feel ready for everyday use yet. I want AppFlowy to grow so I was excited to get an opportunity to contribute to it. Moreover, the frontend is written in Flutter which I am very familiar with. Familiarity with the tech stack certainly helped me with this first open-source contribution.

⚠️The Issue

I was looking at the issues marked good_first_issue and hacktoberfest, and ended up finding this one.

TLDR: In the table UI, when the column type was set to a specific type, undesirable extra vertical spacing was added to rows. You can see the before & after fix comparison below.

Video demonstrating the issue.

🔨Building the Project

The first step was to get a development build running on my machine. I sought out the official build guide and followed the steps.

Of course, I ran into an issue. I am building on an M1-based Mac, and the installed version of cocoapods on my machine refused to run. It was expecting the x86 version of some module (or something), which was (obviously) missing on my ARM64-based machine. Luckily a quick search took me to this StackOverflow page, and it was a quick and easy fix.

Turns out that the Homebrew version of cocoapods runs flawlessly on ARM64 Macs. So I just had to do,

sudo gem uninstall cocoapods
brew install cocoapods

And I had a build running, setting me up for my first open-source contribution!

👨‍💻The Code

Now I had to find out the code responsible for table UI. I reproduced the issue and used Flutter's widget selector tool to find out the culprit widget. This lead me to the aptly named GridMultiSelectCell widget. Here is the widget tree:

Then I used Flutter's layout explorer to find that a Wrap widget (docs), which houses some levels below in GridMultiSelectCell was responsible for the extra height.

Then I found the code responsible for generating that Wrap.

final children = widget.selectOptions.map(
  (option) {
    return SelectOptionTag.fromOption(
      context: context,
      option: option,
    );
  },
).toList();

child = Wrap(
  spacing: 4,
  runSpacing: 2,
  children: children,
);

The spacing: 4 in the constructor for Wrap was responsible for the extra height for some reason. As far as I know, it should just be adding horizontal margins between the children elements. Anyway, commenting out the spacing attribute eliminated the extra height but, unsurprisingly, horizontal spacing between the children was also eliminated.

I added that space back by giving each child a margin, which was accomplished by wrapping the SelectOptionTag constructor in a Padding widget.

Below is the final code:

final children = widget.selectOptions.map(
  (option) {
    return Padding(
      padding: const EdgeInsets.only(right: 4),
      child: SelectOptionTag.fromOption(
        context: context,
        option: option,
      ),
    );
  },
).toList();

child = Wrap(
  runSpacing: 2,
  children: children,
);

That was NOT a lot of code. I certainly did get off easy for my first open-source contribution.

✅Creating a Pull Request

I was assigned a mentor when the issue was assigned to me. As this was my first open source contribution I did not want to make any mistake so I reached out to my mentor on Discord. I briefly summed up what I had done, and asked if I should do the fix in another way. He responded and said that my approach seems okay and I should create a pull request, so he could take a look at the changes.

So I staged, commit, pushed, and created a pull request. A few hours later it was merged and I had officially made my first open-source contribution and Hacktoberfest submission.

PS: I thought about if I should write this blog or not because it was a very small, minuscule, and easy fix. Anyways I felt really good and happy about the contribution, so decided to go ahead with it anyways.

✌️Thanks

This is it for this one.

Feel free to reach out to me on LinkedIn, or leave a comment to share your thoughts directly with me. I always welcome criticism.

If you enjoyed your read, then you may wish to check out my other posts at blog.sahej.io. (There are no others at the time, but there will be more in the future ;) )

Wish you a happy day ahead!