Write a repository version note that explains which files changed

Identify the previous and new versions, name the changed files and explain what a reader needs to recheck. A useful repository version note distinguishes an altered file from a corrected description and a verified consequence from an assumption. “Updated files” gives a reader too little information to decide whether their earlier download is still suitable.

This guide concerns writing a note for a research-material deposit after the team has established what changed. It does not validate a dataset, prescribe a repository’s release policy or authorise publication of restricted material. Follow the repository’s current instructions and the team’s actual permissions before changing a public record.

Establish what kind of update you are describing

Compare the intended deposit with the earlier public version. Separate changes to files from changes to descriptive metadata such as a title. Record what the earlier version contained and what the new version will contain before deciding how to summarise the update.

Zenodo’s version-management guidance, checked on 2 November 2026, distinguishes versioning for updated files from metadata editing and points separately to its handling of minor file errors. A new version is a linked record with its own metadata, files and persistent identifier. Use those distinctions for Zenodo; do not assume every repository uses the same process or that all corrections must follow one route.

A version note should describe the release you actually made. Preparing a new-version draft is not evidence that the files are publicly available. Keep a proposed note marked as provisional until the relevant release and public-record checks have been completed.

Work through an original fictional file comparison

The project, filenames, versions and changes below are invented teaching material. They describe no actual dataset, repository record or research finding.

Imagine a fictional teaching collection called Notice Practice. The team compares its published version 1 with a proposed version 2. The earlier CSV uses the column name notice_label. The proposed CSV renames that column notice_type. Its README explains the new name, while a separate image-key file is unchanged.

Fictional material	Difference established by the comparison	Consequence to explain or check
notice-practice.csv	Header renamed from notice_label to notice_type	A script selecting the old header may need revision
README.txt	File description updated to explain the new header	Readers should use the description supplied with the version they downloaded
image-key.csv	No change identified in the comparison	State the limited comparison result without implying that the whole deposit was independently validated
Numerical analysis in an earlier paper	Not rerun as part of this exercise	Do not claim that all published results are unchanged

An early note says: “Version 2 improves the dataset without affecting previous work.” The comparison does not support that assurance. A header rename can affect a reader’s code, and the example supplies no verification of an earlier analysis.

A more useful proposed note is:

Proposed version 2 renames the CSV header notice_label to notice_type and updates the README to describe that name. The comparison identified no change to image-key.csv. Readers whose scripts select notice_label should check those scripts against the new header. Earlier analyses have not been rerun in this exercise.

After an authorised release is complete, replace the proposed status with the actual release details and verified identifiers. Do not copy the fictional names or substitute a guessed DOI. If the team later establishes an additional change, revise the note to represent it rather than retaining a simpler but incomplete account.

Describe consequences at the level you checked

Separate the nature of a change from its possible effects. Renaming a header, adding records, changing units and revising category definitions pose different questions for someone reusing a file. Describe the difference specifically enough for that reader to locate it.

Do not label a change merely cosmetic when it alters a name used by code. Equally, do not invent an analytical consequence because a file differs. State what has been checked, what a reader may need to adjust and what remains unverified. If a substantive correction affects a published interpretation, follow the appropriate research and publication processes; a repository note is not a substitute for them.

Check that your note accounts for the files included in the release. If a repository offers to import files from an earlier version, inspect the resulting package before describing it as complete. Avoid claiming that a previous file was retained merely because it existed in the earlier deposit.

Connect the note to the record readers can inspect

Identify the relevant earlier and current records using their actual links or identifiers. Keep version-specific details distinct from a link representing the whole collection of versions. Check the repository’s instructions for citation and identifiers rather than inventing a universal citation format.

Compare the public record, the released files and the version note after publication. Confirm the named files and changes, and check that the note no longer describes an unreleased draft as available. A local filename or a saved upload form is not a public-release receipt.

Keep any data-availability statement consistent with the actual material and access conditions. The preprint-version guide addresses a different reader-side task: identifying the particular source read. Both journeys depend on making the version and its limits visible, rather than asking readers to infer them from a generic “latest” label.