Moment For Technology

The most comprehensive open source project creation guide ever

Posted on Aug. 8, 2022, 7:33 p.m. by Mr. Ashley Tomlinson
Category: android Tag: Open source


Open source is the theme of this era. As an Android developer, I have reason to believe that we are the biggest beneficiaries of open source, because the Android that feeds us is Google's open source project. In such an era of open source, even Microsoft, which was the most hostile to open source before, had to embrace open source actively and bought Github to show its determination to open source.

When I was browsing github some time ago, I happened to find that my Github already has 12 open source projects with more than 100 stars and 2 projects with more than 1000 stars. When I look back, I've been working on open source projects for almost three years, and it's been a hard journey.

Late at night and weekends are the main battlefield for my open source projects. My computer and AndroidStudio are the paper and pen I create, and various bugs and issues are the obstacles in my way to excellent projects. I often think about solving a problem until dawn alone. Among them, they have to suffer the sarcasm and questioning of trolls, as well as the deadly serial calls of white whoring parties. Of course, some people will stand up and say a few fair words, but to be fair, the open source environment in China is really bad.

If it weren't for the love of technology and the encouragement of supporters, I'm sure I would have been hard pressed to keep going, just like those creators of open source projects that have faded away, the submission record is forever stuck in the moment.

Therefore, in order to record my arduous journey of open source, as well as to improve the open source environment in China and help more aspiring young people who want to engage in open source projects, I decided to write this experience summary of open source projects.

Why do open source projects

Before deciding to work on an open source project, it's important to ask yourself: Why am I working on open source at all? Whatever the purpose, as long as you have the answer, then you can read on, otherwise the following may not mean anything to you.

Speaking of open source, we have to mention Google, a company with open source spirit. As an American technology company, we continuously export numerous high-quality open source projects every year. At the same time, in recent years, our country's technology companies have also started open source projects, and many interesting open source projects.

So why are the big tech companies actively working on open source projects? In fact, the reason is very simple, nothing more than fame and corporate image. As a technology company with a market value of more than 10 billion yuan, it is embarrassed to say that it is a big company unless it does some open source projects.

So is it necessary for us as individual developers to do open source projects? Before answering this question, it's important to ask yourself: Do you really love doing technology? If your goal in technology is just to support your family, I think taking on private work and outsourcing is better for you. Because doing open source projects is really a pastime for "very bored" people, you will find very little "money" along the way. Only when you truly love technology as a hobby can you appreciate the value and joy of open source projects being cited by millions of people.

So, having said all that, why do we do open source projects at all? Here are my reasons for your reference:

  • Improve your skills.After all, open source projects are like exposing yourself to others, which may not be the right metaphor, but it can improve the quality of your code and your ability to solve problems. After all, if your open source project is actually being used, you are bound to receive a lot of issues and suggestions that you might not have thought of before.
  • Make the project more robust.The great thing about open source is that anyone has the right to see your project's code and make their own suggestions. It's possible to find bugs and make some very constructive suggestions, but it also helps you understand the shortcomings of your project, which will drive the improvement of the project, and the quality of the project will spiral upward and become more robust.
  • Make friends with the same interests.While you're working on an open source project, it's easy to make friends with other open source creators who have the same interests as you. After all, everyone wants to make an open source project better and better. It's very likely that your open source project will be developed and maintained by other open source developers who appreciate it. That way you could be "gay", haha.
  • Help others and increase your influence in the industry.This is also an important purpose for many people to do open source. If you're lucky enough to make a great open source project in an area that gets cited by a lot of people, your reputation in that area is sure to rise, and then there will be anything. See Vue.
  • Demonstrate individual skill level.A lot of people do open source projects because they want to score points in job interviews, especially for big companies. Because by that in just a few hours of the interview doesn't actually very comprehensive study out a person's technical level, and the interview is usually only a few hours, two people face to face talk if this time you can come up with a relatively good open source project, will be a bonus, at least can give the interviewer before the interview to build a good impression.
  • Realize your life value.Open source gives you a lot of creative freedom, with no crazy requirements from product managers, no overtesting bugs from testers, no technical regulations and no enterprise specifications. You can do whatever you think is right or interesting; You can realize your childhood dream of changing the world. You can leave your mark on this world; You can... Open source gives you infinite arena, you can do a lot of meaningful things when hot premise still can't break the law... We can't do things that violate the law, after all, it's important to save our lives, haha.
  • Reap unexpected side income.Although open source is free, it should not be for profit. But have to say there is no economic benefit drive, simply rely on the love of technology is hard to stick to it, especially when you face a lot of pressure in the real life, feelings can be so pale, that is why all the big open source platform for open source provides sponsorship and exceptional channels, after all, open source is also want to make a living. In fact, a good open source project can reap considerable rewards, even a commercial version, licensing, earning service fees, etc. Of course, there are few open source projects that can achieve this step.

