👌 Allow config downgrade for known migrations

[agoscinski]

Allow verdi config downgrade to run when the current AiiDA version cannot load the configuration for normal use, but still has the migration path needed to downgrade it.

This change allows to downgrade the config without requiring the current config schema version be the latest. It only l requires that the migration from newer to older version is implemented. This allows to include migrations for older releases through patch releases.

The extension of ConfigurationVersionError is by _can_downgrade is a hotfix. It is used in get_default_profile to not except when verdi config downgrade is called. Otherwise we raise an exception that we should downgrade, when we want to downgrade. The problem is that the function get_default_profile is put as options.PROFILE into the root verdi cmd, and thus every subcommand inherits it and one cannot override options because subcommands are later evaluated. One would need to move it away from the root verdi and add it only where it is needed. However, this would break the verdi CLI since cmds like this verdi -p <PROFILE> ... would not work anymore. So this is out of the table. One does not technically need to do with exception but without a refactor one would need to load the config twice, once for a downgrade check and second to actually create object. Thats also not great to read a file twice for every verdi cmd. I made an issue #7493 about this.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Configuration migration now evaluates whether incompatible configurations can be downgraded, reports that status through ConfigurationVersionError, enforces a maximum downgrade version, and allows profile loading and the CLI to handle downgradeable configurations.

Changes

Configuration downgrade handling

Layer / File(s)	Summary
Downgrade feasibility contract src/aiida/common/exceptions.py, src/aiida/manage/configuration/migrations/migrations.py, tests/manage/configuration/migrations/test_migrations.py	Adds the can_downgrade exception attribute, a downgrade version cap, and migration-chain feasibility checks with boundary tests.
Migration enforcement and error signaling src/aiida/manage/configuration/migrations/migrations.py, tests/manage/configuration/migrations/test_migrations.py	Materializes migration iterables, blocks configurations above the downgrade cap, reports downgrade feasibility for incompatible versions, and tests full downgrade traversal.
Profile loading and CLI downgrade integration src/aiida/cmdline/utils/defaults.py, tests/cmdline/commands/test_config.py	Handles downgradeable configuration errors during profile loading and verifies CLI downgrade persistence and option-key remapping.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant ProfileLoader
  participant config_needs_migrating
  participant config_can_be_downgraded
  participant ConfigurationVersionError
  ProfileLoader->>config_needs_migrating: load configuration
  config_needs_migrating->>config_can_be_downgraded: check migration path
  config_can_be_downgraded-->>config_needs_migrating: return downgrade status
  config_needs_migrating->>ConfigurationVersionError: raise with can_downgrade
  ConfigurationVersionError-->>ProfileLoader: report configuration state

Loading

Possibly related PRs

• aiidateam/aiida-core#7417: Updates the migration chain and configuration-version constants used by downgrade feasibility checks.
• aiidateam/aiida-core#7421: Changes incompatible configuration guidance involving ConfigurationVersionError.
• aiidateam/aiida-core#7436: Clarifies downgrade-related errors for incompatible newer configurations.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly summarizes the main change: enabling config downgrade support for known migrations.
Description check	✅ Passed	The description is on-topic and matches the downgrade-support changes in the pull request.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 6

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/aiida/manage/configuration/migrations/migrations.py`:
- Around line 505-514: Update the config_can_be_downgraded docstring to document
config, target, and migrations with Sphinx :param: fields, and describe its
boolean result with a :return: field. Add a :raises: field only if this function
explicitly raises documented exceptions.
- Around line 572-576: In the downgrade-version validation block, assign the
formatted error message to a local variable before raising
exceptions.ConfigurationError. Preserve the existing message content and raise
the exception using that variable.
- Around line 521-530: Materialize the migrations iterable before the repeated
lookup loop so generator-backed inputs can be searched from the beginning on
every iteration. Update the flow surrounding the while current > target loop and
its next migration search to reuse the materialized collection, preserving the
existing used-cycle detection and failure behavior.
- Around line 507-508: Update the imports in migrations.py to include Optional
and Type from typing, so the config_can_be_downgraded annotations for target and
migrations resolve without undefined-name errors.

In `@tests/cmdline/commands/test_config.py`:
- Around line 280-281: Add Sphinx-style :param: entries to the
test_config_downgrade_incompatible_but_downgradeable docstring documenting the
injected run_cli_command, config_with_profile_factory, and monkeypatch fixtures.
Keep the existing test description and add only applicable parameter
documentation; no return or raises fields are needed.

In `@tests/manage/configuration/migrations/test_migrations.py`:
- Around line 81-94: Update test_config_can_be_downgraded to use a CURRENT
version below MAXIMUM_DOWNGRADE_CONFIG_VERSION for the true assertion and a
version above it for the false assertion; avoid relying on the default constant
values, and keep OLDEST_COMPATIBLE unchanged.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 168dc623-2c7a-49f8-8594-47928467fc37

📥 Commits

Reviewing files that changed from the base of the PR and between 27d71c1 and 1d85daf.

📒 Files selected for processing (6)

• src/aiida/cmdline/utils/defaults.py
• src/aiida/common/exceptions.py
• src/aiida/manage/configuration/migrations/__init__.py
• src/aiida/manage/configuration/migrations/migrations.py
• tests/cmdline/commands/test_config.py
• tests/manage/configuration/migrations/test_migrations.py

[codecov]

Codecov Report

❌ Patch coverage is 80.00000% with 7 lines in your changes missing coverage. Please review.
✅ Project coverage is 80.66%. Comparing base (27d71c1) to head (77ad50d).

Files with missing lines	Patch %	Lines
...iida/manage/configuration/migrations/migrations.py	80.00%	6 Missing ⚠️
src/aiida/cmdline/utils/defaults.py	75.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #7491      +/-   ##
==========================================
+ Coverage   80.66%   80.66%   +0.01%     
==========================================
  Files         581      581              
  Lines       46944    46977      +33     
==========================================
+ Hits        37861    37888      +27     
- Misses       9083     9089       +6     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@tests/manage/configuration/migrations/test_migrations.py`:
- Around line 74-75: Add a Sphinx-style :param monkeypatch: entry to the
docstring of test_config_needs_migrating_incompatible_version, documenting the
injected pytest monkeypatch fixture while preserving the existing description.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 3f4ae8f0-9dcd-419c-a837-ba81b2dd586f

