userver – what we learned in six months in open-source
More than six months have passed since the release of the framework for C ++ 🐙 user in open source. During this time, we learned a lot, suffered a lot, and most importantly, received many pleasant surprises.
And we decided to write about it. The story will be useful to those who are running or planning to run their own open-source project or are involved in contributions. The rest will be interesting to read about someone else’s stuffing cones and what open-source gives the project in general.
To make the announcement of the release of the framework in open-source go more smoothly, we posted the sources a little in advance and got busy with the arrangement on GitHub: setting up CI, designing, testing and laying out the documentation. As a result, by the time of the announcement, we already had a ready-to-use service template based on the userver framework with all configured CIs and assemblies.
However, what we did not expect at all was that the source repository would be found even before the announcement. At all suddenlythat some third-party developers have found non-trivial places for optimizations deep in the bowels of the drivers and suggested more productive solutions. We answered them in kind: within a few hours suddenly improved everything and expressed gratitude in the changelog.
beta is good
The needs of the company often do not coincide with the wishes of open-source users. What has been successfully used for years in production within a company may not be suitable for a new user due to a factor that simply does not exist in a corporate environment.
We expected that improvements would be needed after the release in open-source, but we had no idea what exactly our new users would ask for. Of course, there was also technical debt: some things needed to be improved, but it was not clear which debts were the most annoying.
To emphasize that we know that there is something to work on, we have posted the framework in beta status. The decision justified itself: many messages from users fell under the regular line “How do you even give all your best without the \s+ technology. Ah, although this is beta, then OK!”
From the announcement, it was important for us to understand the main pains when trying to use the framework, the main wishes for development and realize what we missed. Well, and show your best side, of course.
Of course, it was not without curiosities. For example, we sent material to the PR department with a general message: “Today we are announcing the release of the open-source userver framework for creating highly loaded IO-bound applications in C ++.” The material, after some transformations, went to the publication as “We announce the release of the world’s first set of tools that allows you to create high-load applications.” Fortunately, we managed to stop the process in time.
We have a board with hand-drawn achievements for dubious achievements – this one appeared just after this story
C++ assembly is very, very painful
The first thing people began to come with after the announcement of the release in open-source was build problems.
If you want to be friendly to at least half of your users, you will have to support:
- at least the top 3 popular OS Linux + docker + MacOS;
- 3 latest C++ standards;
- 2 compilers;
- 2 standard libraries;
- 3 hardware architectures;
- installation by downloading packages;
- use of OS system packages;
- using the conan package manager;
- debug and release build.
This is just one of those problems that practically do not arise inside a large company: someone has already set everything up a long time ago and all things are actually being developed for a couple of platforms. Well, or there is a separate team of people who deal with assembly problems.
And here we did not come up with a simple solution for open-source, so we went along a difficult path: to support, to the best of our ability and capabilities, all the configurations that are of interest to our active users. Special thanks to those who brought ready-made edits for their favorite platforms!
roadmap and changelog
From messages in support chats and from comments to articles, the concern of users with the fate of the technology quickly became clear. After all, if you start using something to solve your business problems, you don’t want it to stop being supported soon.
To show that we are serious, the following helped:
- Setting up automatic synchronization of commits from an internal repository on GitHub. As a result, when you visit the repository, you can see that the last commit was made ~2 hours ago. This is a sign that the project is actively developing.
- changelog. The meaning is the same as the last paragraph – to show the pace of development of the project.
- road map. Helps people understand that the project has a development plan, we are moving towards the release and it is close.
- Telegram support channels. They allow us to listen to the wishes of new users and quickly refine the framework to suit their needs.
Benchmarks are useful
What are the big boys who develop frameworks measured by? That’s right, their performance. There are various resources on the net where you can compare yourself with others, and even get useful information from such comparisons:
- The task for the benchmark could not be implemented concisely? This means that something in the interfaces of the framework can be improved and generalized, made more pleasant to use.
- Lost in performance? What is the decision of the leader? Ah, hmm, interesting, let’s try to do something similar, but here we’ll speed it up a little more…
- Everything is fine, but it is difficult to find the optimal configuration? But it’s not in benchmarks that people face this! Let’s auto-tune parameters to configure a lot less things.
Benchmarks are useless
Oh, since benchmarks are so useful, can the framework choose them directly? For example, in our company we needed a framework on Go/Kotlin/NodeJS/… Let’s take the top of the benchmarks!
The idea is interesting, but in practice does not work:
- Many of the top frameworks have vulnerabilities, and the authors are in no hurry to fix them, because the fix will hit performance and benchmark results.
- Without exception, all frameworks in benchmarks work differently than in production. For example, logging is disabled in all frameworks, and it is very gluttonous on production and has a huge impact on response times, latency and jitter.
- Many frameworks have minimal functionality, only what is needed for a benchmark. If you want to work with another database, record metrics, or take advantage of multithreading, it won’t work.
Finally, my favorite factor is the ease of writing and maintaining the code. Which of these frameworks would you like to write on:
You can’t just go ahead and write great documentation. Depending on the mood, task, and preferences, developers need different styles of documentation:
- First acquaintance with the project. You need a description of the approaches used, why they are effective and what limitations they impose.
- Writing the first services (or for the impatient developer). Here we need tutorials with full and understandable code examples.
- For an experienced user. A reference part is needed, where the details of various methods and classes are painted.
- specific task. We need a section of documentation for a specific problem, tips and options for approaching the solution of the problem.
At the same time, all people are different, and it is desirable to present materials in different forms, for example, as video lectures and as text.
Documentation is not a one-time task. It is necessary to listen to user requests and cover with more examples those parts of the framework for which frequent questions arise. Or to simplify this place in the framework so that there is no need to document it at all.
Support chats go hand in hand with documentation: people ask questions, usually about things that are poorly covered in the documentation, which helps to complement it.
Mutually beneficial learning
Having caught our breath after the announcement and corrected the main shortcomings, we belatedly realized an interesting point. Yandex has many educational projects, for example, School of backend development. Many of these activities involve writing a graduation thesis – some kind of toy service. It introduces the student to industrial development and, as a rule, is not made available to the public.
But after all, if you did a good job, you want to brag about it! Show the code, indicate a line in the resume with a link to the work done.
We joined some of the initiatives with the proposal: “Let’s write real code for the userver as a graduation project.” As a result, if you did a good job, you will definitely have something to brag about and something to show.
True, there were hitches here: we were overwhelmed with code, and we are still engaged in its freezing in userver.
By the way, it turned out to be very useful to mark up feature requests on GitHub as “Good challenge for beginners” and mark separately “Big feature for advanced”. We immediately get a set of tasks for external activities for 2-4 days and a set of projects for large multi-month courses, for example, how “Code for Everyone”.
So why open-source?
Question: “Why did you put it in open-source?” haunts many people in chats and forums. Well, let’s honestly answer everything and sort out all the myths.
Myth 1: Let people develop the framework for us
Alas, it doesn’t work that way. The vast majority of our commits come from internal developers. I, of course, secretly hope that this will change. But, as experience with Boost C ++ Libraries shows, even very popular open source projects take a very long time to reach such a development model and very few people succeed.
At the same time, PR from a third-party user is a small holiday! After all, it means that the project has become interesting and useful to someone else.
Myth 2: for people to test the framework for us
Not without it 🙂 But as with development, here the vast majority of bug reports come from within. Many external bug reports are related to a build or functionality that is rarely used in the company.
If suddenly you have a small project with a fairly narrow functionality (for example, a small library), then open-source will obviously help you to test better. For large frameworks, things are somewhat more complicated.
Why is userver actually posted in open-source
Different projects may have different reasons. First of all, we wanted to show off our development and give everyone the opportunity to use it.
For large companies, open-source is also the development of the company’s technology brand. This way you can show people interesting and useful solutions that we write during working hours. Well, this is also useful when hiring: if you suddenly choose between different Yandex departments, you have the opportunity to see in advance the technologies with which you will work and choose a code to your liking.
And open-source also makes it possible to use the familiar set of tools in partner projects: for example, now there is a chance to use userver when collaborating with CERN, or when automating steel mills.
We are preparing for the first release of the framework this year. In the meantime, the release is still in progress, we are happy to talk about the framework (and not only) at conferences Saint High Load++ And HighLoad++ Serbia.
And if you yourself have something to say, come to us at C++ Zero Cost Conf with a talk idea. We are warm, fun and international! This year the conference will be held in two countries – in Russia and in Serbia. We are waiting for your applications!
Thanks to everyone who contributed and bugged the userver. You are best!