How to do open Source projects well

I briefly explained why we do open source projects, and if you have the answer in your mind by now, congratulations, you are a would-be open source creator, so the next step is to explore how to do an open source project well.

I have been working on an open source project for nearly three years, among which XUI, the most successful one, has submitted nearly 600 codes, complete documents and video tutorials, and has only received 2.7K star so far. Therefore, it is very difficult to do an open source project well.

Taking XUI project as an example, I will briefly introduce some metrics to measure the quality of an open source project.

  • Popularity of the project: number of stars, forks, and watches for the project.
  • Project activity: Factors considered here include the total number of issues, the number of open and closed issues, the speed with which issues were answered and resolved, the number of pull requests, and when the project was last submitted.
  • Documentation is complete: is there a wiki or
  • Project stability: how often code is submitted, how often project versions are released.
  • Project potential: number of project branches, project plan, number of project participants, etc.
  • The quality of the project code: whether the design is reasonable, whether it conforms to the principles of design pattern, considering the scalability, convenience and stability of the project.
  • Level of open source author: star volume and industry influence of author's other projects.

Only by understanding these metrics can we create better open source projects. Having said all that, how do we do an open source project well? Keep reading!

1. Choose the right open source hosting platform

Open source hosting platform to Github as the first choice, code cloud as backup.

Although there are many hosting platforms for open source projects in the market at present, such as Code Cloud, code market, GitLab, BitBucket and SourceForge, I strongly recommend Github. After all, Github is used by the largest number of people, who would not like to create their own open source projects can be seen by more people. Although Github is an American enterprise, there is a risk that it will be banned in the future, but I believe that a country that advocates freedom and democracy will not be able to ban the open source platform smoothly. After all, open source has no borders and should not be politicized or commercialized. If you're worried that Github will be banned in the future, you can simply import your Github project to the code cloud as a backup. After all, the code cloud is nationally recognized and reliable.

2. Good idea or concept

If a feature or thing needs to be repeated every time, but there is no good solution or wheel, then we can try to do one.

A good open source project is born to understand a problem. If you have a good idea or concept, you will attract more people to your project, which will attract more people to your project, which will make it difficult to keep your project from becoming popular.

I created XUI in the hope of simplifying the difficulty of Android interface development and improving the efficiency of Android interface development. I believe that those who have made Android know that Android native components are not favored by designers in China, and the Material Design style promoted by Google is even less popular. As a result, the prototype drawings provided by designers are almost all of IOS style. What's more embarrassing is that, There are few open source UI libraries for Android on the web, and almost all of the basic components need to be rewritten. It happened that I came into contact with React and Vue at that time, and found that both of them had very convenient UI libraries. By modifying the sample code directly, I could roughly achieve the effect I wanted, which greatly improved the efficiency of development. Later, I borrowed the ideas related to QMUI, and finally created the open source project XUI.

Therefore, a good idea or concept is very important for open source projects, can be said to be the soul of open source projects.

Good design and code quality

If a good idea or concept is the soul of an open source project, then a good design and code quality are the bones and flesh of an open source project.

3.1 Master design patterns

To have good design, first of all you need to be very proficient in design patterns, so how can you master design patterns proficiently? Here are some lessons I can teach you:

  • 1. Start by understanding the basic principles of design patterns. Here I have a blog about design pattern principles for your reference.
  • 2. Secondly, I will preliminarily learn more than 20 existing design patterns and try to use them in daily work or open source projects. Here I have an open source project dedicated to the use of design patterns, which has the corresponding introduction and source code for your reference.
  • 3. Finally, when you are proficient in using the above 20 design patterns, forget them and review the basic principles of the previous design patterns and use them as the basic principles of future project design.

