Upstream Shipped a Corruption Fix. Does Updating Repair a Damaged File? How I Decided What My Tool Should Claim

Description and use

When Audacity 4.0.2 released, the author verified that the file format constants remained unchanged and clarified that the update prevents future corruption but does not repair existing damaged files. Documentation and tests were updated to reflect this.

Problem

A new Audacity release (4.0.2) raised questions about whether existing code that downgrades project files needed updates and whether the release would repair already damaged files.

Outcome

The tool’s documentation now accurately reflects that the 4.0.2 release does not change the file format and that updating does not repair already corrupted files. Tests ensure the FAQ stays in sync with code.

Workflow

• 1. Identify constants and files the tool depends on (e.g., AUDACITY_FILE_FORMAT_VERSION, ProjectFileIO.cpp).
• 2. Compare the 4.0.1 and 4.0.2 tags to confirm no changes to those constants or files.
• 3. Review pull requests (PR 12544, PR 12539) to understand the corruption fixes.
• 4. Determine the tool’s capabilities: report missing blocks, play/export gaps as silence, but cannot restore deleted audio.
• 5. Update the FAQ to state that updating prevents future corruption but does not repair existing damaged files.
• 6. Add tests that read the FAQ and code to ensure claims match implementation.
• 7. Publish the updated page with citations to tags and pull requests.

Evidence

It does not touch AUDACITY_FILE_FORMAT_VERSION, which is still "2.0.0" at the 4.0.2 tag

Source

The short answer I put on the page is no: an update stops damage from happening again; a file already damaged stays as it is.

Source

It can report the missing block, and the number of samples it estimates are gone.

Source