Writing good documentation and communicating with your users is a great way to ensure that people enjoy using your project. This article will go over some of the ideas I’ve found useful in working with the Rust programming language and its community.
Want to know how to make an open source project? You’re in the right place. With a lot of projects that aren’t very well known, it’s important that you know where you can go to get support, pull requests, feedback, and more. This book is going to cover what does and does not work when you are trying to build a solid foundation for your project. If you’re looking for a quick way to learn about how to make an open source software project then this is the book for you. It will give you the information you need in order to get started and make sure that you are prepared for whatever comes once people start seeing your project!
Why do people open source their work?
There are many reasons why a person or organization would want to open source a project. Some examples include:
- Collaboration: Open source projects can accept changes from anybody in the world. Exercism, for example, is a programming exercise platform with over 350 contributors.
- Adoption and remixing: Open source projects can be used by anyone for nearly any purpose. People can even use it to build other things. WordPress, for example, started as a fork of an existing project called b2.
- Transparency: Anyone can inspect an open source project for errors or inconsistencies. Transparency matters to governments like Bulgaria or the United States, regulated industries like banking or healthcare, and security software like Let’s Encrypt.
Open source isn’t just for software, either. You can open source everything from data sets to books. Check out GitHub Explore for ideas on what else you can open source.
Determine the goals
Every open source project solves a specific problem. Talk with colleagues, chats, forums, and share your idea. It all helps you on the first steps to understand important things, like which solutions already exist, and to hear criticism. Talk with people who already have open source projects. They can give you very valuable advice, so don’t be afraid to ask and take the initiative.
One important bit of advice which I got at that stage is to pay attention in the first place on the documentation of the project. You can have a very good project, but no one will spend the time to understand how it works.
The most important aspect, without which further steps are impossible, is motivation. The idea of the project should inspire you primarily. Most often people get used to the tools with which they work and fall into a comfort zone, so external opinions may be ambiguous.
Well Designed README
README.md is the first thing anyone sees. Make sure to catch their eyes right away.
It’s harder to gain traction based purely on the merit of the tool rather than on the presentation of the tool.
For frontend applications, you should focus more on the design of the frontend rather than the
README. This is for CLI applications.
A well-designed README answers these questions succinctly:
- What does this do?
- Does it solve my problem?
- Does it solve my problem better than the competitors (if they exist) do?
- How do I install it?
- What are the basic commands I need to know?
- Where can I go for more help?
Choosing a license
An open source license guarantees that others can use, copy, modify, and contribute back to your project without repercussions. It also protects you from sticky legal situations. You must include a license when you launch an open source project.
Legal work is no fun. The good news is that you can copy and paste an existing license into your repository. It will only take a minute to protect your hard work.
When you create a new project on GitHub, you are given the option to select a license. Including an open source license will make your GitHub project open source.
The choice of a certain task manager is a matter of taste. It should have a clear picture of the tasks and stages of your project.
Divide tasks into sub-tasks. Ideally, if one task does not take more than 3–4 hours, it is important to enjoy the implementation of small tasks. This will help to avoid burnout and loss of motivation.
I use pivotal tracker. The main advantage is a free version for open source projects where you can sort tasks by type (feature, bug, chore, release), and group them into releases and determined deadlines.
Writing your contributing guidelines
A CONTRIBUTING file tells your audience how to participate in your project. For example, you might include information on:
- How to file a bug report (try using issue and pull request templates)
- How to suggest a new feature
- How to set up your environment and run tests
In addition to technical details, a CONTRIBUTING file is an opportunity to communicate your expectations for contributions, such as:
- The types of contributions you’re looking for
- Your roadmap or vision for the project
- How contributors should (or should not) get in touch with you
Using a warm, friendly tone and offering specific suggestions for contributions (such as writing documentation, or making a website) can go a long way in making newcomers feel welcomed and excited to participate.
First off, thank you for considering contributing to Active Admin. It’s people like you that make Active Admin such a great tool.
In the earliest stages of your project, your CONTRIBUTING file can be simple. You should always explain how to report bugs or file issues, and any technical requirements (like tests) to make a contribution.
Over time, you might add other frequently asked questions to your CONTRIBUTING file. Writing down this information means fewer people will ask you the same questions over and over again.
Link to your CONTRIBUTING file from your README, so more people see it. If you place the CONTRIBUTING file in your project’s repository, GitHub will automatically link to your file when a contributor creates an issue or opens a pull request.
This class goes over the basics of how to make an open source project. We will cover some of the theory and history of Free Software as a bonus, but mostly focus on the practical steps you need to take to get a project started.