In fact, learning design patterns is very similar to practicing a martial arts skill in martial arts novels. Learning design principles is to practice the mind and internal skills, while learning ready-made design patterns is to practice the skills. Only by improving your internal skills, remembering your mind and forgetting your moves can you truly master the art of design patterns.

3.2 Strict code specifications

The easiest way to improve code quality is to strictly follow common code specifications. Here I recommend the Alibaba Java Development Manual and its IDE plug-in P3C project.

Following common code specifications makes it easier for multiple people to collaborate on open source projects. Unless you want to maintain the entire project by yourself, your code is so poorly written that no one can understand it.

4. Rich cases or test cases

As a qualified open source project, it is necessary to provide some unit test cases, because there is no special person to test your writing. If there is no corresponding unit test case, how can you ensure that your writing is not a pit?

If your project isn't a good place to write unit test cases, then you'd better provide a wealth of use cases to make your open source project more attractive and give others something to work with. Otherwise, there's nothing to write about. What's the point?

5. Good documentation

The documentation here consists mainly of README (introduction) and Wiki (usage documentation). Here are some basic requirements for the document:

  • 1. The document should be as concise and structured as possible, and placed in a prominent location for others to find.
  • 2. Documentation should be updated in time to avoid inconsistency between documentation and code.
  • 3. Provide documentation in multiple languages, at least in English.

5.1 the README to write

README is a portal to open source projects, and everyone gets to know your open source projects by reading your README. It's important to remember that a good README can be directly related to how long someone spends on your open source project's homepage and whether they give your project a little star.

If you've never written a README before, I recommend the Standard README, a textbook project written by a foreign writer.

So what does a well-written README contain? The following is my summary of experience for reference only:

  • Project summary (mandatory) : In a few sentences describe the features, strengths, and goals of your project (what kind of problem to solve).
  • About author (optional) : This is where you can promote yourself or other projects.
  • Project Background (optional) : Here you can write about why and how you created the project.
  • Project Features (must) : This is what sets you apart from other projects. Write about your unique features, strengths, ideas, etc.
  • Project design (optional) : Here you can explain the design idea and concept of the project. You can use flowcharts, mind maps, UML class diagrams, sequence diagrams, etc.
  • Project demonstration (required) : This is the place where others can feel the charm of the project most intuitively. Here are five ways you can demonstrate.
    • GIF animation demo
    • Video presentation
    • Images demonstrate
    • The online demo
    • Download the Demo
  • Integration/Installation Guide (required) : Here you have to tell someone how to use your project quickly.
  • Use documentation (required) : This is where you need to tell people how to use your project correctly, in as much detail as possible. Of course, if the content is too much, it is recommended to use a link to the first page of the document or a video tutorial, which may be more friendly.
  • Related projects (optional) : this is your place to promote other open source projects and make your project's fan base grow. Don't miss it.
  • How to Contribute (optional) : Contributions are made in two ways: code contributions and rewards and sponsorships. For code contributions, you need to write out your submission guidelines and code of conduct to avoid unnecessary hassles.
  • Special Thanks (optional) : Thank the people or project addresses who helped or inspired your project.
  • Contact Information (optional) : Here you can write the QQ technical exchange group, wechat public account you created for this project.
  • License Notice (optional) : Here you can write the open source license for your project or the scope of the license (e.g., no commercial use, study only). If you have a free or commercial version, you can explain it here.

For details, you can refer to XUI project's README or my README template.

5.2 the wiki to write

Writing and updating wikis is very important. Wikis are best written in modules that are clear, hierarchical and easy to understand.

I'll take a quick look at how wikis can be written using my other open source project, XUpdate. If you document online, you can skip this one.

A wiki can be divided into three sections, as shown in the figure above, with a brief description of the project at the top, the first page of the document on the left, and the contents of the document on the right. In order to be lazy, I copied the document catalog on the right side of the document page on the left.

