###############################
 Migration Guide to idf-ci 1.x
###############################

This guide outlines the breaking changes introduced in idf-ci 1.0.

*********************************
 Configuration Structure Changes
*********************************

The artifact configuration structure has been reorganized for better clarity and flexibility:

**Before (0.x):**

.. code-block:: toml

    [gitlab.artifacts]
    s3_file_mode = "zip"

    [gitlab.artifacts.s3_zip.flash]
    bucket = "idf-artifacts"
    zip_basedir_pattern = "**/build*/"
    zip_file_patterns = [
        "bootloader/*.bin",
        "*.bin",
    ]

**After (1.x):**

.. code-block:: toml

    [gitlab.artifacts.s3]
    enable = true

    # by default zip_first is false, so the files will be uploaded individually
    [gitlab.artifacts.s3.configs.flash]
    bucket = "idf-artifacts"
    build_dir_pattern = "**/build*/"
    patterns = [
        "bootloader/*.bin",
        "*.bin",
    ]

    [gitlab.artifacts.s3.configs.metrics]
    bucket = "idf-artifacts"
    zip_first = false
    patterns = [
        "**/size*.json"
    ]

Key Changes:

- ``s3`` and ``s3_zip`` configurations merged into ``s3.configs``

  - Moved ``gitlab.artifacts.s3.[key]`` to ``gitlab.artifacts.s3.configs.[key]``
  - Moved ``gitlab.artifacts.s3_zip.[key]`` to ``gitlab.artifacts.s3.configs.[key]``

- Renamed ``gitlab.artifacts.build_job_filepatterns`` to ``gitlab.artifacts.native.build_job_filepatterns``
- Renamed ``gitlab.artifacts.test_job_filepatterns`` to ``gitlab.artifacts.native.test_job_filepatterns``
- New options: ``is_public``, ``zip_first`` for conditional artifact types
- Mixed artifact type upload/download is now supported

Legacy compatibility for native artifact keys:

- ``gitlab.artifacts.build_job_filepatterns`` and ``gitlab.artifacts.test_job_filepatterns`` still work in 1.x for backward compatibility.
- When these legacy keys are used, idf-ci emits deprecation warnings and maps them to ``gitlab.artifacts.native.*`` internally.
- If both the legacy key and the new ``gitlab.artifacts.native.*`` key are set, the new key takes precedence and the legacy one is ignored.

Recommended migration:

.. code-block:: toml

    [gitlab.artifacts.native]
    build_job_filepatterns = [
        "**/build*/bootloader/*.bin",
        "**/build*/*.bin",
    ]
    test_job_filepatterns = [
        "pytest-embedded/",
        "XUNIT_RESULT*.xml",
    ]

***********************
 Environment Variables
***********************

Removed:

- ``IDF_S3_BUCKET`` (bucket now specified per artifact type in config)