As time goes by, code, pull requests and patches for an open-source project will naturally keep arriving in a steady stream. Depending on the volume of these contributions, some projects end up doing just well with a single maintainer, while others require an entire team of maintainers, each specializing in one of the project’s major areas (see the Linux kernel’s MAINTAINERS file, as an extreme example).
Regardless of contribution volume, one question stays the same: “What are the best ways in which a project can properly thank and acknowledge all of its contributors?” Is our current way of doing this good enough or should we improve upon it?
The OpenSIPS Status Quo
OpenSIPS contributions currently have very loose restrictions. Authors may freely add “signpost” comments to their patches that proudly showcase their names (hint: most devs are apt to solve the “blame this line” problem and some of them can even automate it). Then they may also append themselves and their glorious feats to the top-level file history section — although this is a practice we don’t recommend anymore, as we feel it creates a sense of personal code ownership, which may discourage future contributions from fellow enthusiasts.
Then there are the contributions to module documentation. Module authors are also expected to document their creations, and not put that burden on someone else’s shoulders. In an ideal world, of course. Style of writing? There are hardly any rules, and you have a lot of freedom in expressing yourself while explaining your code for others to use. The good part about writing module documentation is that you get to enlist yourself as a documentation author, right at the top of the web page! Talk about bragging rights!
With regards to the C codebase, our current way of acknowledging our community’s efforts is by extracting all unique contributors and enlisting them in the
CREDITS file, with each major release. This file will then live untouched for 1 year, after which it will get replaced with the next releases’ list of contributors. The
AUTHORS file aims to offer an up-to-date representation of the currently active developers who have both contributed significant amounts of code and who have shown a constant willingness to help and volunteer parts of their time for the benefit of others.
In our opinion, the
CREDITS approach has two big limitations: a lack of visibility and a lack of accuracy. OpenSIPS users (who far outweigh contributors) are simply not that interested in opening up the GitHub project page and scrolling through the
CREDITS files. And even if they were to do it, it would be impossible to correlate any of the information contained within those files with the module they need to use, require support for, and have no idea whom to ask for help.
So the problem formulation becomes: “make all contributors of each module visible and accurately represent their efforts since the project’s inception”. Below is our solution to this problem.
A Better Way of Saying “Thank You!”
We felt like we can do better but, at the same time, we did not want to burden the community with yet another MAINTAINERS file which also needs to be maintained! This is how the “contributor statistics“ idea was born — an automated way of inferring maintainer semantics from the
opensips git repository. Inspired by Mozilla’s Web API documentation contributors section and further improved upon, here is how they ended up looking like:
The “commit statistics” are meant to hint at the volume of work put in by each developer. As we couldn’t just sort by commits or lines added, we had to come up with a scoring system. The resulting formula is:
DevScore = author_commits + author_lines_added / (project_lines_added / project_commits) + author_lines_deleted / (project_lines_deleted / project_commits)
Firstly, the formula properly rewards big-volume contributions by properly taking into account the amount of code that they add or remove. Lastly, it also rewards frequent / contained commits. Developers who are pushing lots of small, well-contained commits simplify the code reviewing process, as their commits are a lot easier to digest. Hence, they should be rewarded handsomely!
This screenshot shows the most recently active contributors to either a modules’ code or its documentation. We believe this will be very helpful in answering questions such as “who still maintains this module?” or “who can I contact if I have questions regarding this module?”. Towards the bottom of the page you will find the “documentation copyrights” section, with the exact same data as before, yet a lot more discreet!
The statistics are updated every Sunday by the “opensips-github” bot, set up by our very own Vlad Pătrașcu! They are fully re-computed for each of the
master branches and accurately represent the project’s history from its very beginnings, all the way back to the first commit of the SER project. We hope that you will find this feature useful and we definitely appreciate any kind of feedback on it!
The OpenSIPS team