Skip to content

Release process

This page describes how to create and publish releases of the DataRobot CLI.

Overview

This project uses GoReleaser for automated releases. Trigger releases by creating and pushing Git tags, which automatically build binaries for multiple platforms and publish them to GitHub.

Prerequisites

  • Write access to the upstream repository (datarobot-oss/cli). This is typically restricted to DataRobot maintainers.
  • All changes are merged to the main branch.
  • Familiarity with semantic versioning.
  • For contributors using forks: upstream remote configured to point to datarobot-oss/cli.

Note for external contributors: This document describes how DataRobot maintainers manage the release process. While external contributors cannot create releases, this information helps you understand the project's release workflow.

Versioning

Versioning follows semantic versioning conventions (SemVer).

  • MAJOR.MINOR.PATCH (e.g., v1.2.3)
  • Pre-releases: v1.2.3-rc.1, v1.2.3-beta.1, v1.2.3-alpha.1

Version guidelines

Use MAJOR version when making incompatible API changes, including:

  • Breaking changes to the command-line interface
  • Removing commands or flags
  • Changing default behavior that breaks existing workflows

Use MINOR version when adding functionality in a backward-compatible manner, including:

  • New commands or subcommands
  • New flags or options
  • New features

Use PATCH version when making backward-compatible bug fixes, including:

  • Bug fixes
  • Documentation updates
  • Performance improvements

Create a release

1. Configure remotes (if using a fork)

If you used gh repo fork --clone to set up your repository (recommended), your remotes are already configured correctly.

Verify your remotes:

git remote -v
# Should show:
# origin    https://github.com/YOUR_USERNAME/cli.git (fetch/push)
# upstream  https://github.com/datarobot-oss/cli.git (fetch/push)

If you cloned manually and need to add the upstream remote:

git remote add upstream https://github.com/datarobot-oss/cli.git

2. Ensure the main branch is ready

# Switch to the main branch
git checkout main

# Pull the latest changes from upstream
git pull upstream main

# Verify that all tests pass
task test

# Verify that linting passes
task lint

3. Determine the next version

Review any recent changes and decide on the next version number based on the semantic versioning guidelines.

Before creating a release tag, run smoke tests to verify the CLI works end-to-end:

# Set your DataRobot API token
export DR_API_TOKEN=your-token

# Run smoke tests
task smoke-test

Alternatively, on PRs you can trigger smoke tests via GitHub Actions by commenting /trigger-smoke-test on the pull request. Daily automated smoke tests also run in CI.

5. Create and push a tag

When creating a tag, note that it must start with v (e.g., v1.0.0, not 1.0.0).

# Create a new version tag
git tag v0.2.0

# Push the tag to upstream to trigger the release
git push upstream v0.2.0

6. Monitor the release process

  1. Go to the Actions tab in GitHub.
  2. Watch the release workflow run.
  3. The workflow will:
  4. Build binaries for multiple platforms (macOS, Linux, Windows)
  5. Run tests
  6. Generate release notes from commit messages
  7. Create a GitHub release
  8. Upload artifacts

7. Verify the release

Once the workflow completes:

  1. Go to Releases.
  2. Verify the new release appears with:
  3. The correct version number
  4. Generated release notes
  5. Binary artifacts for all platforms
  6. A checksums file

8. Update release notes

Optional. Edit the release notes on GitHub to:

  • Add highlights of major changes
  • Include any necessary upgrade instructions
  • Add breaking change warnings
  • Include acknowledgments

Pre-release versions

To test releases before making them generally available, use the following commands.

# Create a pre-release tag
git tag v0.2.0-rc.1

# Push the tag to upstream
git push upstream v0.2.0-rc.1

Pre-release versions are marked as "Pre-release" on GitHub and can be used for testing.

Test the release process

To test the release process without publishing, use the commands below. They create build artifacts locally without creating a GitHub release.

# Dry run (builds but doesn't publish)
goreleaser release --snapshot --clean

