Skip to content

Release Notes

4.0.0 [2026-10-09]

Enhancements:

  • Added JupyterLab workspace export and import (workspaces config option with NONE, UPDATE, SKIP_EXISTING, and REPLACE_ALL modes)
  • Added dry run mode (dry_run config option) that previews all changes without modifying the destination project
  • Replaced boolean permissions, gear_rules, data_views, and project_info config options with string enum options supporting NONE, UPDATE, SKIP_EXISTING, APPEND, and REPLACE_ALL merge strategies
  • Added permissions_source config option to apply group permissions template instead of source project permissions
  • Added gear_rules_source config option to apply site template gear rules instead of source project rules
  • Added new_project config option replacing apply_to_existing_project to control whether to create or update the destination project
  • Added access check requiring the gear to be run by a user (not a gear rule) who is a site admin or admin on the destination project
  • Added workspaces file input for importing previously exported workspace archives

Fixes:

  • Fixed session templates export to read raw project record, preserving fields the SDK model drops (e.g. regex added in Flywheel 22.5)
  • Fixed session templates import to handle schema differences between Flywheel versions: removes legacy fields on 22.5+ sites and converts exact-match templates to equivalent regexes on pre-22.5 sites
  • Fixed form_id references in session templates that point to forms unavailable on the destination project, clearing them before import
  • Fixed gear rule fixed input uploads to check that all fixed inputs are present before changing any rules, preventing partial rule updates
  • Fixed data view export to include group_by and filter fields dropped by the SDK model
  • Fixed project settings export to use raw API response, preserving form definition keys (key, name, display, config, settings) that the typed SDK model silently drops
  • Added retry logic for transient errors on all POST operations (gear rules, permissions, views, workspaces, file uploads)
  • Fixed project_info import to support UPDATE and SKIP_EXISTING strategies instead of always replacing all info

Maintenance:

  • Replaced monolithic utils.py with per-feature modules under fw_gear_project_settings/features/
  • Replaced parse_config() returning a dict with a GearArgs dataclass
  • Updated pytest from >=7.4.2,<8 to >=9.1.1
  • Updated pytest-cov from >=4.1.0,<5 to >=7.1.0
  • Updated pytest-mock from >=3.11.1,<4 to >=3.16.0
  • Changed Dockerfile to run as user 31337 instead of named user flywheel
  • Replaced test_utils.py with per-module test files and a shared conftest.py with fake Flywheel SDK client and project fixtures

Documentation:

  • Rewrote README.md with updated config reference, use cases for all five workflows (export, new project, existing project, cross-site import, dry run), logging format reference, and updated workflow diagram

Breaking Changes:

  • Removed default_group_permissions, apply_to_existing_project, and existing_rules config options; replaced by permissions_source, new_project, and gear_rules_action respectively
  • Changed permissions, gear_rules, data_views, and project_info from boolean config options to string enums; existing boolean values will not be accepted
  • Gear must now be run by a user with admin access; runs triggered by gear rules or devices will exit with an error

3.0.3 [2026-08-24]

Maintenance:

  • Updated manifest.json author field from Flywheel SSE to Flywheel and added cite field for manifest standardization
  • Expanded gear description to accurately reflect all supported operations including data views, project settings, attachments, and session templates

3.0.2 [2026-08-19]

Fixes:

  • Fixed form definitions being partially copied during project settings export; the typed FormDefinition SDK model silently dropped form keys (key, name, display, description, config, settings), so export now fetches raw JSON directly from the API to preserve all fields.

3.0.1 [2026-08-03]

Maintenance:

  • Updated flywheel-sdk to 22.3.0

3.0.0 [2026-06-12]

Enhancements:

  • Changed default values for data_views, project_settings, session_templates, project_info, and project_attachments configuration options from false to true, so all settings are copied by default unless explicitly unchecked.

Maintenance:

  • Updated flywheel-sdk dependency from >=17.4.0,<18 to >=22.0.
  • Added .gitignore file.

Documentation:

  • Updated README.md to reflect new default values for configuration options.

