Load a file written against an earlier format version

[fedonman]

A file written against an earlier version now loads instead of being refused. A release that changes a syntax registers one rewrite under its own version with qp.register_migration, and reading applies every rewrite between the version in the file's header and the running one, oldest first, to the lines in memory; the file on disk is untouched. A release that breaks nothing registers nothing, so an older file with no rewrite behind it loads as it is. A rewrite works line for line and may not add or drop one, which is what keeps a ParseError's line number and every source_map entry naming a line of the file its author opened. .wfl reads the same way, from its own table, since a program body and a library entry are not the same text. The require <vendor> line follows the rule too, against the extension's version instead of the library's, so an extension that renames an operation registers a rewrite with qp.register_vendor_migration and the files its users already have keep loading.

Both readers now take a version to be exactly major.minor and refuse anything above the running one. A newer file used to load when its major matched; nothing runs backwards, so it is refused. A patch or a bare major in a header is refused as well, since a patch release changes code and never the format — the grammar's header terminal already said so, and the hand-written parser now agrees with it.

Sits on top of #42.

[pullpo-for-slack]

🔗Pullpo.io Slack PR-Channel

[pullpo-for-slack]

AI Analysis

Purpose of the changes:

The changes introduce a comprehensive migration system that allows older file formats to be upgraded to the current version seamlessly, ensuring backward compatibility while reading files written against earlier syntax versions.

Detailed file changes

(dropdown):

• In file src/qprogram/serialization/migrations.py:

  • Introduced functions for registering migrations for both standard and vendor-specific file formats.
  • Implemented the migration logic that allows files written against older versions to be upgraded to the current version during parsing.
  • Ensured that migrations preserve the line count of the original files to maintain accurate error reporting.

• In file src/qprogram/serialization/parser.py:

  • Updated the loads function to include migration logic that processes files with older format versions before parsing.
  • Added error handling for unsupported major versions and malformed file versions that now raises appropriate exceptions.

• In file src/qprogram/waveform_library.py:

  • Implemented migration handling for waveform library files, allowing older versions to be upgraded similarly to standard files.
  • Added checks to ensure that unsupported versions are rejected with clear error messages.

• In file tests/test_migrations.py:

  • Created a comprehensive suite of tests to validate the migration functionality, covering various scenarios including valid and invalid versions.
  • Ensured that the tests check for correct error handling and the preservation of line counts during migrations.

• In file tests/test_parser.py:

  • Updated tests to validate the new behavior of the loads function in handling migrations for older file formats.
  • Added tests to ensure that newer versions are properly rejected and that invalid version formats raise appropriate errors.

[pullpo-for-slack]

AI Analysis

of the newly committed changes

Purpose of the changes:

Refactor test cases to enhance readability and maintainability by reducing code duplication.

Detailed file changes

(dropdown):

• In file tests/test_migrations.py:
  • Introduced the variable 'ahead' to simplify the construction of version strings in 'test_a_newer_file_is_refused'.
  • Replaced repeated version string construction in 'test_a_newer_file_is_refused' with the 'ahead' variable.
  • Created the variable 'text' to avoid code duplication in 'test_a_migration_ahead_of_its_release_is_left_out' and 'test_a_migration_that_adds_a_line_is_refused'.

[pullpo-for-slack]

AI Analysis

of the newly committed changes

Purpose of the changes:

The changes introduce detailed documentation on handling migrations for waveform constructors and vendor operations, ensuring backward compatibility for older files in the serialization system.

Detailed file changes

(dropdown):

• In file docs/developer/serialization-internals.md:

  • Added a section on how to add a migration for waveform constructor renaming, including code examples.
  • Clarified the use of decorators for registering migrations and their implications on different file formats.
  • Provided detailed explanations of test cases to ensure migrations work as intended.

• In file docs/developer/vendor-extensions.md:

  • Introduced a new section explaining how older files load with the new required arguments for vendor operations.
  • Included code examples demonstrating how to implement vendor migrations and the testing of these migrations.

• In file docs/developer/contributing.md:

  • Updated the contributing guide to clarify the need for migrations when grammar changes stop existing files from parsing.
  • Linked to relevant sections of documentation to assist developers in understanding migration requirements.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[flavie-lebars]

💯