Software Quality
Charles Fishman wrote a terrific article They write the right stuff. [1] for Fast Company magazine in 1996 about the "on-board shuttle group" that works at the Johnson Space Center in Houston, TX producing some of the most sophisticated and error-free software in the world.
We'll try to focus on some best practices and quality metrics - especially as it relates to MediaWiki.
Cliff notes for process and tools at WMF[edit]
- MediaWiki/contributing - our local brief on how to get setup on Gerrit
- Development guidelines provides the big picture of policies (MUST) and guidelines (SHOULD).
- Manual:Coding_conventions/PHP covers aspects of how PHP for MediaWiki is coded.
- Code Stewardship is a model adopted in 2018 by WMF as a layer on top of Developers/Maintainers
- Manual:Mwdocgen.php generates the Doxygen output, but the Manual:Coding conventions/PHP doesn't mention anything about comments for static analysis
- The Coverage Dashboard for MediaWiki Core can be found at doc.wikimedia.org This is generated by Sebastian Bergmann's PHP Code Coverage
- doc.wikimedia.org is home to most other generated docs and analysis like Doxygen output and Static Analysis reports by PhpMetrics
- Hook container with strong types and DI (solved) is part of a series of architecture shifts, and is an example of diving into the details of the codebase.
- API:Client_code/Gold_standard is somewhat interesting - a series of metrics and principles applied to the API Clients listed at API:Client_code
Code Health - project[edit]
MediaWiki Code Health (inactive as of 2024 - was active from 2017-2019 and is still part of the CI process and tools.)
The Codehealth Pipeline is part of the continuous integration process, and invokes SonarScanner which send results to SonarCloud (by "SonarQube" a product of SonarSource github).
SonarCloud is pretty cool because it gives a browseable UI to Static analysis (so code coverage and more). You can browse / search for Gerrit-hosted extensions at https://sonarcloud.io/organizations/wmftest/projects
Although useful, it is unclear to the outside observer how much the tool is actively configured to align with best practices or matches up with the other internal / free software tools utilized by WMF (e.g. https://doc.wikimedia.org/#testing). Some background info is at mw:Continuous integration/SonarQube Scanner. According to T379181 there is ongoing work to update WMF repos to use the tool, and also to configure the tool to generate the warnings or gating criteria during Continuous Integration.
According to T373098, as of late 2024 SonarQube only analyzes Testing, while https://doc.wikimedia.org/cover-extensions/ is used to report on both Unit Tests and Integration Tests.
A list of the extensions / repos that are currently scanned: T321837
SonarCloud Dashboards[edit]
The WMF organization account on SonarCloud is at https://sonarcloud.io/organizations/wmftest/projects
Individual repos are like https://sonarcloud.io/project/overview?id=mediawiki-extensions-DiscussionTools
Workboard in Phabricator
Developing on GitHub[edit]
Developing software for MediaWiki outside of WMF Gerrit and related platforms occurs for a lot of reasons - like organizational reasons and simply because industry norms are more accessible to a wide audience by definition. Whatever the reasons, here are some ways people get more quality out of software hosted on GitHub.
Continuous Integration[edit]
On GitHub your CI pipelines are the GitHub Actions and workflows you setup.
Local Runners[edit]
act (nektos/act) allows you to run your GitHub Actions locally in Docker containers that it sets up just like the runners that you'd be using on GitHub.
Why? For one thing, you can develop your workflows (ci pipelines) interactively without having to commit and push ad nauseum. It's very convenient. And, for normal code changes, the same benefits apply. You can run your unit tests, static analysis and code style checks easily. For the ProfessionalWiki/ExternalContent extension, I made a wrapper script to invoke act
Not only can you save time with Act, but you can save money avoiding GHA usage charges.
AI code review[edit]
CodeRabbit is free to opensource projects. It is an AI bot that will critique your code. CodeRabbit isn't an exact replacement of SonarQube used at WMF. CodeRabbit and SonarQube are both code review/analysis tools, but they have different approaches: SonarQube is a traditional, rule-based static analysis tool (SCA) for deep, enterprise-level quality and security, while CodeRabbit uses Artificial Intelligence (LLMs) for faster, more context-aware, and developer-friendly feedback directly in pull requests, handling tedious checks so humans focus on design. While SonarQube handles strict compliance and technical debt management, CodeRabbit will accelerate the PR process with smart suggestions and summaries, though SonarQube is adding AI features too
References[edit]
- ↑ Fishman, C. (2017, September 8). They write the right stuff. Fast Company. https://www.fastcompany.com/28121/they-write-right-stuff
