#2 Using RollingVersions: First Steps to Manage Versions and Changelogs

This guide will help you start using RollingVersions effectively, including creating a changelog, managing versioning, and automating releases. Follow these steps to incorporate RollingVersions into your workflow seamlessly.

Step 1: Understand the Workflow

RollingVersions integrates into your GitHub repository to streamline versioning and changelog creation. Here's how the process works:

1. Pull Requests (PRs): RollingVersions prompts contributors to describe changes when submitting PRs.
2. Version Calculation: Changes are categorized (e.g., fix, feat, breaking), and version numbers are updated automatically using semantic versioning (SemVer).
3. Changelog Updates: RollingVersions generates a changelog with each release.
4. Automation: Final releases are tested and published automatically.

Step 2: Add Changelog Information to Pull Requests

Guide for Contributors

When creating or updating a Pull Request in GitHub, RollingVersions adds a comment prompting you to describe your changes. Follow these steps:

1. Open your Pull Request in GitHub.
2. Locate the RollingVersions comment (it appears automatically).
3. Use the provided structured form to categorize and describe your changes. Aim to describe your change in language that is user-focused and can be understood by your entire team. Here are a few examples:
   • New features - e.g. "Added support for exporting data in CSV format."
   • Bug fixes - e.g. "Fixed intermittent crash when loading large datasets."
   • Breaking changes - e.g. "The version parameter is now required for all API requests."
   • Performance improvements - e.g. "The app now loads 20% faster on startup."
   • Internal changes - e.g. "Updated React dependency to v19".

Best Practices

• Be concise but clear in your descriptions.
• Ensure all relevant changes are captured to keep the changelog accurate.

Step 3: Preview and Approve Changelog Updates

For Reviewers

RollingVersions collects all PR-level descriptions and generates a draft changelog. Before merging a PR:

1. Review the proposed changelog updates in the RollingVersions UI or directly in GitHub.
2. Ensure changes are correctly categorized and described.

Step 4: Automate a Release

Once all changes are merged into the main branch, RollingVersions prepares the release:

1. Go to the RollingVersions Dashboard for your repository:
   • URL format:

     https://rollingversions.com/{{owner}}/{{repo}}

2. Review the release summary, including version changes and the generated changelog.
3. Click the Release Package button to trigger the release process (if CI/CD automation isn’t set up).

What Happens Next

• The release is tagged in GitHub (e.g.,

  v1.2.3

  ).
• A detailed changelog is added to the GitHub release page.
• If CI/CD is configured, the release is deployed automatically.

Step 5: Access and Share the Changelog

In GitHub

• Navigate to the Releases section of your repository.
• View the latest release with its autogenerated changelog.

In RollingVersions

• Use the RollingVersions Dashboard to track all past and current releases, including their changelogs.

Sharing Updates

To increase visibility, share the changelog with your team:

• Use Slack or Discord integrations to post release notes in relevant channels.
• Link to the RollingVersions Dashboard page for external stakeholders.

Advanced Features (Optional)

You can edit the

.github/rollingversions.toml

file to customize many aspects of how RollingVersions behaves.

Customizing Change Types

You can define custom categories or change the default ones. For example:

[[change_types]]
id = "docs"
bumps = "PATCH"
plural = "Documentation Updates"

Custom Tag Format

You can customize the tag format used by RollingVersions. For example to add an extra "hotfix" suffix to your version numbers, you could add this to your config:

version_schema = ["MAJOR", "MINOR", "PATCH", "HOTFIX"]
tag_format = "v{{MAJOR}}.{{MINOR}}.{{PATCH}}-{{HOTFIX}}"

Troubleshooting and FAQs

Q: What if I forget to describe a change?

RollingVersions adds a status check to allow you to block PRs from being merged until the change log is saved. You can also update the change log for a PR after it's merged, as long as no release has been published since it was merged.

Q: How can I share release notes with external stakeholders and team members who do not use GitHub?

RollingVersions provides a "magic link" for each repository that shows a read only view of the release notes. You can share this URL with anyone who needs to see the release notes.

You can also use our Slack integration to post release notes to a Slack channel.