Here's a quick list of what should be included in our wiki:

  • Summary: Although the summary here is mostly duplicate of the README, it's best not to miss it.
    • Project introduction: including project description, project characteristics, project background, project design ideas and other contents.
    • Integration/Installation guide: If your project is a wheel library, write an integration guide. If your project is a complete project, write an installation guide.
    • Project demo: GIF animation, video, picture demo, online demo and demo download two-dimensional code to choose a few items.
  • If you are using
    • Basic usage: As the name implies, an introduction to use that meets the most basic requirements.
    • Advanced use: This section mainly introduces some personalized (customized) and in-depth use operations.
    • Frequently asked Questions (FAQs) : It is very important to organize faQs, which are usually generated from common issues in the issue or technical exchange group. It is very useful for people who are new to the project.
  • Infrastructure: A good open source project will build its own ecosystem, which is where the infrastructure becomes necessary.

6. Proper version management and planning

New releases shouldn't be released too often or too long between releases, as random releases can be disastrous for users.

The best thing to do is to release the latest version on a regular basis, with updates on the progress of the project and future development plans, after ensuring that there are no problems with adequate testing.

Here are some suggestions for your reference:

  • Each time a new version is developed, it is recommended to pull a separate dev version branch to reduce the impact on the main branch.

  • You can use Github projects to plan your projects.

  • You can create a top issue in Issues to collect user feedback and use it as planning material for new version development.

  • Be sure to provide a detailed version log every time a new version is released for users to refer to and track. At the same time, there must be a clear explanation for several large version adjustments, otherwise users will be very confused.

7. Pay attention to feedback and keep it updated

7.1 Deal with issues in a timely manner

Issues is a bridge of communication between users and project developers. Many issues put forward by users are of great construction significance. Timely and efficient disposal of them can make our project more perfect.

In the process of dealing with issues, we can collect and sort out "frequently asked questions", gain good ideas, and understand the shortcomings of our own projects. This requires us to pay attention to and deal with the issues raised by users in a timely manner.

So how can we deal with issues quickly and efficiently? Here are a few suggestions:

  • 1. Provide issue template to filter invalid issues and improve communication efficiency. Here you can refer to XUI's issue template.

  • 2. Customize the issue labels and manage the issues by category. Some issues can be processed first.

7.2 Welcome PR and handle PR in time

In the early days of open source projects, it was not difficult for one person to maintain a project. Once the project is hot, it is far from enough to maintain the whole project only by one person's energy, which I have experienced deeply.

Therefore, we need to provide PR submission norms and codes of conduct, and actively welcome more people to participate in the maintenance of the project. Meanwhile, for PR proposed by others, we should review and verify it in a timely manner, and for the submission of no problems, we should timely include it in order to improve the enthusiasm of others to participate in contributions.

8. Promote

The adage that good wine needs no bush doesn't work in the Internet age. No matter how good your ideas and design are, no one will see your open source project if you don't promote it well.

I have a lot of experience with how to promote my own open source projects. Here are a few ways to do it:

  • Constantly post articles about open source projects in technical forums, blogs and communities. I often use several platforms: CSDN, Nuggets, Sifu, Jianshu, Zhihu, bilibili.

  • Submit your project request to be included in some open source project recommendation sharing platform. For example, my open source projects XUI and XUpdate were submitted to HelloGitHub.

  • Start your own open source community. You can create QQ groups, wechat public accounts or community websites to promote your project.

  • Join a well-known organization. For example, I joined the B3log open source community.

9. Stay true to why you started

Working on open source projects is a very long process, and you can't possibly imagine the twists and turns that lie ahead.

If you've been working on an open source project for a few months and no one is interested, don't be discouraged. Just focus on doing what you think is valuable, and eventually someone will find it.

If your open source project is successful, and you get a lot of praise, you're going to get a lot of trolls and a lot of mindless trolls. Don't pay attention to those muggles who can't do anything but spit. Don't devote your limited energy to them. Focus your limited energy on the people who are giving you valuable advice on your open source projects and do what you think is right.

The last

It took me a whole week to write this article, and I sincerely hope to improve the open source environment in China and help more aspiring young people who want to engage in open source projects. If you find it useful, I suggest you bookmark this article. Finally, I wish you can write your own excellent open source project soon!!

Wechat official account

For more information, please scan and follow my personal wechat public number: [My Android open Source Journey]

About (Moment For Technology) is a global community with thousands techies from across the global hang out!Passionate technologists, be it gadget freaks, tech enthusiasts, coders, technopreneurs, or CIOs, you would find them all here.