Changelog Style Guide and Process

This document outlines the style and organizational structure for maintaining the Vantage product changelog (changelog.mdx). This guide ensures consistency and clarity when adding new product updates.

Overview

The changelog is organized by month, with each month’s update containing:

Major Product Updates - Significant new features and capabilities
Quality of Life Updates - Improvements, fixes, and smaller enhancements organized by category
Kubernetes Agent Updates - Updates specific to the Kubernetes agent
API Updates - API endpoint changes and enhancements

Structure

Major Product Updates Section

The “Product Updates” section should start with major releases - significant new features that represent substantial product capabilities. These are typically:

New integrations or cost providers
Major feature launches (especially those moving from preview to GA)
Significant new capabilities that unlock new use cases

Format:

Each major update should be a top-level bullet point with a bold title
Include a brief description of the feature and its value
Link to relevant documentation sections

Example:

- **Percent-based cost allocation tagging:** [Percent-based allocation tags](/tagging#percent-based-allocation-tags) are now available for [Virtual Tags](/tagging), allowing you to allocate costs using fixed percentages for predefined chargeback models, manual cost-splitting, and fixed allocation agreements.
- **Cursor integration:** Vantage now integrates with [Cursor](/connecting_cursor) as its latest cost provider.
- **Dynamic forecasting general availability:** [Dynamic forecasting](/forecasting#dynamic-forecast) is now generally available to all Enterprise customers. Previously available in private preview, dynamic forecasting lets customers align their cloud cost forecasts with business growth projections...

Important: When adding major updates, the person providing the changelog content should explicitly identify which updates are considered “major releases” for that month. These should be clearly communicated to ensure proper placement.

Quality of Life Updates Section

After the major product updates, include a “Quality of life updates” section that organizes smaller improvements and fixes into logical categories. Use the following categories (based on December 2025 structure):

Provider integrations - Updates related to connecting and managing cost providers
Resource visibility and data display - Improvements to how resources and data are shown
Cost Reports and notifications - Enhancements to Cost Reports and related notifications
Cost Alerts - Updates to Cost Alert functionality
Dashboards and reporting - Dashboard and reporting improvements
Cost Recommendations - Updates to the Cost Recommendations page
Audit Logs and compliance - Audit log and compliance-related improvements
MSP features - Features and improvements for Managed Service Providers
Virtual Tags & Tagging - Tagging and virtual tag updates
FinOps Agent & AI - Updates to the FinOps Agent and AI features
Active Resources & Resource Visibility - Active Resources page improvements
Business Metrics & Unit Costs - Business metrics and per-unit cost updates
Performance and user interface - UI/UX improvements and performance fixes
Integration and provider management - Integration settings and provider management updates

Format:

Use nested bullets with category headers
Group related updates under the same category
Include links to relevant documentation
Be concise but descriptive

Example:

- **Quality of life updates:** This month, we made a number of improvements and fixes to enhance the Vantage experience:
	- **Cost Reports and notifications:**
		- **Cost Report drilldown in By Date view:** The drilldown functionality is now available in the **By Date** view of [Cost Reports](/cost_reports#update-the-costs-table)...
	- **Cost Alerts:**
		- **Cost Alert notification date fields:** Cost Alert notifications (email, Slack, Microsoft Teams, and Jira) now display two date fields...

Kubernetes Agent Updates Section

The Kubernetes Agent Updates section documents changes specific to the Vantage Kubernetes agent. This section follows a different pattern than other sections: When there are no new Kubernetes agent updates:

Reference the most recent month that had Kubernetes agent updates
Use the format: *See [Previous Month]'s update for the most recent Kubernetes agent release.*

When there are new Kubernetes agent updates:

List the specific updates with version numbers and Helm chart references when applicable
Include links to relevant documentation or GitHub repositories
Describe the feature or fix in user-focused language

Format Options:

Reference to previous month (most common):

## Kubernetes Agent Updates

*See December's update for the most recent Kubernetes agent release.*

Specific version release with details:

## Kubernetes Agent Updates

- Version 1.0.28, Helm Chart [vantage-kubernetes-agent-1.0.40](https://github.com/vantage-sh/helm-charts/releases/tag/vantage-kubernetes-agent-1.0.40), includes the following updates:
	- Default value for `disableKubeTLSverify` is corrected from `string` to `boolean`.
	- Now includes [sidecar init containers](https://kubernetes.io/docs/concepts/workloads/pods/sidecar-containers/) resource requests in pod resources.

Feature update without version:

## Kubernetes Agent Updates

- **Azure GPU support:** Vantage now supports [Azure GPUs](/kubernetes#kubernetes-gpu-idle-costs), allowing you to track, allocate, and optimize GPU-backed workloads running on Azure Kubernetes Service.

Configuration or setting update:

## Kubernetes Agent Updates

Added a configurable setting for [`PodDisruptionBudget`](https://kubernetes.io/docs/tasks/run-application/configure-pdb/) in the Kubernetes agent [Helm chart](https://github.com/vantage-sh/helm-charts) to define how many agent pods can be disrupted. Uses `maxUnavailable` to set the number of pods that may be voluntarily taken down, or `minAvailable` to ensure a minimum number of pods always remain running.

Notes:

Kubernetes agent updates are typically less frequent than product updates
When in doubt, reference the previous month’s update
Only add new content when there are actual Kubernetes agent changes to document
Include Helm chart version numbers and GitHub links when available

API Updates Section

The API Updates section lists changes to API endpoints and Terraform resources. These should be listed as individual bullet points without sub-categories. Format:

Each API update should be a top-level bullet point
Include the endpoint name and link to the API documentation
Describe the enhancement or change

Example:

## API Updates

- **New API documentation site:** A new dedicated [API documentation site](/api) is now available...
- **Audit Logs API enhancements:** The [`/audit_logs`](/api/auditlogs/get-all-audit-logs) endpoint has been enhanced with the following updates:
	- **New object type filter:** You can now filter audit logs by `recommendation_commitment` object type...

Process for Adding Changelog Entries

Step 1: Identify Major vs. Minor Updates

When receiving changelog content, first identify:

Major Product Updates: Significant new features, integrations, or capabilities
Quality of Life Updates: Improvements, fixes, and smaller enhancements

The person providing the changelog should explicitly state which updates are considered “major releases” for the month.

Step 2: Organize Major Updates

Place major product updates at the top of the “Product Updates” section, in order of importance or prominence.

Step 3: Categorize Quality of Life Updates

Organize remaining updates into the appropriate categories listed above. If an update doesn’t fit cleanly into an existing category, use your best judgment or create a new category if it makes sense (though try to reuse existing categories when possible).

Step 4: Add API Updates

List API updates separately in the “API Updates” section without sub-categorization.

Step 5: Verify Links and Documentation

Ensure all links point to the correct documentation sections
Verify that documentation exists for any new features mentioned
Check that API endpoint links use the new /api format (not old readme.io URLs)

Style Guidelines

Consistency: Use consistent formatting and terminology throughout
Links: Always link to relevant documentation sections using anchor links (e.g., /cost_reports#drill-down-in-costs-table)
Bold titles: Use bold for update titles (e.g., **Cost Report drilldown in By Date view:**)
Descriptions: Be concise but descriptive - explain what changed and why it matters
Cross-references: When appropriate, add cross-links between changelog entries and documentation
Date fields: The changelog header should be updated with the current date when adding new entries

Example: Complete Month Structure

<Update label="January 2026">

## Product Updates

- **Major Feature 1:** Description with [link](/docs#section)...
- **Major Feature 2:** Description with [link](/docs#section)...
- **Quality of life updates:** This month, we made a number of improvements and fixes to enhance the Vantage experience:
	- **Category 1:**
		- **Update 1:** Description...
		- **Update 2:** Description...
	- **Category 2:**
		- **Update 3:** Description...

## Kubernetes Agent Updates

*See [Previous Month]'s update for the most recent Kubernetes agent release.*

## API Updates

- **API Update 1:** Description with [link](/api)...
- **API Update 2:** Description with [link](/api)...

</Update>

How to Use This Guide with AI Assistance

Sample Prompt Template

When working with an AI assistant to update the changelog, use this prompt structure:

I need to add changelog entries for [Month Year]. Please follow the changelog style guide at `.cursor/changelog_style_guide.md`.

Major releases for this month:
- [Feature 1 name]: [Brief description]
- [Feature 2 name]: [Brief description]

Other updates to add:
- [Update description or commit SHA/PR number]
- [Update description or commit SHA/PR number]

Please:
1. Check if any documentation needs to be updated
2. Verify feature flag status if applicable
3. Add appropriate cross-links
4. Organize everything according to the style guide

Working with Commits and Code

The changelog process often involves reviewing code changes, commits, and pull requests. Here’s how this has been successfully done: Common Workflow:

Provide commit SHAs or PR numbers: Share specific commit hashes or PR numbers for features/fixes that need changelog entries
Request code review: Ask the AI to examine the code changes to understand what was implemented
Check feature flags: Ask to verify if a feature is behind a feature flag or temporal workflow release
Verify UI steps: Request the AI to identify the user-facing steps or UI changes
Documentation cross-check: Ask if related documentation needs updates based on the code changes

Example Prompts Used Successfully:

"here's the sha 12d8e9c99b8094ef1263fd92481947606c550f20" - Direct commit reference
"check the feature flag status first" - Verify release status before documenting
"what are the ui steps for this" - Understand user-facing changes
"should anything be updated in the corresponding docs" - Check for documentation updates needed
"Does this need to update any docs?" - Verify documentation requirements
"can you add a cross link in the changelog entry" - Add documentation references

Key Success Factors:

Incremental updates: Adding entries one or a few at a time allows for careful review
Verification steps: Always verify feature flag status, documentation needs, and UI impact
Code examination: Reviewing actual code changes ensures accurate descriptions
Cross-linking: Adding links between changelog and documentation improves discoverability

Synopsis of Successful Changelog Process

Based on successful changelog maintenance sessions, here are the key patterns that work well:

Explicit Major Release Identification: Clearly stating which features are “major releases” ensures proper placement at the top of the Product Updates section.
Incremental Entry Addition: Adding entries one at a time or in small batches allows for:
- Careful verification of feature flag status
- Checking if documentation needs updates
- Understanding UI impact and user-facing changes
- Adding appropriate cross-links
Code-Based Verification: Using commit SHAs and PR numbers to:
- Examine actual code changes
- Understand implementation details
- Verify what’s actually being released
- Check for related changes that might need documentation
Documentation Cross-Checking: For each changelog entry:
- Verify documentation exists for the feature
- Check if documentation needs updates based on code changes
- Add cross-links between changelog and documentation
- Update documentation when new features are added
Feature Flag Awareness: Always check:
- If a feature is behind a feature flag
- If it’s a temporal workflow release
- If it’s available to all users or specific tiers
- This determines how to phrase the changelog entry
Category Organization: Organizing quality of life updates into consistent categories:
- Makes the changelog easier to navigate
- Groups related improvements together
- Follows established patterns from previous months
Link Maintenance: Keeping API and documentation links up to date:
- Updating old readme.io links to new /api format
- Verifying all links point to correct documentation sections
- Using proper anchor links for specific sections

Notes

When a feature moves from private preview to GA, this should be called out as a major update
Feature flags or temporal workflow releases should be noted if relevant
Always verify that documentation exists for features mentioned in the changelog
Keep the tone professional and user-focused
Focus on user value and outcomes, not just technical details
When working with commits, always verify feature flag status before documenting
Check for documentation updates needed based on code changes

Get Started

Account & Security

AI, Terraform, & Developer Tools

Provider Integrations

App Integrations

Cost Reporting Features

Financial Planning Features

Changelog style guide

Changelog Style Guide and Process

Overview

Structure

Major Product Updates Section

Quality of Life Updates Section

Kubernetes Agent Updates Section

API Updates Section

Process for Adding Changelog Entries

Step 1: Identify Major vs. Minor Updates

Step 2: Organize Major Updates

Step 3: Categorize Quality of Life Updates

Step 4: Add API Updates

Step 5: Verify Links and Documentation

Style Guidelines

Example: Complete Month Structure

How to Use This Guide with AI Assistance

Sample Prompt Template

Working with Commits and Code

Synopsis of Successful Changelog Process

Notes

Get Started

Account & Security

AI, Terraform, & Developer Tools

Provider Integrations

App Integrations

Cost Reporting Features

Financial Planning Features

​Changelog Style Guide and Process

​Overview

​Structure

​Major Product Updates Section

​Quality of Life Updates Section

​Kubernetes Agent Updates Section

​API Updates Section

​Process for Adding Changelog Entries

​Step 1: Identify Major vs. Minor Updates

​Step 2: Organize Major Updates

​Step 3: Categorize Quality of Life Updates

​Step 4: Add API Updates

​Step 5: Verify Links and Documentation

​Style Guidelines

​Example: Complete Month Structure

​How to Use This Guide with AI Assistance

​Sample Prompt Template

​Working with Commits and Code

​Synopsis of Successful Changelog Process

​Notes

Changelog Style Guide and Process

Overview

Structure

Major Product Updates Section

Quality of Life Updates Section

Kubernetes Agent Updates Section

API Updates Section

Process for Adding Changelog Entries

Step 1: Identify Major vs. Minor Updates

Step 2: Organize Major Updates

Step 3: Categorize Quality of Life Updates

Step 4: Add API Updates

Step 5: Verify Links and Documentation

Style Guidelines

Example: Complete Month Structure

How to Use This Guide with AI Assistance

Sample Prompt Template

Working with Commits and Code

Synopsis of Successful Changelog Process

Notes