1002b16b81
Introduces the Works On My Machine certification framework, including: - CLI tool for project certification and badge/certificate generation - Certification checks per WOMM-STD-001:2026 standard - Supporting documents, assets, and tests - Python package setup with pyproject.toml
483 lines
15 KiB
Markdown
483 lines
15 KiB
Markdown
# WOMM-STD-001:2026
|
|
|
|
## Works On My Machine — Certification Standard
|
|
|
|
**First Edition — 2026-04-02**
|
|
|
|
Published by the **International Bureau of Local Development Assurance (IBLDA)**
|
|
on behalf of the **WOMM Standards Committee (WSC)**
|
|
|
|
---
|
|
|
|
> *"It works on my machine."*
|
|
> — Every developer, at some point
|
|
|
|
---
|
|
|
|
## Document Classification
|
|
|
|
| Field | Value |
|
|
|----------------------|--------------------------------------------|
|
|
| Standard Number | WOMM-STD-001:2026 |
|
|
| Edition | First |
|
|
| Status | **ACTIVE** |
|
|
| Classification | Public — Developer Eyes Only |
|
|
| Supersedes | Verbal assurances, Slack messages, shrugs |
|
|
| Committee | WOMM Standards Committee (WSC/TC-1) |
|
|
| Secretariat | IBLDA, Geneva (or wherever the laptop is) |
|
|
|
|
---
|
|
|
|
## Foreword
|
|
|
|
The WOMM Standards Committee (WSC) was convened in response to an
|
|
industry-wide crisis of confidence in the phrase "it works on my
|
|
machine." For decades, this declaration has served as the final word
|
|
in software dispute resolution, yet it has lacked the formal rigour
|
|
demanded by modern engineering practice.
|
|
|
|
This standard provides a comprehensive framework for evaluating,
|
|
certifying, and communicating the operational status of software
|
|
within the confines of a single developer's workstation. It is the
|
|
product of extensive deliberation by experts from such distinguished
|
|
fields as "closing the laptop and hoping for the best" and "I swear
|
|
I didn't change anything."
|
|
|
|
The WSC acknowledges that this standard cannot guarantee software
|
|
will work on any machine other than the one on which certification
|
|
was performed. This is, in fact, the entire point.
|
|
|
|
Participation in this certification programme is voluntary. However,
|
|
developers who do not participate will be asked "but did you even
|
|
try?" at their next standup.
|
|
|
|
---
|
|
|
|
## 1. Scope
|
|
|
|
### 1.1 Purpose
|
|
|
|
This standard establishes the requirements for certifying that a
|
|
software project **works on the certifier's machine** at the time
|
|
of certification. It provides:
|
|
|
|
a) A common vocabulary for describing the state of "working"
|
|
|
|
b) A tiered certification framework with escalating levels of
|
|
assurance
|
|
|
|
c) Procedures for auditing and verifying compliance
|
|
|
|
d) A formal mechanism for responding to the question "well, does
|
|
it work?"
|
|
|
|
### 1.2 Applicability
|
|
|
|
This standard applies to any software project, repository, script,
|
|
or "quick hack I threw together" that resides on a local filesystem
|
|
and is subject to the claim "it works on my machine."
|
|
|
|
### 1.3 Limitations
|
|
|
|
This standard explicitly does **not** certify that the software:
|
|
|
|
- Works on anyone else's machine
|
|
- Will continue to work after the next `git pull`
|
|
- Works when the Wi-Fi is off (unless the project does not require
|
|
Wi-Fi, in which case, congratulations)
|
|
- Works in production
|
|
- Works
|
|
|
|
The certification is valid only for the exact hardware, software,
|
|
environment variables, running background processes, phase of the
|
|
moon, and emotional state of the developer present at the time of
|
|
certification.
|
|
|
|
---
|
|
|
|
## 2. Normative References
|
|
|
|
The following documents are indispensable for the application of
|
|
this standard. For dated references, only the edition cited applies.
|
|
For undated references, good luck.
|
|
|
|
| Reference | Title |
|
|
|----------------------|----------------------------------------------------|
|
|
| WOMM-STD-000:2025 | Definition of "It" in Software Contexts |
|
|
| WOMM-STD-002:2026 | Requirements for the Phrase "I Didn't Touch That" |
|
|
| WOMM-STD-003:2026 | Guidelines for Reproducible Shrugging |
|
|
| IEEE 404 | Standard Not Found |
|
|
| RFC 2324 | Hyper Text Coffee Pot Control Protocol (HTCPCP/1.0)|
|
|
| ISO 9001 | Quality management systems (cited for comedic contrast) |
|
|
| xkcd 1172 | Workflow (normative) |
|
|
|
|
---
|
|
|
|
## 3. Terms and Definitions
|
|
|
|
For the purposes of this standard, the following terms and
|
|
definitions apply.
|
|
|
|
### 3.1 works
|
|
|
|
The software executes without producing an error message that the
|
|
developer cannot explain. Note: errors that the developer *can*
|
|
explain (e.g., "oh that's fine, it always does that") do not
|
|
constitute failure.
|
|
|
|
### 3.2 my machine
|
|
|
|
The specific computer, virtual machine, container, or cardboard
|
|
box with blinking lights on which the developer performs their
|
|
work. "My machine" is implicitly scoped to the exact configuration
|
|
present at certification time, including but not limited to:
|
|
|
|
- Operating system and version
|
|
- Installed packages and their versions
|
|
- Environment variables (exported and forgotten)
|
|
- Browser tabs currently open
|
|
- Number of Docker containers running
|
|
- Whether Spotify is playing lo-fi beats
|
|
|
|
### 3.3 it
|
|
|
|
The software under certification. The antecedent of "it" must be
|
|
identifiable from context, project directory, or vigorous pointing
|
|
at a screen. See WOMM-STD-000.
|
|
|
|
### 3.4 compiles
|
|
|
|
The software can be transformed from source code into an executable
|
|
or interpretable form without the build tool exiting with a non-zero
|
|
status code. Warnings are not errors. Warnings have never been
|
|
errors. We do not speak of `-Werror`.
|
|
|
|
### 3.5 tests pass
|
|
|
|
All automated tests in the project's test suite complete with a
|
|
passing status. Tests that are skipped, marked as expected failures,
|
|
or commented out with `# TODO: fix this later` are considered to
|
|
have passed in the spiritual sense.
|
|
|
|
### 3.6 but did you pull main?
|
|
|
|
A ritual question posed during certification disputes. The correct
|
|
response is always "yes" regardless of whether one has, in fact,
|
|
pulled main.
|
|
|
|
### 3.7 the vibes
|
|
|
|
An intangible but critical quality metric. Software that works but
|
|
feels wrong has poor vibes and may be subject to additional scrutiny
|
|
under Section 6.
|
|
|
|
### 3.8 nondeterministic
|
|
|
|
A word used to describe test failures that only happen in CI. See
|
|
also: "cosmic rays", "timing issue", "works on my machine."
|
|
|
|
---
|
|
|
|
## 4. Certification Levels
|
|
|
|
### 4.1 General
|
|
|
|
WOMM certification is awarded at one of four levels, each
|
|
representing an increasing degree of assurance that the software
|
|
works on the certifier's machine.
|
|
|
|
### 4.2 Level Definitions
|
|
|
|
#### 4.2.1 WOMM Bronze — "It Compiles"
|
|
|
|
Requirements:
|
|
|
|
a) The project directory exists and contains at least one source
|
|
file recognisable as code
|
|
|
|
b) The source code can be parsed without syntax errors
|
|
|
|
c) The developer can point to the project and say "that's the
|
|
one" with reasonable confidence
|
|
|
|
Bronze certification represents the minimum viable claim that
|
|
software exists and is not, in fact, just a README.
|
|
|
|
#### 4.2.2 WOMM Silver — "Tests Pass"
|
|
|
|
Requirements:
|
|
|
|
a) All requirements of WOMM Bronze
|
|
|
|
b) A test suite exists within the project
|
|
|
|
c) The test suite executes and all tests pass (see definition 3.5)
|
|
|
|
d) The developer did not achieve this by deleting the failing tests
|
|
|
|
Silver certification indicates that the software does what someone,
|
|
at some point, thought it should do.
|
|
|
|
#### 4.2.3 WOMM Gold — "Production Ready*"
|
|
|
|
\*on my machine
|
|
|
|
Requirements:
|
|
|
|
a) All requirements of WOMM Silver
|
|
|
|
b) A README file exists and contains at least one true statement
|
|
about the project
|
|
|
|
c) No `TODO`, `FIXME`, or `HACK` comments remain in the codebase
|
|
(or they have been reclassified as "known architectural decisions")
|
|
|
|
d) The developer has mass-suppressed that vague feeling that
|
|
something isn't quite right
|
|
|
|
Gold certification indicates that the software meets a standard of
|
|
quality that the developer would be comfortable showing to a
|
|
colleague, provided the colleague does not look too closely.
|
|
|
|
#### 4.2.4 WOMM Platinum — "Works Everywhere*"
|
|
|
|
\*that I have tested, which is here
|
|
|
|
Requirements:
|
|
|
|
a) All requirements of WOMM Gold
|
|
|
|
b) A continuous integration configuration file is present in the
|
|
repository (e.g., `.github/workflows/`, `Jenkinsfile`,
|
|
`.gitlab-ci.yml`, `bitbucket-pipelines.yml`)
|
|
|
|
c) The git working tree is clean (no uncommitted changes)
|
|
|
|
d) The developer has mass-suppressed the even stronger vague feeling
|
|
that something isn't quite right
|
|
|
|
Platinum certification represents the highest level of assurance
|
|
available under this standard. It indicates that the developer has
|
|
not only verified local functionality but has at least *gestured*
|
|
toward the concept of reproducibility.
|
|
|
|
---
|
|
|
|
## 5. Certification Procedure
|
|
|
|
### 5.1 Pre-Certification
|
|
|
|
Before initiating the certification process, the certifier SHALL:
|
|
|
|
a) Close all unrelated terminal windows to reduce anxiety
|
|
|
|
b) Ensure the machine is in a "known good state" (defined as: the
|
|
state it's in right now)
|
|
|
|
c) Optionally mutter "okay, let's see" under their breath
|
|
|
|
### 5.2 Certification Execution
|
|
|
|
Certification SHALL be performed by executing the WOMM CLI tool
|
|
(`womm certify`) in the root directory of the project under test.
|
|
The tool will automatically evaluate all applicable requirements
|
|
and assign the highest achievable certification level.
|
|
|
|
Manual certification (i.e., just saying "it works on my machine"
|
|
without running the tool) is deprecated as of this edition but
|
|
remains in widespread use.
|
|
|
|
### 5.3 Post-Certification
|
|
|
|
Upon successful certification, the certifier SHALL:
|
|
|
|
a) Generate a certificate of compliance using `womm certificate`
|
|
|
|
b) Optionally affix the WOMM seal to the project's README
|
|
|
|
c) Lean back in their chair with quiet satisfaction
|
|
|
|
d) Not touch anything else
|
|
|
|
### 5.4 Recertification
|
|
|
|
Certification is valid until:
|
|
|
|
- Any file in the project is modified
|
|
- Any dependency is updated
|
|
- The developer runs `git pull`
|
|
- The machine is restarted
|
|
- More than 24 hours have elapsed
|
|
- Someone asks "are you sure?"
|
|
|
|
Recertification follows the same procedure as initial certification.
|
|
|
|
---
|
|
|
|
## 6. Audit Procedures
|
|
|
|
### 6.1 General
|
|
|
|
An audit may be requested by any stakeholder who has reason to
|
|
believe that the claim "it works on my machine" is unsubstantiated.
|
|
Common triggers include:
|
|
|
|
- The software does not work on the auditor's machine
|
|
- The CI pipeline is red
|
|
- A customer has reported an issue
|
|
- It's Monday
|
|
|
|
### 6.2 Audit Process
|
|
|
|
The audit SHALL proceed as follows:
|
|
|
|
a) The auditor requests the certifier demonstrate the software
|
|
working on their machine
|
|
|
|
b) The certifier navigates to the project directory, ideally while
|
|
saying "it was working five minutes ago"
|
|
|
|
c) The `womm certify` command is executed
|
|
|
|
d) Results are compared against the claimed certification level
|
|
|
|
e) If certification fails, proceed to Section 7
|
|
|
|
### 6.3 Environmental Considerations
|
|
|
|
The auditor must acknowledge that the software's behaviour may be
|
|
influenced by factors beyond the developer's control, including but
|
|
not limited to:
|
|
|
|
- The auditor's presence (observer effect)
|
|
- Solar flares
|
|
- npm
|
|
- The fact that Mercury is in retrograde
|
|
|
|
---
|
|
|
|
## 7. Non-Conformance and Appeals
|
|
|
|
### 7.1 Non-Conformance
|
|
|
|
A non-conformance occurs when the software fails to meet the
|
|
requirements of its claimed certification level during an audit.
|
|
|
|
### 7.2 Immediate Remediation Steps
|
|
|
|
Upon discovery of non-conformance, the following steps SHALL be
|
|
attempted in order:
|
|
|
|
1. Run the command again
|
|
2. Run the command again, but slower
|
|
3. Clear all caches (local, browser, DNS, emotional)
|
|
4. Run `git status` and stare at the output pensively
|
|
5. Check if the correct branch is checked out
|
|
6. Ask "did someone push something?"
|
|
7. Restart the machine
|
|
8. Restart the machine again, but with feeling
|
|
|
|
### 7.3 Appeals
|
|
|
|
If remediation is unsuccessful, the certifier may appeal by filing
|
|
a Formal Declaration of Bewilderment (Form WOMM-7B), which must
|
|
include:
|
|
|
|
- Timestamp of last known working state
|
|
- A sworn statement that "I literally didn't change anything"
|
|
- Screenshot evidence (optional but strongly recommended)
|
|
- Stack Overflow link that seems relevant but isn't
|
|
|
|
---
|
|
|
|
## 8. Marking and Labelling
|
|
|
|
### 8.1 WOMM Seal
|
|
|
|
Projects that have achieved WOMM certification MAY display the
|
|
official WOMM Seal of Approval in their documentation, README, or
|
|
office wall.
|
|
|
|
The seal SHALL include:
|
|
|
|
- The text "WOMM CERTIFIED"
|
|
- The certification level (Bronze, Silver, Gold, or Platinum)
|
|
- The date of certification
|
|
- The text "Works On My Machine" or an approved abbreviation
|
|
|
|
### 8.2 Usage Restrictions
|
|
|
|
The WOMM Seal SHALL NOT be used to imply that the software works
|
|
on any machine other than the certifier's. Misuse of the seal
|
|
constitutes a violation of WOMM-STD-001 and may result in the
|
|
offender being asked to "fix it in production, then."
|
|
|
|
---
|
|
|
|
## Appendix A (Informative): Common Excuses and Their Classification
|
|
|
|
| Excuse | Classification | Accepted? |
|
|
|--------|---------------|-----------|
|
|
| "It works on my machine" | Standard claim | Yes (with certification) |
|
|
| "I didn't change anything" | Denial | Under investigation |
|
|
| "It must be a caching issue" | Deflection | Provisionally accepted |
|
|
| "That test is flaky" | Technical excuse | Accepted if test is, in fact, flaky |
|
|
| "Works in debug mode" | Partial conformance | Bronze only |
|
|
| "The API must be down" | External attribution | Requires evidence |
|
|
| "Have you tried clearing your node_modules?" | Counter-audit | Procedurally valid |
|
|
| "It's a known issue" | Acknowledgement | Accepted if issue is, in fact, known |
|
|
| "That's not a bug, it's a feature" | Reclassification | Requires product owner sign-off |
|
|
| "I'll fix it tomorrow" | Deferral | Not accepted for certification |
|
|
| "It worked yesterday" | Temporal defence | Expired |
|
|
| "It works if you do it in the right order" | User-error claim | Gold and above only |
|
|
|
|
---
|
|
|
|
## Appendix B (Normative): Official WOMM Seal Usage Guidelines
|
|
|
|
### B.1 Minimum Seal Size
|
|
|
|
The WOMM Seal SHALL be displayed at a minimum size of 64x64 pixels
|
|
in digital media, or 20mm diameter in print. Smaller sizes risk the
|
|
seal being mistaken for a loading spinner.
|
|
|
|
### B.2 Colour Requirements
|
|
|
|
The seal SHALL be displayed in the official WOMM colour palette:
|
|
|
|
| Level | Primary Colour | Hex |
|
|
|----------|---------------|---------|
|
|
| Bronze | Copper | #B87333 |
|
|
| Silver | Silver | #C0C0C0 |
|
|
| Gold | Gold | #FFD700 |
|
|
| Platinum | Platinum | #E5E4E2 |
|
|
|
|
### B.3 Prohibited Modifications
|
|
|
|
The following modifications to the seal are prohibited:
|
|
|
|
- Adding the word "probably" before "certified"
|
|
- Replacing the checkmark with a question mark
|
|
- Displaying the seal upside-down (this indicates WOMM Decertification)
|
|
- Using the seal as a loading animation
|
|
- Tattooing the seal on any body part (this is not prohibited per se,
|
|
but the Committee questions your judgement)
|
|
|
|
---
|
|
|
|
## Appendix C (Informative): Revision History
|
|
|
|
| Version | Date | Description |
|
|
|---------|------------|-------------------------------------------------|
|
|
| 0.1 | 2025-01-15 | Initial draft, written on a napkin |
|
|
| 0.2 | 2025-06-01 | Added certification levels after heated debate |
|
|
| 0.9 | 2025-11-30 | Committee reached quorum (2 people) |
|
|
| 1.0 | 2026-04-02 | First edition published. It works on my machine. |
|
|
|
|
---
|
|
|
|
*Copyright 2026 The WOMM Standards Committee. All rights reserved,
|
|
except the right to guarantee it works on your machine.*
|
|
|
|
*END OF WOMM-STD-001:2026*
|