📥 Commits

Reviewing files that changed from the base of the PR and between 1d85daf and 03e821f.

📒 Files selected for processing (5)

• src/aiida/cmdline/utils/defaults.py
• src/aiida/common/exceptions.py
• src/aiida/manage/configuration/migrations/migrations.py
• tests/cmdline/commands/test_config.py
• tests/manage/configuration/migrations/test_migrations.py

🚧 Files skipped from review as they are similar to previous changes (2)

• src/aiida/common/exceptions.py
• src/aiida/cmdline/utils/defaults.py

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (2)

tests/manage/configuration/migrations/test_migrations.py (2)

94-109: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Add a regression test for downgrade_config’s version cap.

The above-cap case only exercises config_can_be_downgraded; it never calls downgrade_config, so the new ConfigurationError guard could regress without failing these tests. Add a pytest.raises case with CURRENT = MAXIMUM_DOWNGRADE_CONFIG_VERSION + 1.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tests/manage/configuration/migrations/test_migrations.py` around lines 94 -
109, Extend test_config_can_be_downgraded with a
pytest.raises(ConfigurationError) case that calls downgrade_config using a
configuration whose CURRENT equals MAXIMUM_DOWNGRADE_CONFIG_VERSION + 1. Keep
the existing above-cap config_can_be_downgraded assertion and verify
downgrade_config rejects the same unsupported version.

---

74-75: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Document all injected pytest fixtures in the changed tests.

Both functions expose fixtures without Sphinx parameter fields:

• tests/manage/configuration/migrations/test_migrations.py#L74-L75: add :param monkeypatch:.
• tests/manage/configuration/migrations/test_migrations.py#L124-L132: add :param load_config_sample: and :param monkeypatch:.

As per coding guidelines, Python docstrings must use Sphinx-style parameter documentation, with types kept in annotations.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tests/manage/configuration/migrations/test_migrations.py` around lines 74 -
75, The docstrings for both changed tests must document their injected pytest
fixtures using Sphinx-style parameter fields. In
tests/manage/configuration/migrations/test_migrations.py lines 74-75, update
test_config_needs_migrating_incompatible_version to add :param monkeypatch:. At
lines 124-132, add :param load_config_sample: and :param monkeypatch: to the
corresponding test docstring; keep fixture types in annotations.

