View Source Upgrades

Igniter provides a mix task mix igniter.upgrade that is a drop-in replacement for mix deps.update, but will run any associated upgrade tasks for the packages that have changed.

Using Upgraders

In general, you can replace your usage of mix deps.update with mix igniter.upgrade. Packages that don't use igniter will be updated as normal, and packages that do will have any associated upgraders run.

Writing Upgraders

To write an upgrader, your package should provide an igniter task called your_package.upgrade. This task will take two positional arguments, from and to, which are the old and new versions of the package.

While you are free to implement this logic however you like, we suggest using mix igniter.gen.task your_package.upgrade --upgrade, and following the patterns that are provided by the generated task.

Limitations

Compile Compatibility

The new version of the package must be "compile compatible" with your existing code. For this reason, we encourage library authors to make even major versions compile compatible with previous versions, but this is not always possible. For those cases, we encourage library authors to provide a version prior to their breaking changes that includs an upgrader to code that is compatible with the new version. This way, you can at least instruct users to mix igniter.upgrade package@that.version before upgrading to the latest version.

Path dependencies

We cannot determine the old version for path dependencies, so currently there is no way to use them with mix igniter.upgrade. We can potentially support this in the future with arguments like --old-version-<dep-name> x.y.z.

Upgrading in CI (i.e Dependabot)

The flag --git-ci is provided to mix igniter.upgrade to allow for CI integration. This flag causes igniter to parse the previous versions from the mix.lock file prior to the current pull request. This limitation does mean that only hex dependencies can be upgraded in this way. Here is an example set of github action steps that will run mix igniter.upgrade and add a commit for any upgrades.

Limitations

This example setup does not trigger the github actions on your PR again. This is due to [intentional limitations of GITHUB_TOKEN]. You can see more here: https://github.com/stefanzweifel/git-auto-commit-action?tab=readme-ov-file#commits-made-by-this-action-do-not-trigger-new-workflow-runs It is possible to work around this with a "personal access token". If you come up with a nice way to make the commit trigger another workflow, please let us know 😊.

igniter-upgrade:
  name: mix igniter.upgrade
  runs-on: ubuntu-latest
  if: ${{inputs.igniter-upgrade}}
  permissions:
    contents: write
  steps:
    - name: Dependabot metadata
      id: dependabot-metadata
      uses: dependabot/fetch-metadata@v2
      if: github.event.pull_request.user.login == 'dependabot[bot]'
    - uses: actions/checkout@v3
      with:
        fetch-depth: 0
        ref: ${{ github.head_ref }}
    # This uses a `.tool-version` file for languages
    # Feel free to use whatever steps you want to set up elixir
    # and run the `igniter.upgrade` mix task. Just use the same flags as shown.
    - uses: team-alembic/staple-actions/actions/mix-task@main
      with:
        task: igniter.upgrade --git-ci
    - name: Commit Changes
      uses: stefanzweifel/git-auto-commit-action@v5
      if: github.event.pull_request.user.login == 'dependabot[bot]'
      with:
        commit_message: "[dependabot skip] Apply Igniter Upgrades"
        commit_user_name: dependabot[bot]