#1 Get Started with RollingVersions

Welcome to RollingVersions, the seamless way to automate version management, changelogs, and deployment workflows in your GitHub projects. This guide will walk you through the basic setup to integrate RollingVersions into your development workflow, ensuring your releases are efficient and worry-free.

Background

RollingVersions operates by reading configuration files placed in your GitHub repository. These files define your versioning and changelog settings, tailored to your project needs.

Step 1 Add a configuration file to your repository:

Create a file at

.github/rollingversions.toml

. Use the following default template as a starting point:

release_trigger = "github_tags"

[[packages]]
  type = "custom"
  name = "project_name"

[[change_types]]
  id = "breaking"
  bumps = "MAJOR"
  plural = "Breaking Changes"

[[change_types]]
  id = "feat"
  bumps = "MINOR"
  plural = "New Features"

[[change_types]]
  id = "fix"
  bumps = "PATCH"
  plural = "Bug Fixes"

[[change_types]]
  id = "perf"
  bumps = "PATCH"
  plural = "Performance Optimizations"

[[change_types]]
  id = "other"
  bumps = "PATCH"
  plural = "Other Changes (not user-facing)"

Replace

project_name

with a descriptive name for your project. For repositories with multiple packages, you can add additional package blocks as needed.

Step 2: Install the RollingVersions GitHub App

1. Visit RollingVersions GitHub App.
2. Log in with a GitHub account that has admin privileges for your repository.
3. Follow the steps to grant repository access and complete the installation.

Step 3: Integrate with CI/CD (Optional but Recommended)

RollingVersions integrates with your CI/CD pipelines for automated publishing and deployment.

Option 1: Trigger Releases with GitHub Tags

1. Set up your CI pipeline to automatically run when a new GitHub tag is created.
2. When you’re ready to release a new version, click "Publish Release" in the RollingVersions dashboard to create a new tag in GitHub and trigger your CI job.

Option 2: Tell RollingVersions when a new version is released by CI

If you want to trigger your CI job via something other than RollingVersions, and have the release automatically created in RollingVersions when your CI job is ran, you can configure your CI to mark the package as released in RollingVersions like this:

1. Go to the RollingVersions dashboard at

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

   .
2. Copy the automation token from the Repository Settings.
3. Add the token to your CI environment variables as

   ROLLINGVERSIONS_AUTH_TOKEN

   .
4. Add the following command to your build script:

npx rollingversions publish --repo {{owner}}/{{repo}}

5. Replace

   {{owner}}

   and

   {{repo}}

   with your GitHub organization and repository names.

If you do this, you may want to remove the

release_trigger = "github_tags"

line from your configuration file to remove the "Publish Release" button from the RollingVersions dashboard.

Step 4: Enhance Team Awareness

Add a Badge to Your README

Include a RollingVersions badge in your repository’s README for quick access to your release timeline.

Markdown for the badge:

[![RollingVersions](https://img.shields.io/badge/Rolling%20Versions-Release%20Notes-brightgreen?style=for-the-badge)](https://rollingversions.com/{{owner}}/{{repo}})

Replace

{{owner}}

and

{{repo}}

with your GitHub organization and repository names.

Set Up Notifications in Slack

Integrate RollingVersions with communication tools like Slack or Discord for automatic release updates.

Slack Integration

1. Install the GitHub-Slack App.
2. Create dedicated Slack channels, e.g.,

   #rollingversions-releases

   .
3. Post the following command in the channel, replacing placeholders with your details:

/github subscribe {{owner}}/{{repo}} releases