How a two-year repository on GitHub has become a trend in 48 hours

GitHub has provided an opportunity for millions of developers to easily publish their projects and thereby attract users and like-minded people. Often, developers face the problem of inefficient use of resources - they spend hundreds of hours creating a project to promote it to GitHub, and get a maximum of two stars.

I found myself in exactly this situation, developing a project for the non-profit organization Hack4Impact . This is a student group that works on technical projects for public organizations. Together we developed flask-base, which was used as template code for all our products. The database included the main elements of the flask of the web application: SQLAlchemy, Redis Queue and user authentication (along with several other functions).

You can familiarize with our repository under the link.
')

Flask-base backend demonstration

The flask-base developed by us belongs to the category of “plug and play”, which is its main advantage. Installing a workable version on a computer is not a big deal (and it can be run on a hosting such as Heroku). In addition, the base is extremely minimalist compared to peers, it is very convenient to customize it.

The development of flask-base took two years and served as a template for 90% of our technical projects. The project helped to implement products for organizations such as Kiva , OSET , Juvenile Law Center , Givology .

We were able to help America’s public organizations achieve the social influence they sought. Despite all our attempts to popularize our code, flask-base remained unknown in wide circles, but became useful for people working with it.


Where did we start

Our failed attempts to expand the audience led to despair, as we were confident that other developers and small companies could use the fruit of our work for meaningful projects. But we could not find a way to promote our product. As a result of this, we have questioned the honesty of open source sources that should highlight great ideas for a wide range of consumers.


That feeling

Subsequently, we discovered the error of our approach. We carefully studied how open source works from the user's point of view. We found key areas that needed to be fixed and refined our project to make it suitable for

In this article we want to show how our flask-base took its leading position on GitHub. If you have a significant project, you can easily use our experience and get the most out of it.

The path begins with research

We started with an analysis of success stories. Popular repositories on GitHub have similarities:

• Product overview contains illustrations and gifs;
• Documentation;
• Static code analysis;
• Clarifying instructions;
• Well described installation instructions;
• Logo.

Breakdown of the first lines of the README

I want to draw your attention to some of the best GitHub repositories:

• React-Router : more than 19 thousand stars, 4.5 thousand forks. ReactnRouter is useful in the context of managing individual web application pages, and is also a rare repository that serves as a tutorial on the use of structure. It also contains a comprehensive installation guide, along with recommendations for errors that users may encounter.
  
  
• Webpack : 23.5 thousand stars, 2.7 thousand forks. Webpack can be called one of the best front-end development tools, thanks to its reliability and design capabilities for a variety of browsers. README consists of dozens of characters and examples of the use of cases with links to documentation. Webpack also emphasizes the role of society in supporting the project (in particular, they have a Sponsor and Backer section)

Now we give an example of a failed repository:

abhisuri97 / leARn : I chose my own repository as a bad example - Hackathon project, which won PennApps XIII VR / AR and got into Top 10. It was the only project I developed on Unity, which has a huge number of extraneous unnecessary files. Along with a detailed description of the project functional, he does not explain how the project works on specific systems and what its functions are.

After analyzing the many repositories and monitoring the main trends, we identified a key concept: the developer studying your repository needs a good reason why it should try your project, that is, in understanding that the product is as simple as possible and easy to install.

AGD (Attention Grabbing Device - Attracting Attention Methods)

Eloquence and README :

In the past, I took part in contests of oratory, one of which was called "Original Oratory" ("True Eloquence"). It was required to recite the jury 10-minute speech of his own writing. Each of my performances began with a 2 minute introduction. Most often it was a story that preceded the theses for speech, which I am going to cover.
Essentially, the README is your project AGD!

README is the first thing the user sees when accessing your repository. In this regard, it is worth paying close attention to its content.

But what is paramount and how to capture the user's attention? When familiarizing with your project, the user should know:

• what is it;
• how good the code is;
• what support is available;
• what is included in the project;
• what does he look like;
• how to install the project.

Let's go through all the points in more detail.

What is it


A huge logo immediately tells about your product.

The simplest question is about repositories, but many people misinterpret it. Your project is one of millions of existing. You have very little time to impress.

Describe your project in tweet (about 140 characters) - without unnecessary details: for them, a feature section is set aside. The logo will also help because he highlights the name of the project among the black-and-white text README (and also shows your efforts made to create it).

How good is the code

The same question that 90% of the repositories are not able to answer. While the definition of a “good” code is subjective, there are several basic characteristics:

• it is well tested;
• Passed style check (ESlint);
• it can be compiled in its current form;
• It has passed static analysis (through services such as (Code Climate).

Code Climate Dashboard gives you an average code quality score

It is not interesting for developers to thoroughly study your code before using it. As well as the "characters" on the first line of the project. The peculiarity of these symbols is their ease of use, which makes the project really reliable in the eyes of the visitors, and they do not need to waste time learning the code itself.

What technical support is available

Support consists of two types: problems and training for the user. Support for problems can be implemented in the FAQ. But for new projects there is no possibility to find out the hidden problems of the old code (and there is no content for the FAQ). The only solution in this case is to answer questions in the course of their occurrence and fix bugs promptly.


Documentation flask-base created with mkdocs

The second type of support is documentation. This task is very laborious for developers, but it is extremely important in the context of the popularity of the project (and should be written anyway).
The easiest way is to create documents in mkdocs, and you can generate gh pages from the mkdocs CLI, which you can later transfer to GitHub hosting.

Users will get good examples of how to use the project and get familiar with the explanation of the subtleties thanks to well-written documentation. And also it will be a detailed guide to the launch of the project (if this is a web application).

What is included in the project


X for Y

The list of features should contain key features included in the demo version, that is, should not be overly extensive. Maximum 10 points in the format "X for features Y"

What does he look like


Demonstration example of editing function of the flask-base admin page

A picture is always better than a thousand words, so it’s best to do a .gif. Show how the application works, even if it is an exit from the command line. This information will provide an opportunity for the developer to see a) how the project will look like b) is suitable for his needs.

Do not underestimate the impact of good graphics on the choice of the developer in favor of your project.

How to install the project


Copy repository
Initiating virtualenv
(If you are working on a Mac) Make sure you have xcode installed
Add environment variables
Create a .env file containing environment variables using the following syntax: ENVIROMENT_VARIABLE = value. For example, mail environment variables can be set as follows:
We recommend using Sendgrid as an SMTP mail server, but any other server will also work without problems.

In the development process, you work on a single computer on which all the necessary utilities are already installed. But the user should be able to install your project and start working with it in 3-4 steps. If this involves creating a MakeFile, do it. You should definitely warn if you have used “global” tools, such as babel-cli, babel-core.

According to the basic rule, if you had to use them, then others will have to do it. Do not forget to compress the scripts into a single file (for Python, this is requirements.txt, and for node / javascript is package.json). In short, the installation of the project should take no more than 5 minutes.

How to get to the trend

Retain users will help you AGD (README). But how to attract users to your project?

There are three solutions:

• Hacker News / Product Hunt: both provide an excellent opportunity to highlight the project for the interested community of developers (and get a media review). But there is the difficulty of getting into the tops - placement and promotion of the project requires careful planning and help from users at the start.
  
  
• Reddit: the most effective method to get start stars for your repository. But you need to determine the target audience. For our product, this audience was / r / Python , where we easily reached the tops. It is important to appeal to the audience interested in your project. But you need to be careful if you publish your post on such large subreddit as / r / Programming, where your post can easily get lost among others.
  
  
• Workshops: It's no secret that workshops are a great way to get dozens of stars. Make a workshop on how you created the project, how it functions and how to use it.

Veronica Wharton and I do a Flask workshop on PennApps XV

We used this method on PennApps XV: with the help of a training workshop for creating a web application with Flask. The audience consisted of about 40 people, and we showed our product as an example of a Flask application that they could use during the hackathon. 5 minutes after the end of the workshop, we checked our performance: we received 17 stars and 8 forks, which added to our optimism.

Status monitoring


Comments on improvement. Be nice, share your opinions and enjoy feedback.

Inevitably there will be someone who finds bugs after the launch of your project. Make sure that you answer all comments and take into account feedback. Being in touch with the audience is key to getting feedback from users. If you get a rise from 30 to 40 stars in a short period (1-2 hours), then your project has a great chance to become a trend (of course, this information concerns the trend operation algorithms in GitHub).


Top Flask-base trending among Python repositories on Github after 24 hours

Our achievements

• The project went to the tops for python repositories, 3rd place in the trend and top for / r / Python for the week.
• Hack4Impact became the 4th top python developer and 5m among all developers.
• In addition, we have more than 80 clones and 40 forks at the moment.

I can say that this is an incredibly pleasant feeling when you see that people use the code that you helped to write.


Thank you letter received by me


Our analytics on GitHub. Reddit really helped.

If you could not get into trends, do not despair. Just shake and repeat.
Everyone is sometimes lucky, and sometimes not.

If you have attempted to create open source, useful for people, you are already making a great contribution to the world of open source.