Pedagogical Versioning Protocol
An open protocol for treating lesson plans as versioned pedagogical artifacts.
PVP defines a minimum workflow for teachers to number versions, record changes and preserve each plan's history, context and provenance. Each incorporated improvement produces a new traceable version.
- Current version
- Core 1.0
- Status
- Published version
- Date
- 4 March 2026
- License
- CC BY 4.0
Use example
How a lesson accumulates versions.
The protocol keeps each change and its context legible. This example is illustrative and does not represent a research finding.
Apply this workflow with the Starter Kit →Illustrative example
VLP / Lesson plan
Quadratic equations
Version history
- v1.0.0E0Initial plan, never taught
- v1.1.0E1Rebalanced lecture timing
- v1.2.0E1Swapped the opening example
- v1.3.0E2Bridge example before the problemCurrent version
- What changed
- Added a bridge example between mechanical formula and a contextual problem.
- Why it changed
- The direct jump skipped a cognitive step.
- Classroom signal
- Illustrative record: “70% stalled at the transition.”
The numbers in this example are not research findings and do not demonstrate learning.
Every teacher leaves class knowing what they'd do differently.
That thought lasts seconds and disappears. Without a record, every year restarts from zero.
Practical knowledge is volatile
Teachers spend ~9.3 hours a week planning (OECD TALIS, 2024), yet the improvements they discover in the room stay tacit and vanish with turnover, retirement or a change of school.
Software solved this in 2005
Version control turned source code from an overwritten file into an artifact with memory. PVP adapts that idea to the lesson plan: minimal, semantic and cumulative.
Five rules. Three entities. One brief record.
A protocol, not a method, framework or system. Follow the five rules and you are using PVP.
Explicit version
Every lesson plan carries a version number in X.Y.Z or X.Y form.
Recorded change
Every improvement becomes an Improvement Record: what changed, why, and which classroom signal prompted it.
Declared context
The plan declares its grade level, class time, resources and student profile.
Minimal record
Each change retains at least one observed classroom signal, rather than a purely theoretical justification.
Preserved provenance
Version history and authorship stay traceable. Old versions are superseded, never erased.
Versioned Lesson Plan
Improvement Record
Contextual Variation
The artifact, the change, the variation.
Pedagogical semantic versioning
XMajor- Significant restructuringapproach, audience, or sequence
YMinor- Evolution within the same structureactivity, example, or timing
ZPatch- Localized refinementlink, instruction, or wording
When X increments, Y and Z reset to zero; when Y increments, Z resets to zero. The X.Y form is also accepted.
In the filename
The version can also remain visible on the artifact itself:
lesson-plan-quadratic-equations-v1.3.0.pdfOptional convention: the name identifies the version; the Improvement Record documents what changed, why, and the classroom signal.
Documented use maturity
- E0 Draft - no documented application
- E1 Applied once - one documented application
- E2 Applied 2+ times - two or more documented applications
- E3 Multi-context - documented contextual variation
Notation follows the version: v3.2.1 - E3. E0-E3 describes documented use maturity, not quality, effectiveness or learning.
Improvement pulled by the classroom, not pushed by a platform.
- 1
Classroom signal
You observe something real, for example: “70% stalled on question 3” or “the back rows engaged when I switched to a concrete example”. These are illustrative examples, not research findings.
- 2
Improvement Record
You write what changed, why, and the signal that prompted it. The 90-second reference is an unvalidated design estimate, not a measured result.
- 3
New version
The plan is versioned: v1.2.0 → v1.3.0. Its use record can be updated when applicable, while earlier versions remain traceable.
Four layers. Each one works on its own.
Layer 1 is enough. Start with pen and paper; scale only if you want to.
Essential
Fill an Improvement Record with 3 fields after class. The 90-second reference is an unvalidated design estimate.
Pen and paperStructured
PVP Canvas, spreadsheet organization, formal history.
Printed canvas or spreadsheetCollaborative
Institutional sharing, peer contributions, curation.
Shared repositoryPlatform
Digital system with automation, search and analytics.
Web/app platformGit → PVP
The protocol transposes the core ideas of version control into the reality of lesson planning. See all eight mappings →
| Git | PVP | Function |
|---|---|---|
| Repository | VLP | Versioned artifact |
| Commit | IR | Atomic change record |
| Branch | CV | Variation for another context |
| Semantic Versioning | Pedagogical Versioning | X.Y.Z convention |
| Pull Request | Contribution | Proposed improvement (human curation) |
| Automated tests | Classroom signals | Documented use conditions, not a test of efficacy |
What diverges: PVP requires a classroom signal, works without technology, accepts natural language, and merges only through human curation.
A formal specification with a research agenda.
Cite Core 1.0
The Core is openly deposited with a DOI and has an OSF registration. The local record documents a work deposit and paid fee at the National Library of Brazil; final approval remains to be confirmed.
Protocol, not platform. Gizhub is a future digital implementation under development. PVP remains usable with paper, spreadsheets, documents or other platforms.