Translation status. This English page is informative and does not replace the complete, normative Portuguese Core 1.0 at tag v1.0.0 in the public repository. If there is any divergence, the Portuguese source prevails.
Current limits. E0-E3 does not demonstrate effectiveness, learning or quality. The 90-second reference is a design estimate, not a measurement. Historical formulations reproduced below have not been retroactively changed.
The PVP (Pedagogical Versioning Protocol) is an open protocol for recording, versioning and accumulating improvements in lesson plans through classroom-based evidence.
1Definition
The PVP is a minimal set of rules for recording, versioning and accumulating improvements in lesson plans. It draws on the principles of software version control (Git), transposing them to the reality of pedagogical planning.
PVP is a protocol - not a method, framework or system. A teacher who follows the five rules is using PVP. A teacher who does not, is not.
2Rationale
Teachers spend on average 9.3 hours a week on planning (OECD TALIS, 2024), handle multiple classes, and operate under high turnover. Improvements identified after each class are volatile: they exist in the teacher's mind for seconds and are lost without a record. Practical pedagogical knowledge (PCK - Shulman, 1986) stays tacit and disappears with a change of school, class or year.
PVP proposes minimal infrastructure so that this knowledge can be recorded, accumulated and traced.
3The five rules
Rule 1 - Explicit version
Every lesson plan under PVP carries a version number in the form X.Y.Z or X.Y.
Rule 2 - Recorded change
Every improvement is documented in an Improvement Record (IR) with three mandatory fields: (a) what changed, (b) why it changed, (c) the classroom signal that motivated the change.
Rule 3 - Declared context
The plan declares its context of application: grade/year, class time, available resources and student profile.
Rule 4 - Minimal evidence
Each IR requires at least one observed classroom signal - empirical evidence collected during or after the lesson.
Rule 5 - Preserved provenance
Version history and authorship remain traceable over time. No previous version is erased; they are superseded by new versions.
4Entities
English names are given first, with the protocol's original Portuguese acronyms in parentheses.
4.1 Versioned Lesson Plan - VLP (PT: PAV)
Any lesson plan that comes to carry a version number and change history. The format is agnostic: notebook, digital document, spreadsheet, slide or any medium. The VLP is the artifact of the protocol.
Minimum fields: identification (subject, topic, grade, author); current version (X.Y.Z or X.Y); context (Rule 3); plan content (free form); version history.
4.2 Improvement Record - IR (PT: RM)
The atomic unit of change. Each IR documents a specific improvement, with an estimated fill time of 90 seconds.
Required fields: what changed (a concrete description); why it changed (justification tied to practice); classroom signal (the observation that motivated it). Optional: date, change type (X, Y or Z), observed result.
4.3 Contextual Variation - CV (PT: VC)
An adaptation of a VLP for a context different from the original, keeping a traceable link to the base plan. The CV resolves the problem of teachers who work across multiple contexts (regular/adult education, morning/evening, in-person/remote).
It identifies the base VLP, declares the specific context of the variation, keeps its own version history, and universal improvements may be reintegrated into the base VLP. Suggested naming: CV-[context] (e.g. CV-Evening).
5Pedagogical semantic versioning
Based on Semantic Versioning (Preston-Werner, 2013), adapted:
| Position | Name | Increments when… | Example |
|---|---|---|---|
X | Major | Significant restructuring: change of approach, audience, sequence redesign | 1.3.0 → 2.0.0 |
Y | Minor | Adjustment within the same structure: swapped activity, added example, retimed | 1.2.0 → 1.3.0 |
Z | Patch | Micro-correction: broken link, clearer instruction, fixed wording | 1.3.0 → 1.3.1 |
When X increments, Y and Z reset to zero; when Y increments, Z resets. The simplified X.Y form is accepted (implicit Z = 0). The initial version is 1.0.0 (or 1.0).
6Evidence scale
A maturity scale for the plan, based on its level of empirical validation:
| Level | Name | Criterion |
|---|---|---|
E0 | Draft | Plan never taught - theoretical planning |
E1 | Applied once | Taught at least once with the teacher's observation |
E2 | Applied 2+× | Taught twice or more with a learning check (exercise, diagnostic or assessment) |
E3 | Multi-context | Taught in different contexts with a documented Contextual Variation |
Evidence is noted after the version. Example: v3.2.1 - E3.
7Implementation layers
The protocol is implementable in four progressive layers. Each layer works autonomously.
| Layer | Name | Description | Requirements |
|---|---|---|---|
| 1 | Essential | Teacher fills an IR with 3 fields in 90s after class | Pen and paper |
| 2 | Structured | PVP Canvas, spreadsheet organization, formal history | Printed canvas or spreadsheet |
| 3 | Collaborative | Institutional sharing, peer contributions, curation | Shared repository, coordination |
| 4 | Platform | Digital system with automation, search, curriculum integration, analytics | Web/app platform |
8Classroom signal
The central concept of PVP. A classroom signal is any observational evidence the teacher collects during or after class that motivates an improvement. It requires no formal instrument, standardized research or statistical analysis.
Valid examples:
- “70% of students got question 3 wrong on the practice exercise.”
- “The class lost focus after 20 minutes of lecture.”
- “The back rows engaged when I swapped the abstract example for a concrete one.”
- “No student could start the activity without asking for help.”
The classroom signal makes PVP a pull system: improvement is pulled by observed reality, not pushed by theory, platform or external directive.
9Git → PVP transposition
| Git | PVP | Function | Divergence |
|---|---|---|---|
| Repository | VLP | Versioned artifact | VLP is format-agnostic |
| Commit | IR | Atomic change record | IR requires a classroom signal |
| Branch | CV | Variation for another context | CV has a pedagogical/legal motivation |
| Semantic Versioning | Pedagogical Versioning | X.Y.Z convention | Adapted categories |
| Pull Request | Contribution | Proposed improvement | Mandatory human curation |
| Merge | Integration | Incorporating a contribution | No automatic merge |
| Changelog | Version history | Chronological record | - |
| Automated tests | Classroom signals | Validation | Qualitative E0-E3 scale |
10References
- SHULMAN, L. S. Those who understand: knowledge growth in teaching. Educational Researcher, v. 15, n. 2, p. 4-14, 1986.
- SHULMAN, L. S. Knowledge and teaching: foundations of the new reform. Harvard Educational Review, v. 57, n. 1, p. 1-22, 1987.
- NONAKA, I.; TAKEUCHI, H. The Knowledge-Creating Company. Oxford University Press, 1995.
- OHNO, T. Toyota Production System. Productivity Press, 1988.
- PRESTON-WERNER, T. Semantic Versioning 2.0.0. 2013. semver.org.
- LEWIS, C. Lesson Study: A Handbook of Teacher-Led Instructional Change. RBS, 2002.
- OECD. TALIS 2024 Results. OECD Publishing, 2024.
- McNIFF, J. Action Research: Principles and Practice. 3rd ed. Routledge, 2013.
PVP Core 1.0 · Leidison Lima dos Santos · CC BY 4.0 · 2026 · DOI 10.5281/zenodo.18874305