Where can I find requirements specification for Open Source software?
-
21-03-2021 - |
italiano
english
français
española
中国
日本の
العربية
Deutsch
한국어
Português
RussianFrage
I can hardly imagine a software project where the things to do are not somehow collected in a formal/informal document, be it a SRS or a simple note. So I was searching for these requirements documents for some well-known Open Source applications (e.g. Signal, GIMP, VLC, ...). As the Source is open, I guess engineering documentations can be as well, be it according to Waterfall, Agile or other methodologies. But I have not found any. So where are requirements captured for open source projects?
Lösung
Don't let the software prevent you from seeing the projects.
I challenge the idea that you need requirements for a software. And suggest that requirements are for software projects. And that there are many software projects in the making of a software. Of those, only one was the inception, and that one is often the worse documented.
Alright, perhaps from a more philosophical point of view, software have requirements from the moment the idea of them is conceived is the mind. But you are not getting to see those. For a practical stand point, there will be projects.
Free and Open Source software has multiple ways to advance. The software is the software (across all its versions and editions), but each change is a project. Each one of those projects has requirements.
Bug Reports.
There are people who test and use the software, and submit bug reports (issues). Fixing them becomes the requirement for the project of, well, fixing them. Some time a change is done to address multiple bugs, in essence collecting those issues are requirements for a single project.
Ah, but let us talk about adding features…
Road-maps.
It is common that a lead programmer will have a road-map of features to add. Which could be public for everybody, could be shared only among maintainers/core developers, or could be entirety private. The core developers will work towards the what is laid out in road-map.
Proposals.
You will also find the issue system co-opted for feature requests. In fact, the practice of writing proposals for change as issues is becoming widespread. These proposals are usually more detailed than a road-map. You can consider them RFC documents.
The issues, in the issue tracker. Be them bug reports or proposals for new features. Those are requests for change. They bring new requirements (or remind of old ones in the case of regressions). To implement those changes, we do projects (with design, and testings, programming, etc). To reiterate, each one of those projects has requirements.
TO-DO lists.
Some of us will have private, never seen by the public, TO-DO lists. Which can be as detailed as needed. Those can be considered requirements, but they never get to the repositories.
For example, I may turn an issue into a TO-DO list, work on it, and delete the TO-DO list when I'm done. Oh, and let me tell you about moments of inspiration. I've learned to portray these ideas quickly. Formalism may take too long. And the idea can be too large to implement quickly. I find the TO-DO list format useful in those cases.
Ah, by the way, some tools can pull TO-DO items from source code comments. Keep an eye for those.
Pull requests.
Contributes may come from outsiders. As third parties can fork the repository, modify the source, and then have those modifications incorporated into the official repository (with approval of its maintainers). This process is formalized as pull requests. How did they manage the requirements for those changes? Each developer does it their own way.
In fact, you may find common that they only express the requirements after the fact. Often to explain what the change does, in order to have it approved. And that can be dealt with in a conversational manner, instead of formal document.
Milestones.
Furthermore, you will find milestones. Usually corresponding to major releases. For a milestone a set of issues (bugs to fix, or features to add) is selected. You may consider all those as requirements for the next release.
Tests.
For some folks following TDD, the tests are the requirements. Even for those of us who don't follow TDD, having the code pass all tests is often a requirement for a new release. Thus, those are requirements expressed in the very formal language of actually executable code.
I remind you that automated tests, unlike requirement documents, are very good at telling you something is broken. Ah, yes, put writing tests in your DO-DO list, and require tests to have pull requests approved.
After all, both design and tests should come from the requirements. And if I don't have to do estimation, or have my project approved by management, or negotiate requirements with a client… I could start expressing my requirements in the form of automated tests, interfaces and other forms of code contracts. So I get to writing code faster.
I'll also remind you that many open source software come from a personal need. In many cases, the founders of these project started them because they needed the software, other times the founders really wanted to create the software out of passion.
And I'll remind you that not every developer is a software engineer. Not everybody needs and is trained for formality in methodology.
I hope it is not hard to imagine for you that the requirements for new born software can be "it helps me in my situation". At the start it could have no formal iterations or milestones, those thing you can added to the workflow later. At the start what matters is whatever or not the software is an improvement over nothing for whatever the founder is doing.
So, no, you are not going to find a requirements document for the entire software. However, you will find requirements for releases, or for particular changes. Don't let the software prevent you from seeing the projects.
Andere Tipps
Requirements don't need to be captured in a formal software requirements specification or any other kind of document. They can be captured in tests (primarily acceptance tests and system tests, but perhaps also integration and unit tests), issues (feature requests, bug reports), discussions (both persistent like mailing lists or ephemeral like chat rooms), or by pointing to features in other software products and cloning them.
Depending on the project type and history, you'll see different ways to capture requirements. A project that was started by one or two people to solve a personal problem but then open-sourced is different than a project started by a large company to make money. Projects that are built to someone else's needs or specifications are different than products generally made available in the marketplace. Projects with a core, dedicated team that ultimately controls the product are different than projects that are maintained by one person or a small number of people who otherwise don't work together. These differences lead to differences across the methodologies used.
I'd also point out that the vast majority of methodologies aren't designed for open-source projects. They make key assumptions about the location, size, structure, working hours or allocation, and skills of the team members that may not be true for open-source projects, especially large open-source projects.
Some good answers here already, especially for your question where requirements are found in Open Source projects. Let me say something about a reasons, why is it hard to find a formal spec document for such projects.
SRSs make most sense in projects with an economical interest between two parties. Some customer / client / employer requires some software and may be willing to invest some time and money. But to make sure they will something in return which will have enough value to balance the invested money, they are asking a potential contractor or employee for a detailed description of what they will get in return, something which is detailed enough for making a contract or to justify the expected effort. That's typically the primary motivation behind creating a requirements specification.
In most Open Source projects, especially FOSS projects, the motivation behind the development is usually different. Most often, FOSS authors are not having the primary interest of selling their programs to someone else, otherwise they would not disclose the whole source code. Often are trying to develop something for a domain they are interested in for themselves, maybe for educational purposes, maybe for solving a problem they are personally interested in, maybe for research purposes, for cooperation with others, or for building some reputation.
I think it is quite obvious that in the latter situation a detailed spec is way less important than in the former situation. That does not mean each commercial project will always have a detailed spec, or FOSS projects never have one, but it means that in FOSS projects chances are way lower to find a formal spec than in closed-source commercial projects.
To learn more about the typical motivations in FOSS projects, I would recommend to have a look into Eric S. Raymond's book "The Cathedral and the Bazzar".
The main way is through comments in the code, and the readme, and 'issue trackers'.
Someone usually starts the project, on their own. They have an idea where it's going, and they build it, and release it. This is now 'the specification'. Any question you have is answered in any comments, any tips in the README or in the functioning of the software.
One of the big differences between humans and current 'computers' is that humans can easily form a model of what the software is doing and should do and could do. I have no 'study' to back this up, but 'it is known' that these models will be quite consistent between different humans, and the inconsistencies our handled by simply issues on the tracker, or by actual pull requests expressing a human's vision of the project.
In fact, the book Culture Code does study this and found that often for simple collaborative tasks like 'stack the spaghetti into the tallest possible tower, kindergarteners did BETTER than adult teams who were 'commandeered' by a forceful 'leader' or where everyone 'discussed strategies to achieve the highest possible tower'. The kindergarteners just kind of worked together and piled stuff on and tried things and within the time allowed got better results.
So this is how the projects begin, and then as they're more complex, they are not managed as a 'full specification' but rather as individual features where 'humans agree it fits the mental model of the software', and where comments in code and issue trackers are added where complexity demands things being specific.
Very few OSS projects grow to a point beyond where this is not practical, and for those who do, they typically just make roadmaps and milestones and discussion groups, and each dev specializes in the 'area' and so they are trusted with the details. It is in fact a tough task when a dev leaves, to 'pass on the mantle'. Typically the 'replacement dev' will simply study the existing code/functionality until they teach themselves the concepts, and so they're then likely to add more helpful comments and maybe notes in a README, and it goes on.
The minimal requirements are complete code that compiles and can be built, producing the usable executable. This does not need to be the a script to run (while often is) but it should be enough documentation to make this manageable.
The "open source" project you cannot really build (with some code or build scripts intentionally removed) is theoretically possible if you are the sole owner of the code, but this is very much against the spirit and may bring no benefits in comparison to just having it proprietary.
My two cents - Github Issues
I have seen various open-source software collecting their requirement through GitHub issues, or at least when anyone posts any issue, they create a new issue or wiki with the detailed requirement(and they can link to/mentioned in other issues as well, thus creating a link). I can't think/find of any such issue, to give you an example. But here's a list of some issues, which might give you an idea.
Kubernetes - Support port ranges in services #23864
Kubernetes - Allow RegExp or wildcard for ingress domain and/or path #41881
Open
Terraform - Storing sensitive values in state files #516
Kubernetes - Is sharing GPU to multiple containers feasible? #52757
As other answers note, it's unusual for formal specifications to exist. But there are noticeable exceptions. For instance, GCC tries to implement the ISO C and C++ standards. These standards are written much like requirements, and typically distinguish between requirements and recommendations.
The catch here is that the requirements are not written (solely) by the GCC team.
