From c5dce359629872ca74cd2c6da3a968879c563e16 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 30 Oct 2025 20:27:21 +0000 Subject: [PATCH 1/5] Initial plan From ce06c46c8604562892c9d7d1b8178032cf2e6e20 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 30 Oct 2025 20:39:17 +0000 Subject: [PATCH 2/5] Add automated changelog management system Co-authored-by: bookernath <8922457+bookernath@users.noreply.github.com> --- .changelogs/README.md | 97 ++++++ .changelogs/entries/.gitkeep | 3 + .changelogs/published/.gitkeep | 3 + .../1730322000000-abc123.json | 22 ++ .changelogs/schema.json | 80 +++++ .github/workflows/changelog-entry-check.yml | 98 ++++++ .github/workflows/changelog-pr-helper.yml | 139 +++++++++ .github/workflows/changelog-publish.yml | 129 ++++++++ CONTRIBUTING.md | 48 +++ README.md | 23 ++ docs/changelog/2025-10-30.mdx | 13 + docs/changelog/GUIDE.md | 293 ++++++++++++++++++ docs/changelog/README.mdx | 33 ++ package.json | 5 +- pull_request_template.md | 7 + scripts/changelog-add.js | 184 +++++++++++ scripts/changelog-publish.js | 185 +++++++++++ scripts/changelog-validate.js | 146 +++++++++ 18 files changed, 1507 insertions(+), 1 deletion(-) create mode 100644 .changelogs/README.md create mode 100644 .changelogs/entries/.gitkeep create mode 100644 .changelogs/published/.gitkeep create mode 100644 .changelogs/published/2025-10-30T20-36-04-120Z/1730322000000-abc123.json create mode 100644 .changelogs/schema.json create mode 100644 .github/workflows/changelog-entry-check.yml create mode 100644 .github/workflows/changelog-pr-helper.yml create mode 100644 .github/workflows/changelog-publish.yml create mode 100644 docs/changelog/2025-10-30.mdx create mode 100644 docs/changelog/GUIDE.md create mode 100644 docs/changelog/README.mdx create mode 100755 scripts/changelog-add.js create mode 100755 scripts/changelog-publish.js create mode 100755 scripts/changelog-validate.js diff --git a/.changelogs/README.md b/.changelogs/README.md new file mode 100644 index 000000000..314c89b93 --- /dev/null +++ b/.changelogs/README.md @@ -0,0 +1,97 @@ +# Changelog Management System + +This directory contains the automated changelog management system for BigCommerce Developer Documentation. + +## Directory Structure + +``` +.changelogs/ +├── entries/ # Ephemeral changelog entries (one per doc change) +├── published/ # Archived published changelogs +├── schema.json # JSON schema for changelog entries +└── README.md # This file +``` + +## How It Works + +### 1. Creating Changelog Entries + +When you make a documentation change, create a changelog entry: + +```bash +npm run changelog:add +``` + +This will: +- Prompt you for information about your change +- Generate a unique changelog entry file in `.changelogs/entries/` +- The entry will be committed with your documentation changes + +### 2. Changelog Entry Format + +Each changelog entry is a JSON file containing: + +```json +{ + "id": "unique-id", + "timestamp": "2025-10-30T20:00:00.000Z", + "type": "added|changed|deprecated|removed|fixed|security", + "title": "Brief description of the change", + "description": "Detailed description of what changed and why", + "affectedDocs": [ + { + "path": "docs/api-docs/cart/cart-api.mdx", + "url": "/docs/api-docs/cart/cart-api", + "title": "Cart API Overview" + } + ], + "author": "github-username", + "prNumber": 123 +} +``` + +### 3. Publishing Changelogs + +Changelogs are automatically aggregated and published on a regular cadence (every 2 weeks) via GitHub Actions: + +- The workflow collects all entries from `.changelogs/entries/` +- Generates a formatted changelog document +- Creates a PR with the aggregated changelog +- Moves processed entries to `.changelogs/published/` + +### 4. Manual Publishing + +To manually generate a changelog: + +```bash +npm run changelog:publish +``` + +## Change Types + +- **added**: New documentation, features, or capabilities +- **changed**: Updates to existing documentation +- **deprecated**: Documentation marked as deprecated +- **removed**: Removed documentation or features +- **fixed**: Bug fixes or corrections +- **security**: Security-related updates + +## Best Practices + +1. **Create entries alongside doc changes**: Always create a changelog entry when updating documentation +2. **Be descriptive**: Write clear, user-friendly descriptions +3. **Link to relevant docs**: Include all affected documentation pages +4. **Use consistent language**: Follow the existing style in published changelogs +5. **Review before committing**: Ensure your changelog entry is accurate and complete + +## Automation + +The system includes several GitHub Actions workflows: + +- **changelog-entry-check.yml**: Validates that PRs with doc changes include changelog entries +- **changelog-publish.yml**: Runs bi-weekly to aggregate and publish changelogs +- **changelog-pr-helper.yml**: Auto-generates changelog entry templates from PR context + +## Configuration + +Configuration is stored in `package.json` under the `changelog` key. diff --git a/.changelogs/entries/.gitkeep b/.changelogs/entries/.gitkeep new file mode 100644 index 000000000..a69e38156 --- /dev/null +++ b/.changelogs/entries/.gitkeep @@ -0,0 +1,3 @@ +# This directory contains ephemeral changelog entries + +Changelog entries in this directory will be aggregated and moved to `published/` when a changelog is released. diff --git a/.changelogs/published/.gitkeep b/.changelogs/published/.gitkeep new file mode 100644 index 000000000..97c5b10e6 --- /dev/null +++ b/.changelogs/published/.gitkeep @@ -0,0 +1,3 @@ +# This directory contains archived changelog entries + +After changelogs are published, the individual entries are moved here for archival purposes. diff --git a/.changelogs/published/2025-10-30T20-36-04-120Z/1730322000000-abc123.json b/.changelogs/published/2025-10-30T20-36-04-120Z/1730322000000-abc123.json new file mode 100644 index 000000000..8ef20ae5d --- /dev/null +++ b/.changelogs/published/2025-10-30T20-36-04-120Z/1730322000000-abc123.json @@ -0,0 +1,22 @@ +{ + "id": "1730322000000-abc123", + "timestamp": "2025-10-30T20:00:00.000Z", + "type": "added", + "title": "Automatic changelog management system", + "description": "Introduced a new automated changelog management system inspired by changesets. Documentation contributors can now create changelog entries alongside their changes, which are automatically aggregated and published on a regular cadence.", + "affectedDocs": [ + { + "path": ".changelogs/README.md", + "url": "/.changelogs/README", + "title": "Changelog Management System" + }, + { + "path": "docs/changelog/README.mdx", + "url": "/docs/changelog", + "title": "Documentation Changelog" + } + ], + "author": "devdocs-team", + "tags": ["automation", "changelog", "documentation"], + "breaking": false +} diff --git a/.changelogs/schema.json b/.changelogs/schema.json new file mode 100644 index 000000000..c00a17d07 --- /dev/null +++ b/.changelogs/schema.json @@ -0,0 +1,80 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "https://developer.bigcommerce.com/schemas/changelog-entry.json", + "title": "Changelog Entry", + "description": "Schema for BigCommerce documentation changelog entries", + "type": "object", + "required": ["id", "timestamp", "type", "title", "description", "affectedDocs"], + "properties": { + "id": { + "type": "string", + "description": "Unique identifier for this changelog entry", + "pattern": "^[a-z0-9-]+$" + }, + "timestamp": { + "type": "string", + "description": "ISO 8601 timestamp when the entry was created", + "format": "date-time" + }, + "type": { + "type": "string", + "description": "Type of change", + "enum": ["added", "changed", "deprecated", "removed", "fixed", "security"] + }, + "title": { + "type": "string", + "description": "Brief, user-friendly title for the change", + "minLength": 10, + "maxLength": 200 + }, + "description": { + "type": "string", + "description": "Detailed description of the change and its impact", + "minLength": 20 + }, + "affectedDocs": { + "type": "array", + "description": "List of documentation pages affected by this change", + "minItems": 1, + "items": { + "type": "object", + "required": ["path", "url"], + "properties": { + "path": { + "type": "string", + "description": "Relative file path from repository root" + }, + "url": { + "type": "string", + "description": "Public URL path for the documentation page" + }, + "title": { + "type": "string", + "description": "Title of the documentation page" + } + } + } + }, + "author": { + "type": "string", + "description": "GitHub username of the author" + }, + "prNumber": { + "type": "integer", + "description": "Pull request number associated with this change", + "minimum": 1 + }, + "tags": { + "type": "array", + "description": "Optional tags for categorization", + "items": { + "type": "string" + } + }, + "breaking": { + "type": "boolean", + "description": "Whether this is a breaking change", + "default": false + } + } +} diff --git a/.github/workflows/changelog-entry-check.yml b/.github/workflows/changelog-entry-check.yml new file mode 100644 index 000000000..cdf1b13a9 --- /dev/null +++ b/.github/workflows/changelog-entry-check.yml @@ -0,0 +1,98 @@ +name: Changelog Entry Check + +on: + pull_request: + types: [opened, synchronize, reopened, labeled, unlabeled] + paths: + - 'docs/**' + - 'reference/**' + - 'guides/**' + +jobs: + check-changelog: + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v3 + with: + fetch-depth: 0 + + - name: Setup Node.js + uses: actions/setup-node@v3 + with: + node-version: 18.x + + - name: Install dependencies + run: npm ci + + - name: Check for changelog entry + id: check + run: | + # Check if PR has skip-changelog label + if [[ "${{ contains(github.event.pull_request.labels.*.name, 'skip-changelog') }}" == "true" ]]; then + echo "⏭️ Skipping changelog check (skip-changelog label present)" + exit 0 + fi + + # Check if any doc files were modified + CHANGED_DOCS=$(git diff --name-only origin/${{ github.base_ref }}...HEAD | grep -E '^(docs|reference|guides)/' || true) + + if [ -z "$CHANGED_DOCS" ]; then + echo "ℹ️ No documentation files changed" + exit 0 + fi + + echo "📝 Documentation files changed:" + echo "$CHANGED_DOCS" + + # Check for changelog entries + CHANGELOG_ENTRIES=$(git diff --name-only origin/${{ github.base_ref }}...HEAD | grep -E '^\.changelogs/entries/.*\.json$' || true) + + if [ -z "$CHANGELOG_ENTRIES" ]; then + echo "::error::No changelog entry found. Please add a changelog entry using 'npm run changelog:add' or add the 'skip-changelog' label if this change doesn't require a changelog entry." + exit 1 + fi + + echo "✅ Changelog entries found:" + echo "$CHANGELOG_ENTRIES" + + - name: Validate changelog entries + if: steps.check.outcome == 'success' + run: | + ENTRIES=$(git diff --name-only origin/${{ github.base_ref }}...HEAD | grep -E '^\.changelogs/entries/.*\.json$' || true) + + if [ -n "$ENTRIES" ]; then + echo "Validating changelog entries..." + for entry in $ENTRIES; do + if [ -f "$entry" ]; then + npm run changelog:validate "$entry" + fi + done + fi + + - name: Comment on PR + if: failure() + uses: actions/github-script@v6 + with: + script: | + github.rest.issues.createComment({ + issue_number: context.issue.number, + owner: context.repo.owner, + repo: context.repo.repo, + body: `## 📝 Changelog Entry Required + +This pull request modifies documentation files but doesn't include a changelog entry. + +**To add a changelog entry:** +\`\`\`bash +npm run changelog:add +\`\`\` + +Then commit the generated file in \`.changelogs/entries/\` along with your changes. + +**If this change doesn't require a changelog entry**, add the \`skip-changelog\` label to this PR. + +For more information, see [.changelogs/README.md](.changelogs/README.md). + ` + }) diff --git a/.github/workflows/changelog-pr-helper.yml b/.github/workflows/changelog-pr-helper.yml new file mode 100644 index 000000000..de4fb8ef2 --- /dev/null +++ b/.github/workflows/changelog-pr-helper.yml @@ -0,0 +1,139 @@ +name: Suggest Changelog Entry + +on: + pull_request: + types: [opened, reopened] + paths: + - 'docs/**' + - 'reference/**' + - 'guides/**' + +permissions: + pull-requests: write + +jobs: + suggest: + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v3 + + - name: Analyze PR changes + id: analyze + uses: actions/github-script@v6 + with: + script: | + const { data: pr } = await github.rest.pulls.get({ + owner: context.repo.owner, + repo: context.repo.repo, + pull_number: context.issue.number + }); + + // Get list of changed files + const { data: files } = await github.rest.pulls.listFiles({ + owner: context.repo.owner, + repo: context.repo.repo, + pull_number: context.issue.number + }); + + // Filter for documentation files + const docFiles = files.filter(file => + file.filename.match(/^(docs|reference|guides)\/.*\.(mdx?|yml|yaml|json)$/) + ); + + if (docFiles.length === 0) { + console.log('No documentation files changed'); + return; + } + + // Determine change type based on file status + const addedFiles = docFiles.filter(f => f.status === 'added'); + const modifiedFiles = docFiles.filter(f => f.status === 'modified'); + const removedFiles = docFiles.filter(f => f.status === 'removed'); + + let changeType = 'changed'; + if (addedFiles.length > 0 && modifiedFiles.length === 0) { + changeType = 'added'; + } else if (removedFiles.length > 0) { + changeType = 'removed'; + } + + // Generate suggested entry + const affectedDocs = docFiles.map(file => { + const url = file.filename + .replace(/^docs\//, '/docs/') + .replace(/^reference\//, '/docs/api-docs/') + .replace(/^guides\//, '/docs/guides/') + .replace(/\.(mdx?|yml|yaml|json)$/, '') + .replace(/\/index$/, ''); + + return { + path: file.filename, + url: url, + title: file.filename.split('/').pop().replace(/\.(mdx?|yml|yaml|json)$/, '') + }; + }); + + const suggestion = { + type: changeType, + title: pr.title, + description: pr.body || pr.title, + affectedDocs: affectedDocs, + author: pr.user.login, + prNumber: pr.number + }; + + // Create a comment with the suggestion + const comment = `## 📝 Suggested Changelog Entry + +Based on the changes in this PR, here's a suggested changelog entry: + +\`\`\`json +{ + "type": "${suggestion.type}", + "title": "${suggestion.title}", + "description": "${suggestion.description.substring(0, 200)}${suggestion.description.length > 200 ? '...' : ''}", + "affectedDocs": [ +${suggestion.affectedDocs.map(doc => ` { + "path": "${doc.path}", + "url": "${doc.url}", + "title": "${doc.title}" + }`).join(',\n')} + ], + "author": "${suggestion.author}", + "prNumber": ${suggestion.prNumber} +} +\`\`\` + +### To use this suggestion: + +1. Run \`npm run changelog:add\` in your local repository +2. Use the suggested values above when prompted +3. Review and adjust as needed +4. Commit the generated file in \`.changelogs/entries/\` + +### Change Type Options: +- **added**: New documentation or features +- **changed**: Updates to existing documentation +- **deprecated**: Documentation marked as deprecated +- **removed**: Removed documentation or features +- **fixed**: Bug fixes or corrections +- **security**: Security-related updates + +### Tips: +- Keep the title concise and user-friendly +- Expand the description to explain what changed and why +- Ensure all affected documentation pages are listed +- Review the automatically generated URLs and adjust if needed + +--- + +*This suggestion was automatically generated. You can add the \`skip-changelog\` label if a changelog entry is not needed.*`; + + await github.rest.issues.createComment({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: context.issue.number, + body: comment + }); diff --git a/.github/workflows/changelog-publish.yml b/.github/workflows/changelog-publish.yml new file mode 100644 index 000000000..9f1968fa6 --- /dev/null +++ b/.github/workflows/changelog-publish.yml @@ -0,0 +1,129 @@ +name: Publish Changelog + +on: + schedule: + # Run every two weeks on Monday at 9 AM UTC + - cron: '0 9 * * 1' + workflow_dispatch: + inputs: + dry_run: + description: 'Dry run (do not create PR)' + required: false + default: 'false' + +permissions: + contents: write + pull-requests: write + +jobs: + publish: + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v3 + with: + token: ${{ secrets.GITHUB_TOKEN }} + + - name: Setup Node.js + uses: actions/setup-node@v3 + with: + node-version: 18.x + + - name: Install dependencies + run: npm ci + + - name: Check for changelog entries + id: check_entries + run: | + ENTRY_COUNT=$(find .changelogs/entries -name "*.json" -type f | wc -l) + echo "entry_count=$ENTRY_COUNT" >> $GITHUB_OUTPUT + + if [ $ENTRY_COUNT -eq 0 ]; then + echo "ℹ️ No changelog entries to publish" + echo "has_entries=false" >> $GITHUB_OUTPUT + else + echo "📝 Found $ENTRY_COUNT changelog entries to publish" + echo "has_entries=true" >> $GITHUB_OUTPUT + fi + + - name: Publish changelog + if: steps.check_entries.outputs.has_entries == 'true' + run: | + npm run changelog:publish + + - name: Get changelog details + if: steps.check_entries.outputs.has_entries == 'true' + id: changelog_details + run: | + VERSION=$(date +%Y-%m-%d) + echo "version=$VERSION" >> $GITHUB_OUTPUT + + CHANGELOG_FILE="docs/changelog/${VERSION}.mdx" + if [ -f "$CHANGELOG_FILE" ]; then + echo "changelog_exists=true" >> $GITHUB_OUTPUT + else + echo "changelog_exists=false" >> $GITHUB_OUTPUT + fi + + - name: Create Pull Request + if: steps.check_entries.outputs.has_entries == 'true' && steps.changelog_details.outputs.changelog_exists == 'true' && github.event.inputs.dry_run != 'true' + uses: peter-evans/create-pull-request@v5 + with: + token: ${{ secrets.GITHUB_TOKEN }} + commit-message: 'docs: publish changelog ${{ steps.changelog_details.outputs.version }}' + branch: changelog/${{ steps.changelog_details.outputs.version }} + title: '📰 Changelog - ${{ steps.changelog_details.outputs.version }}' + body: | + ## Automated Changelog Release + + This PR contains the aggregated changelog for documentation updates. + + **Version:** ${{ steps.changelog_details.outputs.version }} + **Entry Count:** ${{ steps.check_entries.outputs.entry_count }} + + ### What's included + + This changelog aggregates all documentation updates since the last release, including: + - New documentation pages + - Updates to existing documentation + - Bug fixes and corrections + - Deprecated or removed content + + ### Review Checklist + + - [ ] Review the changelog entries for accuracy + - [ ] Ensure all links are working correctly + - [ ] Verify the formatting is correct + - [ ] Check that all entries are appropriately categorized + + ### After Merging + + Once merged, this changelog will be published to the developer documentation site. + The individual changelog entries have been archived in `.changelogs/published/`. + + --- + + *This PR was automatically created by the changelog publishing workflow.* + labels: | + changelog + documentation + draft: false + + - name: Summary + if: steps.check_entries.outputs.has_entries == 'true' + run: | + echo "## Changelog Publishing Summary" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "✅ Successfully published changelog" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "- **Version:** ${{ steps.changelog_details.outputs.version }}" >> $GITHUB_STEP_SUMMARY + echo "- **Entries:** ${{ steps.check_entries.outputs.entry_count }}" >> $GITHUB_STEP_SUMMARY + echo "- **Dry Run:** ${{ github.event.inputs.dry_run }}" >> $GITHUB_STEP_SUMMARY + + - name: No entries summary + if: steps.check_entries.outputs.has_entries == 'false' + run: | + echo "## Changelog Publishing Summary" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "ℹ️ No changelog entries to publish" >> $GITHUB_STEP_SUMMARY diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 098f7f050..154ba1ea7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,6 +2,7 @@ - [Making a Quick Edit](#making-a-quick-edit) - [Editing Locally](#editing-locally) +- [Creating Changelog Entries](#creating-changelog-entries) - [Commit Messages](#commit-messages) - [Style Guides](#style-guides) - [Contributing to Other Projects](#contributing-to-other-projects) @@ -42,6 +43,53 @@ For more complex changes, fork and edit locally: 5. Create a [pull request](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork) to `bigcommerce:docs/main`. +## Creating Changelog Entries + +When you make changes to documentation, create a changelog entry to track what changed: + +1. **Run the changelog tool:** + ```bash + npm run changelog:add + ``` + +2. **Follow the prompts** to describe your change: + - Select the type of change (added, changed, fixed, etc.) + - Provide a clear title and description + - List all affected documentation files + - Add your GitHub username and PR number (if available) + +3. **Commit the entry** along with your documentation changes: + ```bash + git add .changelogs/entries/*.json + git commit -m "docs: your change description" + ``` + +### When to Create a Changelog Entry + +Create a changelog entry when: +- Adding new documentation pages +- Making significant updates to existing documentation +- Fixing errors or bugs in documentation +- Deprecating or removing documentation +- Making security-related updates + +You may skip creating a changelog entry for: +- Typo fixes +- Minor formatting changes +- Internal documentation updates +- Draft or work-in-progress changes + +If skipping, add the `skip-changelog` label to your pull request. + +### Changelog Entry Tips + +- **Be user-focused**: Write for documentation readers, not internal teams +- **Be specific**: Clearly state what changed and where to find it +- **Link correctly**: Ensure documentation URLs are accurate +- **Review before committing**: Check that your entry is complete and accurate + +For more details, see [.changelogs/README.md](.changelogs/README.md). + ## Commit Messages diff --git a/README.md b/README.md index 0afbf251e..7ba3eb8c2 100644 --- a/README.md +++ b/README.md @@ -53,6 +53,11 @@ Always update your fork to ensure you're working with the newest source files. ```shell . +├── .changelogs/ # automated changelog management + ├── entries/ # ephemeral changelog entries + ├── published/ # archived published changelogs + ├── README.md # changelog system documentation + └── schema.json # JSON schema for changelog entries ├── .github/ # github config └── workflows/ # workflows to lint pull requests, etc. └── ... @@ -67,6 +72,7 @@ Always update your fork to ensure you're working with the newest source files. ├── docs # narrative documentation ├── api-docs/ ├── bigcommerce-for-wordpress/ + ├── changelog/ # published documentation changelogs ├── legacy/ # Blueprint and V2 API docs ├── msf/ # MSF docs ├── partner-apps/ # docs for some partner integrations @@ -79,6 +85,10 @@ Always update your fork to ensure you're working with the newest source files. ├── catalog/ # catalog OAS API reference ├── payments/ # payments OAS API reference └── ... # other OAS API reference +├── scripts/ # automation scripts + ├── changelog-add.js # create new changelog entries + ├── changelog-publish.js # aggregate and publish changelogs + └── changelog-validate.js # validate changelog entry format ├── theme-styles ├── _root # MDX files for Stencil style configuration options ├── .cspell.json @@ -99,6 +109,19 @@ Always update your fork to ensure you're working with the newest source files. ## Archived docs View our archived documentation [here](/archive/). +## Changelog Management + +This repository uses an automated changelog management system to track documentation updates. When making documentation changes: + +1. Create a changelog entry: `npm run changelog:add` +2. Commit the entry with your changes +3. Changelogs are automatically published bi-weekly + +For more information, see: +- [Changelog Management Guide](/docs/changelog/GUIDE.md) +- [Published Changelogs](/docs/changelog/) +- [System Documentation](/.changelogs/README.md) + --- ## Our developer channels: * [Join our Developer Slack space](https://developer.bigcommerce.com/slack) diff --git a/docs/changelog/2025-10-30.mdx b/docs/changelog/2025-10-30.mdx new file mode 100644 index 000000000..6b95d9c33 --- /dev/null +++ b/docs/changelog/2025-10-30.mdx @@ -0,0 +1,13 @@ +# Changelog - 2025-10-30 + +**Release Date:** 2025-10-30 + +This changelog includes all documentation updates and improvements made since the last release. + +## ✨ Added + +* Automatic changelog management system: Introduced a new automated changelog management system inspired by changesets. Documentation contributors can now create changelog entries alongside their changes, which are automatically aggregated and published on a regular cadence. ([Changelog Management System](/.changelogs/README), [Documentation Changelog](/docs/changelog)) + +--- + +*This changelog was automatically generated from 1 documentation update.* diff --git a/docs/changelog/GUIDE.md b/docs/changelog/GUIDE.md new file mode 100644 index 000000000..6537807c4 --- /dev/null +++ b/docs/changelog/GUIDE.md @@ -0,0 +1,293 @@ +# Changelog Management System Guide + +This guide provides detailed information about the automated changelog management system for BigCommerce Developer Documentation. + +## Table of Contents + +1. [Overview](#overview) +2. [Quick Start](#quick-start) +3. [Creating Changelog Entries](#creating-changelog-entries) +4. [Publishing Changelogs](#publishing-changelogs) +5. [Automation](#automation) +6. [Best Practices](#best-practices) +7. [Troubleshooting](#troubleshooting) + +## Overview + +The changelog management system automates the tracking and publishing of documentation changes. It's inspired by the [changesets](https://github.com/changesets/changesets) tool and provides: + +- **Individual changelog entries**: Create small, focused entries alongside documentation changes +- **Automatic aggregation**: Combine entries into comprehensive changelogs +- **Scheduled publishing**: Release changelogs on a regular cadence (bi-weekly) +- **Direct documentation links**: Link to updated documentation pages, not PRs +- **GitHub Actions automation**: Automatic validation and publishing + +## Quick Start + +### For Documentation Contributors + +1. Make your documentation changes +2. Create a changelog entry: + ```bash + npm run changelog:add + ``` +3. Follow the interactive prompts +4. Commit both your changes and the changelog entry + +### For Reviewers + +- Check that PRs with documentation changes include changelog entries +- The CI system will automatically validate entries and remind contributors if missing +- Review changelog entries for accuracy and clarity + +## Creating Changelog Entries + +### Using the CLI Tool + +Run the interactive tool: + +```bash +npm run changelog:add +``` + +The tool will prompt you for: + +1. **Change Type**: Select from: + - `added` - New documentation or features + - `changed` - Updates to existing documentation + - `deprecated` - Documentation marked as deprecated + - `removed` - Removed documentation or features + - `fixed` - Bug fixes or corrections + - `security` - Security-related updates + +2. **Title**: A brief, user-friendly description (10-200 characters) + +3. **Description**: Detailed explanation of what changed and why (minimum 20 characters) + +4. **Affected Documentation**: List all documentation files affected by your change + - Provide the file path (e.g., `docs/api-docs/cart/cart-api.mdx`) + - Optionally provide a title for the page + - The tool will automatically generate the public URL + +5. **Optional Metadata**: + - Your GitHub username + - PR number + - Tags for categorization + - Whether it's a breaking change + +### Manual Creation + +If you prefer to create entries manually, follow this format: + +```json +{ + "id": "unique-timestamp-random", + "timestamp": "2025-10-30T20:00:00.000Z", + "type": "added", + "title": "Brief description of the change", + "description": "Detailed description explaining what changed and why it matters", + "affectedDocs": [ + { + "path": "docs/api-docs/example.mdx", + "url": "/docs/api-docs/example", + "title": "Example Documentation Page" + } + ], + "author": "github-username", + "prNumber": 123, + "tags": ["optional", "tags"], + "breaking": false +} +``` + +Save the file in `.changelogs/entries/` with a `.json` extension. + +### Validating Entries + +To validate your changelog entries: + +```bash +npm run changelog:validate +``` + +Or validate a specific entry: + +```bash +npm run changelog:validate 1730322000000-abc123.json +``` + +## Publishing Changelogs + +### Automatic Publishing (Recommended) + +The system automatically publishes changelogs: +- **Schedule**: Every two weeks on Monday at 9 AM UTC +- **Process**: + 1. Collects all entries from `.changelogs/entries/` + 2. Generates a formatted changelog in `docs/changelog/` + 3. Creates a PR with the aggregated changelog + 4. Archives processed entries to `.changelogs/published/` + +### Manual Publishing + +To manually trigger a changelog release: + +```bash +npm run changelog:publish +``` + +This will: +1. Generate a changelog file for today's date +2. Move entries to the published archive +3. Provide instructions for creating a PR + +### Dry Run + +To test the publishing workflow without creating a PR: + +1. Go to Actions → Publish Changelog +2. Click "Run workflow" +3. Set "Dry run" to `true` +4. Click "Run workflow" + +## Automation + +### GitHub Actions Workflows + +#### Changelog Entry Check (`changelog-entry-check.yml`) + +- **Triggers**: On pull requests that modify documentation +- **Purpose**: Ensures PRs include changelog entries +- **Actions**: + - Checks for documentation file changes + - Verifies presence of changelog entries + - Validates entry format + - Comments on PR if entry is missing + +**Bypass**: Add the `skip-changelog` label to skip this check + +#### Changelog PR Helper (`changelog-pr-helper.yml`) + +- **Triggers**: When a PR is opened/reopened with doc changes +- **Purpose**: Suggests changelog entry content +- **Actions**: + - Analyzes changed files + - Determines appropriate change type + - Generates a suggested entry + - Posts as a comment on the PR + +#### Publish Changelog (`changelog-publish.yml`) + +- **Triggers**: + - Scheduled: Every 2 weeks on Monday at 9 AM UTC + - Manual: Via workflow dispatch +- **Purpose**: Aggregates and publishes changelogs +- **Actions**: + - Collects all changelog entries + - Generates formatted changelog + - Creates a PR with the changes + - Archives processed entries + +## Best Practices + +### Writing Good Changelog Entries + +1. **User-Focused Language** + - ✅ "Added support for webhook validation in the Storefront API" + - ❌ "Implemented webhook validation feature" + +2. **Clear and Specific** + - ✅ "Fixed incorrect parameter type in Cart API documentation" + - ❌ "Fixed docs" + +3. **Complete Context** + - Include all affected documentation pages + - Explain why the change matters + - Provide enough detail for readers to understand the impact + +4. **Consistent Formatting** + - Follow the existing style in published changelogs + - Use proper grammar and punctuation + - Keep titles concise but descriptive + +### When to Create Entries + +**Always create an entry for:** +- New documentation pages +- Significant content updates +- API changes or additions +- Breaking changes +- Security updates +- Bug fixes that affect understanding + +**Consider skipping for:** +- Typo fixes (single word or punctuation) +- Minor formatting adjustments +- Internal documentation +- Work-in-progress changes +- Temporary or draft content + +### Timing + +- Create entries **before** merging your PR +- Include the entry in the same commit as your changes +- Update the entry if you make significant revisions during review + +## Troubleshooting + +### My PR failed the changelog check + +**Solution**: Either create a changelog entry or add the `skip-changelog` label if the change doesn't need tracking. + +### The validation script failed + +**Check**: +- All required fields are present +- Field values meet minimum length requirements +- JSON syntax is valid +- File paths and URLs are correct + +**Fix**: Run `npm run changelog:validate` to see specific errors + +### I made a mistake in my entry + +**Before merging**: +1. Edit the JSON file directly +2. Run `npm run changelog:validate` to verify +3. Commit the fix + +**After merging**: +1. Create a new entry to correct the information +2. The incorrect entry will be archived but won't affect future changelogs + +### The auto-suggestion has wrong information + +The PR helper uses automated analysis and may not always be perfect. Always review and adjust the suggestion before creating your actual entry. + +### How do I link to documentation correctly? + +**File path**: Use the relative path from the repository root +``` +docs/api-docs/cart/cart-api.mdx +``` + +**URL**: Remove the file extension and repository root +``` +/docs/api-docs/cart/cart-api +``` + +The URL should match what users see in their browser when viewing the documentation. + +## Additional Resources + +- [.changelogs/README.md](../.changelogs/README.md) - Quick reference +- [CONTRIBUTING.md](../CONTRIBUTING.md) - General contribution guidelines +- [docs/changelog/](../docs/changelog/) - Published changelogs +- [JSON Schema](../.changelogs/schema.json) - Entry format specification + +## Support + +For questions or issues: +- Open an issue: [github.com/bigcommerce/docs/issues](https://github.com/bigcommerce/docs/issues) +- Start a discussion: [github.com/bigcommerce/docs/discussions](https://github.com/bigcommerce/docs/discussions) +- Review existing changelogs: [developer.bigcommerce.com/docs/changelog](https://developer.bigcommerce.com/docs/changelog) diff --git a/docs/changelog/README.mdx b/docs/changelog/README.mdx new file mode 100644 index 000000000..2dcbe01a3 --- /dev/null +++ b/docs/changelog/README.mdx @@ -0,0 +1,33 @@ +# Documentation Changelog + +Welcome to the BigCommerce Developer Documentation changelog. This section tracks all updates, additions, and improvements to our documentation. + +## About This Changelog + +This changelog is automatically generated from individual changelog entries created by our documentation team. Changes are published on a regular cadence, typically every two weeks. + +## Change Categories + +- **✨ Added**: New documentation, features, or capabilities +- **📝 Changed**: Updates to existing documentation +- **⚠️ Deprecated**: Documentation marked as deprecated +- **🗑️ Removed**: Removed documentation or features +- **🐛 Fixed**: Bug fixes or corrections +- **🔒 Security**: Security-related updates + +## Recent Changelogs + +- [2025-10-30](./2025-10-30.mdx) - Initial changelog system setup + +## How Changes Are Tracked + +When documentation is updated, our team creates changelog entries that describe: +- What changed +- Why it changed +- Where to find the updated documentation + +These entries are then aggregated and published as comprehensive changelogs, making it easy to stay up-to-date with documentation changes. + +## Feedback + +If you have questions about any changes or notice issues with the documentation, please [open an issue](https://github.com/bigcommerce/docs/issues) or [start a discussion](https://github.com/bigcommerce/docs/discussions). diff --git a/package.json b/package.json index 6d6af39ee..0b5b4325f 100644 --- a/package.json +++ b/package.json @@ -10,7 +10,10 @@ "node": ">= 18.0.0" }, "scripts": { - "lint": "eslint ./docs ./archive --ext mdx --max-warnings 0" + "lint": "eslint ./docs ./archive --ext mdx --max-warnings 0", + "changelog:add": "node scripts/changelog-add.js", + "changelog:publish": "node scripts/changelog-publish.js", + "changelog:validate": "node scripts/changelog-validate.js" }, "repository": { "type": "git", diff --git a/pull_request_template.md b/pull_request_template.md index 4675ae58c..e20375e33 100644 --- a/pull_request_template.md +++ b/pull_request_template.md @@ -6,6 +6,13 @@ * +## Changelog Entry + + +- [ ] Changelog entry created (or skip-changelog label added) + ## Release notes draft