Pedagogical Versioning ProtocolOpen protocol / Core 1.0
Menu
StartProtocolCore 1.0CiteLicenseAboutPortuguês

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.

Start using PVPRead the specification
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

  1. v1.0.0E0Initial plan, never taught
  2. v1.1.0E1Rebalanced lecture timing
  3. v1.2.0E1Swapped the opening example
  4. v1.3.0E2Bridge example before the problemCurrent version
Improvement Recordv1.2.0 → v1.3.0
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.

Why versioning matters

When a lesson plan changes, the file should not erase its history.

Plans change because of the class, available time, resources and what is observed during instruction. Without an explicit version, it becomes difficult to know which file was used, what changed and why that decision made sense.

Illustrative exampleThe same lesson plan in two documented states. The names, class and changes below are included only to demonstrate how to read the comparison.

Without traceability

The content exists, but its history depends on the filename.

Record available?

Lesson plan

Quadratic equations

Class
Year 10
Duration
50 min
Format
In person
File presumed to be currentlesson-final-now.docx
Version
Not indicated
Previous plan
Not identified
Change
Not recorded
Application
It is unclear which copy was used
Copies found
  1. lesson-final.docx
  2. lesson-final-revised.docx
  3. lesson-final-now.docx

With PVP

State, change, context and origin become legible.

Versioned Lesson Plan (PAV)v1.1.0E1

Lesson plan

Quadratic equations

Class
Year 10
Duration
50 min
Format
In person
Identified filequadratic-equations-v1.1.0.docxOrigin: PAV v1.0.0
RM 001
What changed
The abstract opening example was replaced with a concrete situation.
Why it changed
Make it easier for the class to begin the activity.
Classroom signal
Part of the class stopped working during the abstract opening.
Historyv1.0.0 → RM 001 → v1.1.0

Versioning does not mean creating endless copies. It means being able to locate a state, explain a change and preserve the continuity of the work.

What is a PAV? It is the Versioned Lesson Plan (PAV; Plano de Aula Versionado in Portuguese): the plan itself, whether on paper or in a file, identified by a version and connected to its change history. In Core 1.0, the PAV — not each related material — is the versioned unit. Slides, worksheets and other files may display the PAV version they belong to; independent PVP versions for each material are not yet a Core rule.

Five rules. Three entities. One brief record.

A protocol, not a method, framework or system. Follow the five rules and you are using PVP.

  1. Rule 01

    Explicit version

    Every lesson plan carries a version number in X.Y.Z or X.Y form.

  2. Rule 02

    Recorded change

    Every improvement becomes an Improvement Record: what changed, why and which classroom signal prompted it.

  3. Rule 03

    Declared context

    The plan declares its grade level, class time, resources and student profile.

  4. Rule 04

    Minimum evidence

    Each change retains at least one observed classroom signal, rather than a purely theoretical justification.

  5. Rule 05

    Preserved provenance

    Version history and authorship stay traceable. Old versions are superseded, never erased.

Protocol entities

PAVVersioned Lesson Plan
The plan with an explicit version, context and history.
RMImprovement Record
The record of what changed, why it changed and which signal prompted it.
VCContextual Variation
An adaptation for another context, traceably linked to the base plan.
Notation sheet

How to read v3.2.1 · E3

The version and E level appear together, but they answer different questions.

Pedagogical version

Which state of the plan is this?

X.Y.Z

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.pdf

Optional convention: the name identifies the version; the Improvement Record documents what changed, why, and the classroom signal.

Documented use

How much of the plan’s use has been documented?

  • E0Draftno documented application
  • E1Applied onceone documented application
  • E2Applied 2+ timestwo or more documented applications
  • E3Multi-contextdocumented contextual variation
Reading examplev3.2.1 · E3

Version 3.2.1 of the plan, with documented multi-context use.

The version describes the state and type of change. E0–E3 describes documented use. Neither notation is a quality score or proof of learning.

Improvement pulled by the classroom, not pushed by a platform.

  1. 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. 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. 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.

Layer 1

Essential

Fill an Improvement Record with 3 fields after class. The 90-second reference is an unvalidated design estimate.

Pen and paper
Layer 2

Structured

PVP Canvas, spreadsheet organization, formal history.

Printed canvas or spreadsheet
Layer 3

Collaborative

Institutional sharing, peer contributions, curation.

Shared repository
Layer 4

Platform

Digital system with automation, search and analytics.

Web/app platform
The origin of the transposition

From version control to pedagogical planning.

PVP draws on a principle used in software development: identify states, explain changes and preserve the history of work that evolves.

In technology

What Git helps solve

Git is a version-control system: an organized memory of a project. Instead of depending on names such as “final-2”, it makes it possible to locate successive states, compare changes and recover an earlier reference.

Identified state
each project reference can be located and compared
Recorded change
the alteration remains connected to a readable record
Recoverable history
the current state does not erase previous states
In the pedagogical transposition

What PVP adapts

PVP transposes this logic, not the commands. The plan becomes a PAV (Versioned Lesson Plan) with a version, context and history; an improvement receives an RM (Improvement Record); and an adaptation for another context can be recorded as a VC (Contextual Variation).

PAV
keeps the state of the plan, its context and its sequence of versions
RM
explains what changed, why it changed and which signal prompted the decision
VC
preserves the link between an adaptation and the plan from which it originated

Essential correspondences

The table summarizes the conceptual inspiration. Teachers do not need to reproduce the infrastructure of software development.

See the full formal mapping in Core 1.0 →

Swipe horizontally to see all columns.

Version controlPVPWhat is preserved
RepositoryPAVThe artifact and its history
CommitRMThe concrete change and its rationale
BranchVCThe adaptation linked to a base plan
Semantic VersioningPedagogical VersioningThe state and type of change
ChangelogVersion historyThe chronological sequence of changes
ResearchPage in preparation

A formal specification with a research agenda.

PVP Core 1.0 is a protocol specification. A scoping review is planned to map concepts, methods, protocols and systems related to versioning, adaptation and provenance in pedagogical planning. That review will map antecedents; it will not empirically validate PVP. Any later empirical study will be declared separately.

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.

10.5281/zenodo.18874305Citation formats →