Breaking Changes:

  • All copy settings (data_views, project_settings, session_templates, project_info, project_attachments) now default to true instead of false; existing workflows that relied on these being disabled by default must now explicitly set them to false.

2.3.0 [2026-06-03]

Enhancements:

  • Added support for exporting and importing project settings (project_settings config option), including forms, deid_profile, viewer_apps, and workspaces.
  • Added support for exporting and importing session and acquisition templates (session_templates config option).
  • Added support for exporting and importing project custom metadata (project_info config option).
  • Added support for exporting and uploading project attachment files (project_attachments config option and attachments file input).

Fixes:

  • Fixed a typo in README.md ("to be assist" → "to assist").
  • Fixed a syntax error in the generate_project_template docstring (missing colon after "views").

Maintenance:

  • Refactored Dockerfile to use a multi-stage build with base, build, dev, and final production stages using flywheel/python:3.12-wolfi-build.
  • Added requirements-dev.txt to .dockerignore allowlist to support the dev build stage.
  • Extended save_template JSON serializer to handle Flywheel model objects with a to_dict method.
  • Added tests for project_settings, session_templates, project_info, and project_attachments export and import functionality.

Documentation:

  • Updated README.md to document the new project_settings, session_templates, project_info, and project_attachments configuration options.
  • Updated README.md to document the new attachments file input and output.
  • Updated README.md description and use case sections to reflect the expanded set of exportable/importable project attributes.

2.2.9 [2025-10-23]

Enhancements:

  • Added classification metadata fields (function, modality, organ, species, therapeutic_area) to gear manifest
  • Enabled show-job setting in gear manifest

Fixes:

  • Added USER flywheel directive to Dockerfile for improved security

Maintenance:

  • Migrated from poetry to uv for dependency management
  • Migrated from flywheel-gear-toolkit to fw-gear==0.3.2 library
  • Updated python from 3.12.8 to 3.12.12
  • Set PYVER to 3.12 in CI configuration
  • Updated glob2 version constraint from ^0.7 to >=0.7,<0.8
  • Updated pyproject.toml to use PEP 621 format with hatchling build backend
  • Added PLR0913, PLR0912, and PLR0915 lint exceptions for functions with many parameters/branches/statements
  • Refactored string formatting to use f-strings instead of .format()
  • Removed unnecessary import zipfile statement

Documentation:

  • Updated CONTRIBUTING.md with uv-based workflow instructions
  • Updated pre-commit hook documentation to reflect configuration changes

2.2.8 [2025-02-06]

Fixes:

  • Fixed bug where fixed input file version mismatch between origin and destination projects caused the gear to fail by removing version specifications from gear rules
  • Fixed bug where the gear expected permission to have id instead of _id (now accepts either field)

Documentation:

  • Updated README.md formatting to ensure all lines are 88 characters or less
  • Added clarification in README.md about gear rule fixed input versioning behavior
  • Fixed typo in manifest.json config description changing apply_group_permissions to default_group_permissions

Maintenance:

  • Updated python from 3.12.7 to 3.12.8

2.2.6 [2024-12-10]

Enhancements:

  • Added .dockerignore file to optimize Docker build context and reduce image build time

Maintenance:

  • Added CI/CD pipeline configuration with .gitlab-ci.yml for automated testing and deployment
  • Added pre-commit hooks configuration for code quality checks including ruff, pytest, hadolint, and linting tools
  • Added comprehensive test suite with pytest covering main functionality, parser, and utility functions
  • Added Dockerfile based on flywheel/python:3.12-alpine image
  • Added project documentation including README.md, CONTRIBUTING.md, FAQ.md, and LICENSE
  • Added fw_gear_project_settings package with modular architecture separating main logic, parsing, and utilities
  • Migrated to pyproject.toml for dependency management with poetry
  • Updated python to 3.12 and flywheel-sdk to ^17.4.0
  • Added glob2 and flywheel-gear-toolkit dependencies
  • Added release notes documentation in docs/release_notes.md