updates to migration scripts and docs

General MR

Summary

This MR improves the Big Bang 3.x-to-4.x values migration workflow, particularly for deployments that compose configuration from multiple plaintext or SOPS-encrypted values sources.

It adds a supported way to migrate secondary values sources without duplicating packageConfiguration, validates the required yq anchor behavior before decrypting SOPS files, and reorganizes the migration documentation into a concise workflow guide and detailed command reference.

Changes

Migration scripts

• Add --omit-package-configuration to migrate-values-3-to-4.sh.
  • Removes the complete packageConfiguration block from the migrated output.
  • Intended for secondary values sources when another source in the same Big Bang release owns packageConfiguration.version: v1.
  • Treats exact built-in names already under packages as intentional canonical configuration in this mode.
  • Remains idempotent when the same secondary source is migrated again.
• Preserve the existing default behavior for standalone or primary values sources:
  • Set packageConfiguration.version: v1.
  • Migrate recognized top-level and addons package configuration into packages.
• Add the same option to migrate-sops-values-3-to-4.sh and forward it to the plaintext migration.
• Add a yq feature probe to the SOPS wrapper before any decryption occurs.
  • Requires support for --yaml-fix-merge-anchor-to-spec=true.
  • Reports Mike Farah yq 4.47.1 or newer as the minimum known compatible version.
• Update command help and examples for both scripts.

Documentation

• Restructure the Big Bang 4.0 migration guide around a workflow decision table.
• Provide concise command sequences for:
  • A single plaintext values file.
  • Consolidated layered plaintext values.
  • Separately maintained primary and secondary values sources.
  • Decrypted Kubernetes Secrets.
  • SOPS-encrypted Kubernetes Secrets.
• Clarify that exactly one separately stored source should own packageConfiguration.version: v1.
• Clarify that source ordering must match Helm or Flux precedence.
• Separate the documentation responsibilities:
  • The migration guide answers which workflow and command sequence to use.
  • The script reference documents complete option semantics, safeguards, precedence, anchor handling, output behavior, refusal conditions, and troubleshooting.
• Document yq >= 4.47.1 as the minimum known compatible version.
• Clarify that the current migration covers unified package-path changes only. It does not yet migrate deprecated child-chart or upcoming bb-common subchart values.
• Update ADR 0011 to describe the secondary-source omission workflow and its idempotency behavior.

Tests

• Add plaintext migration coverage for:
  • Omitting packageConfiguration.
  • Migrating legacy package paths in omission mode.
  • Rerunning omission mode without additional changes.
• Add SOPS wrapper coverage for:
  • Forwarding --omit-package-configuration.
  • Preserving migrated package values without the discriminator.
  • Failing the yq feature probe before invoking SOPS.
• Update help-output tests for the new option.

Validation

• bats --jobs 4 tests/bats/migrate-values-3-to-4/migrate-values-3-to-4.bats tests/bats/migrate-values-3-to-4/migrate-sops-values-3-to-4.bats
  • 40 tests passed.
• scripts/generate-package-schemas.sh --check
  • Generated package metadata files are up to date.
• git diff --check
  • Passed.

The repository documentation link-check job should provide final validation for internal and external Markdown links.

Important usage notes

• --omit-package-configuration is only appropriate for a secondary values source when another source applied to the same Big Bang release supplies packageConfiguration.version: v1.
• SOPS migration still requires access to the input document's configured master keys.
• YAML anchors, aliases, and merge keys are expanded during migration and are not recreated in the output.
• Users may migrate the unified package paths now and rerun the migration tooling after consuming the final Big Bang 3.x minor release when the remaining bb-common migration support is available.

Linked Issue

Closes issue

Upgrade Notices

N/A