Summary: Each of the invariants listed at the top of the `Graph` class is now explicitly checked by `checkInvariants`, which is called at the end of each `Graph` method during tests only. This is powerful: it means that not only do our tests for `Graph` test the graph, but also any tests that depend on `Graph`—e.g., plugin code—will give us extra invariant testing on `Graph`. As noted in a comment, if this becomes bad for performance, we can blacklist expensive tests or whitelist tests that we care about. A graph method may assume that the graph invariants hold before the method is invoked. Within the body of a graph method, invariants may be violated, but the method must ensure that the invariants hold immediately before it returns or yields. A consequence of this is that if a graph function internally calls a public function (e.g., `addEdge` might call `hasNode` to check that the source and destination exist), then it must ensure that the invariants hold before the internal call. This is not an “implementation detail” or “caveat”; it is simply part of the interface of public functions. It is legal and reasonable for private helper functions to explicitly not expect or not guarantee that particular invariants hold, and in this case the exception should be documented. (This is not yet the case in any of our code.) Finally, note that the `checkInvariants` method should not call any public methods, because those methods in turn call `checkInvariants`. If this becomes a huge pain, we can look into implementing some kind of “only check invariants if the invariants are not actively being checked”, but I’d much rather not do so if we don’t have to. Test Plan: Running `yarn coverage` indicates that each of the failure cases is verified. In principle, I’d be willing to add a test that parses the source code for `graph.js` and verifies that each `return`, `yield`, or implicit return is preceded by an invariant check. But I don’t really want to implement that right now. wchargin-branch: automatic-invariants
SourceCred
Vision
Open source software is amazing, and so are the creators and contributors who share it. How amazing? It's difficult to tell, since we don't have good tools for recognizing those people. Many amazing open-source contributors labor in the shadows, going unappreciated for the work they do.
As the open economy develops, we need to go beyond commit streaks and follower counts. We need transparent, accurate, and fair tools for recognizing and rewarding open collaboration. SourceCred aims to do that.
SourceCred will enable projects to create and track "cred", which is a quantitative measure of how much value different contributors added to a project. We'll do this by providing a basic data structure—a cred graph—into which projects can add all kinds of information about the contributions that compose it. For example, a software project might include information about GitHub pull requests, function declarations and implementations, design documents, community support, documentation, and so forth. We'll also provide an algorithm (PageRank) which will ingest all of this information and produce a "cred attribution", which assigns a cred value to each contribution, and thus to the people who authored the contributions.
Principles
SourceCred aims to be:
-
Transparent
If it's to be a legitimate and accepted way of tracking credit in projects, cred attribution can't be a black-box. SourceCred will provide tools that make it easy to dive into the cred attribution, and see exactly why contributions were valued the way they were.
-
Community-controlled
At the end of the day, the community of collaborators in a project will know best which contributions were important and deserve the most cred. No algorithm will do that perfectly on its own. To that end, we'll empower the community to modify the cred attribution, by adding human knowledge into the cred graph.
-
Forkable
Disputes about cred attribution are inevitable. Maybe a project you care about has a selfish maintainer who wants all the cred for themself :(. Not to worry—all of the cred data will be stored with the project, so you are empowered to solve cred disputes by forking the project.
Roadmap
SourceCred is currently in a very early stage. We are working full-time to develop a MVP, which will have the following basic features:
-
Create: The GitHub Plugin populates a project's GitHub data into a Contribution Graph. SourceCred uses this seed data to produce an initial, approximate cred attribution.
-
Read: The SourceCred Explorer enables users to examine the cred attribution, and all of the contributions in the graph. This reveals why the algorithm behaved the way that it did.
-
Update: The Artifact Plugin allows users to put their own knowledge into the system by adding new "Artifact Nodes" to the graph. An artifact node allows users to draw attention to contributions (or groups of contributions) that are particularly valuable. They can then merge this new information into the project repository, making it canonical.
Community
Please consider joining our Discord chat or posting on our forum.