Source: FreeCodeCamp Developers around the world use GitHub to share their projects. In this article, I will try to give some tips to help you create a great open source project. You can also use these tips to create hackathon projects. Most recently, I ended up on the coveted GitHub Trending page. I was the second trending developer on all of GitHub, as well as in the Python section, which was a very pleasant surprise for me. I was also mentioned in the daily GitHub newsletter after I moved one of my projects to open source. If interested, you can see my repository here .
Find your motivation
Trying to get into the GitHub Trending section is next to impossible. GitHub uses much more complex algorithms during trending than just the number of stars. To get into trends, you need strong motivation. Well, for starters, you can participate in hackathons, create projects, and experiment with other projects. And soon you will find something that could be turned into a library or made into a utility, and so on. Your motivation for creating a project can come from anywhere. For example, I study new articles on machine learning daily on arXiv(archive of open access articles) and read the ones that interest me. One article I read prompted me to create my own Python package. Another time I was at a machine learning model training hackathon and I wanted to participate in something similar. Our team then decided to create another open source project called TF-Watcher. As you can see, there are always some issues to work on when you are looking for a goal for your project. Please note that when I say that you must be highly motivated, I do not mean that the project must be really huge or very complex. It can be quite a simple project that makes life easier for developers. Think of it this way: if there was a project like the one you want to develop, would you use it yourself? If the answer is yes, then you have enough motivation to create a project, regardless of its size and complexity. Not too long ago, a guy from Oakland, California broke web development around the world,removing just 11 lines of code . You may have heard of left-pad, a very small open source npm package with only 11 lines. But it turns out that it was used by many developers around the world.
Explore your idea
Once you find a problem and you have enough motivation to start working on it, you will most likely want to spend a lot of time on your research. But before that, try to answer a few questions:
Does a similar project or tool already exist?
If there is no analogue yet and there is a need for it, then proceed to create it. If something like this exists, is well developed, and is actively used, you might want to look elsewhere. There are a huge number of open source projects on GitHub, and it's not uncommon to find a repository that performs similar tasks (more common than you might think). But you can still work on your project and improve it.
If something like this really exists, can your project improve it?
If there is already an analogue, you can make it more modular or more efficient. You can try to implement it in another language or improve it in other ways. A great way is to look at the issues in this repository. Try to research with existing solutions (if any) and find out what element of the project can be improved. In my case, I took inspiration from an interesting research article I read (Fastformer: Additive Attention Can Be All You Need). I also discovered the official implementation of the code and the implementation of the document by the community in PyTorch. After all, my repository, although derived from research papers, was very different from existing code implementations.
Can you explain your project like I'm 5 years old?
Explaining the essence of your project as if your interlocutor is five years old is a great exercise that I like to do as soon as I have an idea for a repository. I'm trying to explain what the project is trying to achieve, how it works, or why it's better than similar repositories, to a friend who doesn't know much about the subject. It helps me develop or get a clear idea of what I want to do in my projects. Trying to explain a project to a friend often also helps me discover flaws in my plan or assumptions I may have made while thinking about the project. This process also helps me when I start the development phase of a project on the board. To do this, you can use GitHub or Trello, JetBrains Spaces, and so on.
What can you learn from the best repositories in similar categories?
You can often draw inspiration and learn from repositories belonging to similar categories. See how their code is written and structured. In my case, I really liked the way reformer-pytorch was written . It is easy to use in your projects as a Python library.
How to develop a repository for your project
You may have heard Martin Fowler's popular quote: “Any fool can write code that a computer can understand. Good programmers write code that people can understand.” If people can't understand your code, they won't use it. I've noticed in my repositories that when I spend more time making things simple and easy to use, these projects end up becoming more popular. So try to spend extra time on making your project more user-friendly and intuitive. Typically, when developing a repository:
You must add an open source license. It allows people to use, copy, modify and contribute to your project while retaining copyright. You can easily find the right license for your project at Choosealicense.com .
Write a good README: there will be a whole section on this, because it is very important.
Use consistent coding conventions and clear function/method/variable names. Often you can use some kind of static code analysis tool, such as black , ktlint and others.
Make sure your code is clearly commented, document your thoughts, and point out possible problems.
Make sure your changelog, issues, or pull requests do not contain sensitive material (such as API keys, passwords, or other sensitive information).
If you are developing an application/library I would recommend you to use GitHub releases. Try to keep clear release notes and changelogs every time you make a new release so the community can keep track of what's new. Write down what bugs were fixed, and so on.
Finally, you should also include guidelines in the repository that tell your audience how to participate in your project. You can include information about the types of contributions you expect, or how to submit a feature request or bug report, and so on.
How to write a good README
A good README is undoubtedly one of the most important components of a repository. Potential contributors usually check the README first, and only then, if they are interested, look at the code or consider using the project. I don't have a universal guide to writing a README. Just experiment with what works for your project. You will probably want to include these components in your README:
Explain what the project does
Try to describe the project in just 3-4 lines. Don't worry about including too many small details or features - you can add them in the following sections. This is the first thing visitors to your repository read, so try to make it interesting.
Create a great cover image or project logo
If you have a logo or cover for your project, please include it.
Place graphic labels with metadata
You see small icons at the top of the README that convey metadata such as whether all the tests for the project have passed. You can use shields.io to add them to the README. They can add credibility to your project without the need for visitors to look through all of your code.
Add visual effects
You should always try to include visual elements in your README. It can be a GIF showing your project in action, or a screenshot of your project. Good README graphics can really help convince other developers to use your project.
Explain how to install or set up your project
You must also include specific installation instructions. Include any required dependencies and anything else that other developers need to install in order to use your project. If you run into any issues setting up a project or installing a dependency, it's likely that users will run into this as well, so make sure you address that. It can be very simple:
Give clear examples of use
I think this is very important to have in the README. Don't expect other developers to read your code for a long time - make it as easy as possible for them. Always check and double check that your code examples or "How To" section are easily reproducible. Also, make sure it's understandable to a wide range of users, and don't forget to include instructions on how to run it. Since my project is a Python package, I created the included Colab Notebook to demonstrate the use of the package. This allows people to easily try it out in their browsers without having to install anything on their own machines. There are quite a few products that allow you to do this, such as repl.it, Glitch, Codepen, and so on.
Explain where this project can be applied
It is often helpful to list the features of your project and the problems it can solve. You don't need to describe all the features you've worked on, but share the main ones. This will help developers understand what your project is capable of and why they should use it.
Tell how people can get help or contribute to the project
Finally, you should be clear about whether you are willing to approve commits and what your requirements are for them to be accepted. You should also document commands for linting code or running tests. These steps help ensure that code is of high quality and reduces the chance that changes will accidentally break something.
External Documentation
Let's say you think your README is too long. In this case, you can create an additional documentation website and link to it in the README without missing any important information. Since I work a lot with Python, I usually use Sphinx to generate documentation from Python docstrings. I find Sphinx to be quite flexible and easy to set up. There are quite a few options for creating documentation: mkdocs , Docsaurus , docsifyand others. However, for my project, which was starting to take off, I didn't need an external documentation website. Here is an example of what I think would be a good starting README from one of my own projects. This is not a complete README, but what fits in one picture: Finally, for more inspiration, I suggest you try using the Make a README guide .
How to Drive Visitors to Your GitHub Page
Once you've created a nice README and made the project public, you need to think about bringing people to the GitHub page. First, make sure you have added the appropriate tags to your GitHub repository. These tags will make it much easier for people exploring GitHub to discover the project.
Share your project on Hacker News, Twitter and Reddit
Great places to post about your project are Hacker News and Reddit. But keep in mind that getting your post to become a top story or top post on any of these platforms is a difficult task. When one of my repositories became a top story, it got over a hundred stars in a couple of hours. But when I originally posted my repo to Hacker News, I didn't have a single upvote. It wasn't until someone in the community noticed my project and posted it to Hacker News that it became headline news. So it often takes good planning and a little help from friends to get your project to the top. In my case, Twitter was a really great place to get the very first visitors to my project and reach out to an external audience. This often serves as a great way for people to quickly understand whether they might be interested in your project. And you just have a limited number of characters to sell your repository to people. Also, don't go overboard with posting about your project on any platform because it can be flagged as spam.
Feedback matters, but not in the way you think
I often receive emails or messages with responses to my project or book. But I firmly believe that this does not make much sense. If you want someone to leave feedback about your project, first get them to use your project and find it useful. Also add a "tweet this project" button to the README. Then people who like the project will naturally begin to distribute it among their audience. Also keep in mind that reviews don't earn you stars. People will star your project only if they like it. This certainly doesn't mean that you shouldn't ask people for help, feedback, or code reviews. Indeed, you should always try to respond to all kinds of feedback: improvements, bugs, inconsistencies, and so on. Always be willing to accept negative feedback and think about how you can improve it. Maybe you will learn a few new things :) In my case, I noticed an unusually high number of visitors coming to the project from Twitter. My project was implemented with TensorFlow and Keras and after a couple of days I found the Keras creator himself discussing my project! This was most likely due to the fact that I added “Tweet about this project” at the top of the README and allowed it to be shared on social media.
Developer community tips for creating a project on GitHub
As an interesting exercise, I asked the Twitter community for any advice I could include in this blog. Here are a few of them:
(You should add) 1. Documentation 2. Decision logs
Good release templates and PR. You can also use the GitHub release forms.
Documentation (should be complete and) include the application architecture, packaging, style guide, code discussion, references to the technology platform library used, required tokens, and so on.
Conclusion
Thank you for reading to the end. I hope this helps you create your own open source projects. With these tips and experimentation and effort, you can create a great project.
You see small icons at the top of the README that convey metadata such as whether all the tests for the project have passed. You can use shields.io to add them to the README. They can add credibility to your project without the need for visitors to look through all of your code.
Finally, for more inspiration, I suggest you try using the Make a README guide .
GO TO FULL VERSION