Heads-up: Branch Restructuring Plan

[chengfang]

Heads-up: Branch Restructuring Plan

Summary

We are restructuring branches of argocd-image-updater to promote the new CRD-based implementation as the default master branch going forward.

Branch Changes

• Current master branch → will be renamed to master-annotation-based
• Current crd branch → will be renamed to master

After this change:

• master = CRD-based implementation (new default)
• master-annotation-based = Legacy annotation-based implementation

Timeline

Target Date: 2025-10-24 Friday America/New_York

What This Means

The new master branch introduces a major architectural improvement:

• ImageUpdater Custom Resource Definition (CRD) for declarative configuration
• Controller-based reconciliation pattern
• Replaces the legacy annotation-based configuration and registry polling approach

The legacy implementation will continue to be maintained in a limited fashion on the master-annotation-based branch for users who need it.

Migration Guide for Community Members

For Users with Local Clones

If you have a local clone of the repository, follow these steps to update your local branches AFTER the upstream rename is complete. You can also reference
GitHub Docs on renaming branches

# 1. Fetch the latest changes from remote
git fetch origin

# 2. If you're currently on master, switch to a different branch first
git checkout -b temp-branch

# 3. Delete your local master branch
git branch -D master

# 4. Delete your local crd branch (if you have one)
git branch -D crd

# 5. Create new local branches tracking the renamed remote branches
git checkout -b master origin/master
git checkout -b master-annotation-based origin/master-annotation-based

# 6. Clean up the temporary branch
git branch -D temp-branch

# 7. Update your default branch
git remote set-head origin master

For Fork Owners

If you have a fork of the repository, run these steps AFTER the upstream rename is complete:

# 1. Add upstream if not already configured
git remote add upstream https://github.com/argoproj-labs/argocd-image-updater.git

# 2. Fetch all branches from upstream (after the upstream rename)
git fetch upstream

# 3. Save your current master branch to master-annotation-based
git checkout master
# At this point, your local master still has the old annotation-based code
# Create a new branch to preserve it
git checkout -b master-annotation-based

# 4. Push the annotation-based code to your fork
git push origin master-annotation-based

# 5. Update your master to match the new CRD-based upstream master
git checkout master
git reset --hard upstream/master  # Now points to the new CRD-based code
git push origin master --force

# 6. Clean up old crd branch if you have one
git branch -D crd 2>/dev/null || true  # Ignore error if branch doesn't exist
git push origin --delete crd 2>/dev/null || true

What each step does:

• Step 3: Checks out your current master (still annotation-based) and creates a branch from it
• Step 4: Pushes this preserved copy to your fork as master-annotation-based
• Step 5: Resets your local master to match upstream's new master (which is now CRD-based)
• Step 6: Removes the old crd branch since it's now merged into master

For Active PR Contributors

If you have open pull requests:

1. PRs targeting the old master:

   • Your PR will now target master-annotation-based
   • Consider whether your changes should target the new CRD-based master instead
   • You may need to recreate your PR against the appropriate branch

2. PRs targeting the old crd branch:

   • Your PR will now target the new master
   • This is likely what you want - no action needed

3. If you need to retarget your PR:

   # Update your local repository first (see above)
   
   # Rebase your feature branch onto the correct base
   git checkout your-feature-branch
   git rebase master  # or master-annotation-based, depending on target
   git push --force-with-lease

For CI/CD Pipelines

Update any automation that references branch names:

• Change crd → master
• Change master → master-annotation-based (if you need the legacy version)
• Update default branch references in your CI/CD configs

For Documentation/Tutorial Authors

• Update any documentation that references the crd branch to use master
• Add notes about master-annotation-based for users on the legacy version
• Update installation commands to reflect the new branch structure

Questions or Issues?

If you encounter any problems during migration:

• Check this guide first
• Open an issue at https://github.com/argoproj-labs/argocd-image-updater/issues
• Ask in the CNCF #argocd-image-updater Slack channel

Why This Change?

The CRD-based implementation represents a significant architectural improvement:

• Better alignment with Kubernetes-native patterns
• Improved declarative configuration management
• Enhanced reconciliation and state management
• Better integration with GitOps workflows
• Cleaner separation of concerns

We believe this is the right direction for the project's future, and making it the default master branch reflects that commitment.

Thank you for your understanding and cooperation during this transition!

[chengfang]

Completed the planned branch renaming. From now on,

master = CRD-based implementation (default branch)
master-annotation-based = Legacy annotation-based implementation