# Check output in the dist/ directory
ls -la dist/

Rollback

If a release has issues, the following actions are available.

Delete the tag locally and remotely

# Delete a local tag
git tag -d v0.2.0

# Delete a remote tag from upstream
git push upstream :refs/tags/v0.2.0

Delete the GitHub release

  • Go to the Releases page.
  • Click on the problematic release.
  • Click Delete this release.

Fix the issues and create a new patch release

Release configuration

The release process is configured in goreleaser.yaml. Key configurations:

  • Builds: Defines target platforms and architectures.
  • Archives: Creates distribution archives.
  • Checksums: Generates checksum files.
  • Release notes: Automatic generation from commits.
  • Artifacts: Files to include in the release.

To validate the configuration:

goreleaser check

Automated release workflow

The GitHub Actions workflow (.github/workflows/release.yaml) automatically:

  1. Triggers on tag push matching v*
  2. Checks out the code
  3. Sets up Go environment
  4. Runs GoReleaser
  5. Creates GitHub release
  6. Uploads all artifacts
  7. Verifies installation on all platforms (Linux, macOS, Windows)
  8. Sends Slack notification on success

Post-release verification

After GoReleaser creates the release, the workflow follows a "verify before promoting" approach:

  1. Mark as pre-release: The release is immediately marked as a pre-release after creation
  2. Verify installation: The workflow tests installation on all supported platforms (Linux, macOS, Windows)
  3. Promote on success: If verification passes, stable releases are recreated without pre-release status and a success Slack notification is sent
  4. Stay as pre-release on failure: If verification fails, the release remains marked as a pre-release and a warning Slack notification is sent

This approach ensures users installing "latest" never get a broken release. Semantic pre-releases (e.g., v1.0.0-rc.1) remain as pre-releases even after successful verification.

To fix a failed release: 1. Investigate the installation failure in the workflow logs 2. Fix the underlying issue (usually missing or corrupted binaries) 3. Either re-upload the binaries and manually remove pre-release status via GitHub UI, or delete and recreate the release

Testing installation manually

Use the Installation Tests (On Demand) workflow to test installation without creating a release:

  1. Go to Actions > Installation Tests (On Demand)
  2. Click Run workflow
  3. Enter a version (e.g., v0.2.49) or leave empty for latest
  4. Click Run workflow

This is useful for verifying installation scripts work correctly before or after releases.

Best practices

  1. Never tag the same commit twice.
  2. Each semver tag must point to a unique commit.
  3. If you need to release a new version, ensure the commit differs from any previously tagged commit (e.g., bump the changelog or add a fixup commit before tagging).

  4. Creating two tags on the same commit causes ambiguous version resolution and should be avoided regardless of whether the tags are stable or pre-release.

  5. Always test before releasing.

  6. Run full test suite: task test
  7. Run linters: task lint

  8. Build locally: task build

  9. Use meaningful commit messages.

  10. Commit messages are used to generate release notes

  11. Follow the conventional commit format when possible

  12. Update CHANGELOG.md.

  13. Document significant changes

  14. Include migration notes for breaking changes

  15. Communicate breaking changes.

  16. Update documentation
  17. Add prominent notes in the release description

  18. Consider a major version bump

  19. Test the installation.

  20. Test the install script after the release
  21. Verify that binaries work on target platforms

Troubleshooting

Release workflow fails

  • Check the Actions tab for error messages.
  • Verify thatgoreleaser.yaml is valid: goreleaser check.
  • Ensure all required secrets are configured.

Tag already exists

# Delete and recreate the tag if needed
git tag -d v0.2.0
git push upstream :refs/tags/v0.2.0
git tag v0.2.0
git push upstream v0.2.0

Missing artifacts

  • Verify the build configuration in goreleaser.yaml.
  • Check the build logs in GitHub Actions.
  • Test locally with goreleaser release --snapshot --clean.

Next steps