Source: Coding guidelines

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@tests/cmdline/commands/test_config.py`:
- Around line 300-303: Update the migration test assertions after loading
dictionary to verify the legacy configuration key broker.task_timeout is absent
from dictionary['options'], while preserving the existing assertion that
rmq.task_timeout equals 12.

---

Nitpick comments:
In `@tests/manage/configuration/migrations/test_migrations.py`:
- Around line 94-109: Extend test_config_can_be_downgraded with a
pytest.raises(ConfigurationError) case that calls downgrade_config using a
configuration whose CURRENT equals MAXIMUM_DOWNGRADE_CONFIG_VERSION + 1. Keep
the existing above-cap config_can_be_downgraded assertion and verify
downgrade_config rejects the same unsupported version.
- Around line 74-75: The docstrings for both changed tests must document their
injected pytest fixtures using Sphinx-style parameter fields. In
tests/manage/configuration/migrations/test_migrations.py lines 74-75, update
test_config_needs_migrating_incompatible_version to add :param monkeypatch:. At
lines 124-132, add :param load_config_sample: and :param monkeypatch: to the
corresponding test docstring; keep fixture types in annotations.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 235b5f67-9103-45cf-a64a-b444f0efc156

📥 Commits

Reviewing files that changed from the base of the PR and between 03e821f and 1b836c8.

📒 Files selected for processing (5)

• src/aiida/cmdline/utils/defaults.py
• src/aiida/common/exceptions.py
• src/aiida/manage/configuration/migrations/migrations.py
• tests/cmdline/commands/test_config.py
• tests/manage/configuration/migrations/test_migrations.py

🚧 Files skipped from review as they are similar to previous changes (3)

• src/aiida/cmdline/utils/defaults.py
• src/aiida/common/exceptions.py
• src/aiida/manage/configuration/migrations/migrations.py

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (2)

.github/workflows/public-api.yml (1)

27-29: 🔒 Security & Privacy | 🔵 Trivial | ⚡ Quick win

Set persist-credentials: false on checkout.

This job only reads the repo and does local git worktree operations — it never pushes. Leaving the token persisted in .git/config is unnecessary and is the credential-persistence gap zizmor flags.

🔒 Proposed change

     - uses: actions/checkout@v6
       with:
         fetch-depth: 0
+        persist-credentials: false

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.github/workflows/public-api.yml around lines 27 - 29, Update the
actions/checkout step in the workflow to set persist-credentials to false
alongside fetch-depth, ensuring the job’s read-only checkout and local git
worktree operations do not retain the authentication token in git configuration.

Source: Linters/SAST tools

utils/public_api.py (1)

292-346: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Docstrings omit Sphinx :param:/:return: for parameterized methods.

Methods such as extract_class_resources, extract_resources, and resolve_symbol take parameters but use single-line summaries only. The project convention expects Sphinx-style docstrings; types remain in annotations (already satisfied here). Low-priority for an internal tool, but worth aligning if you touch these.

As per coding guidelines: "Use Sphinx-style docstrings (:param:, :return:, :raises:), with types written in annotations rather than docstrings."

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@utils/public_api.py` around lines 292 - 346, Update the docstrings for
extract_class_resources, extract_resources, and resolve_symbol to use
Sphinx-style :param: entries for each parameter and :return: entries for their
return values. Keep type information in the existing annotations and retain the
current summary text; add :raises: only if these methods explicitly raise
documented exceptions.

Source: Coding guidelines

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@tests/manage/configuration/migrations/test_migrations.py`:
- Around line 124-132: Update the test_migrate_full_downgrade docstring to
document both injected fixtures using Sphinx fields, adding :param
load_config_sample: and :param monkeypatch: descriptions; keep types out of the
docstring because they belong in annotations.

---

Nitpick comments:
In @.github/workflows/public-api.yml:
- Around line 27-29: Update the actions/checkout step in the workflow to set
persist-credentials to false alongside fetch-depth, ensuring the job’s read-only
checkout and local git worktree operations do not retain the authentication
token in git configuration.

In `@utils/public_api.py`:
- Around line 292-346: Update the docstrings for extract_class_resources,
extract_resources, and resolve_symbol to use Sphinx-style :param: entries for
each parameter and :return: entries for their return values. Keep type
information in the existing annotations and retain the current summary text; add
:raises: only if these methods explicitly raise documented exceptions.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 348f6434-160c-4e8b-8b49-5b0f986a51a4

📥 Commits

Reviewing files that changed from the base of the PR and between 1b836c8 and 1af9e4d.

📒 Files selected for processing (8)

• .github/workflows/public-api.yml
• src/aiida/cmdline/utils/defaults.py
• src/aiida/common/exceptions.py
• src/aiida/manage/configuration/migrations/migrations.py
• tests/cmdline/commands/test_config.py
• tests/manage/configuration/migrations/test_migrations.py
• tests/utils/test_public_api.py
• utils/public_api.py

🚧 Files skipped from review as they are similar to previous changes (3)

• src/aiida/cmdline/utils/defaults.py
• src/aiida/common/exceptions.py
• src/aiida/manage/configuration/migrations/migrations.py

[agoscinski]

I will ignore codecov patch because the missing lines are just raising errors and I don't want to have regression tests for this as the behavior is not exactly correct and can be only fixed with an API break, see issue #7493