|
| 1 | +--- |
| 2 | +description: "Create a release PR: bump version, update READMEs, RELEASES.md, gruntfile, and commit" |
| 3 | +agent: "agent" |
| 4 | +--- |
| 5 | + |
| 6 | +# Create Release PR |
| 7 | + |
| 8 | +Prepare a release by incrementing the version and updating all required files. Do NOT create a new branch — use the current branch. |
| 9 | + |
| 10 | +## Step 1: Increment the Version |
| 11 | + |
| 12 | +**IMPORTANT: You MUST run the setVersion command FIRST and wait for it to complete BEFORE reading `version.json`.** Do NOT read `version.json` beforehand — the current value is the *old* version. The script increments the version, and only after it finishes will `version.json` contain the correct new version. |
| 13 | + |
| 14 | +Run the following command from the repo root to bump the version based on the `next` field in `version.json`: |
| 15 | + |
| 16 | +``` |
| 17 | +npm run setVersion -- -next |
| 18 | +``` |
| 19 | + |
| 20 | +After the command completes, THEN read `version.json` to determine the new version number (the `release` field). This is referred to as `X.Y.Z` in the steps below. Do NOT assume you know the version from any prior reading of the file. |
| 21 | + |
| 22 | +## Step 2: Update AISKU/README.md CDN Version Table |
| 23 | + |
| 24 | +In [AISKU/README.md](../AISKU/README.md), find the `## CDN Version Release Summary (with Size tracking)` table. |
| 25 | + |
| 26 | +Add a new row for `X.Y.Z` immediately after the nightly row and before the previous release entry. Use this exact format (substitute the actual version): |
| 27 | + |
| 28 | +``` |
| 29 | +| X.Y.Z: | [](https://js.monitor.azure.com/scripts/b/ai.X.Y.Z.js.svg)|  |  |
| 30 | +``` |
| 31 | + |
| 32 | +Remove the oldest version row from the v3.x section to keep the table from growing unbounded (keep the last ~25 v3.x entries). Do NOT remove any v2.x entries. |
| 33 | + |
| 34 | +## Step 3: Update RELEASES.md |
| 35 | + |
| 36 | +In [RELEASES.md](../RELEASES.md): |
| 37 | + |
| 38 | +1. **Create a new release heading** at the top of the file (after the initial note and before any existing release entries), using format: |
| 39 | + ``` |
| 40 | + ## X.Y.Z (Month DDth, YYYY) |
| 41 | + ``` |
| 42 | + Use today's date. The new release section is always inserted at the top — above all existing entries including any beta/alpha/pre-release entries. |
| 43 | + |
| 44 | +2. **Include Significant Changes**: If this release includes significant new features, breaking changes, behavioral changes, package deprecations, or other notable updates, add a `### Significant Changes (since PREV_VERSION)` section (where `PREV_VERSION` is the previous full release version) summarizing them. Review the existing beta/pre-release entry (if any) for content that should be carried forward (duplicated) into the new release. This section should be human-readable and describe the impact to users. |
| 45 | + |
| 46 | + **You MUST always thoroughly review every PR/commit since the previous release** to identify all significant changes — do not rely solely on what was already written in the beta or unreleased sections. PRs that introduce new features, change behavior, deprecate packages, modify default configuration values, or improve reliability/performance should all be included as significant changes even if they were not called out in prior sections. |
| 47 | + |
| 48 | + If any packages have been merged, deprecated, or are now published only as compatibility shims, add a `### Package Deprecation` section describing which packages are affected, that they are still published as shims, and that consumers should migrate to the new package. |
| 49 | + |
| 50 | + If any of the significant changes were previously included in a beta/alpha/pre-release, add a blockquote note immediately after the heading: |
| 51 | + ``` |
| 52 | + > The following are the significant changes since the previous full release (PREV_VERSION). Some of these changes were previously included in the X.Y.Z-beta release. |
| 53 | + ``` |
| 54 | + This makes it clear why content may appear duplicated across release entries. |
| 55 | + |
| 56 | +3. **Include Breaking Changes and Potential Breaking Changes**: If the existing unreleased or beta sections contain `### Breaking Changes` or `### Potential Breaking Changes` or `### Potential behavioral changes` sections, duplicate them into the new release section. Do NOT remove them from the original beta/pre-release entry. |
| 57 | + |
| 58 | +4. **Build the Changelog**: Combine: |
| 59 | + - All entries currently under `## Unreleased Changes (from Main)` changelog |
| 60 | + - All entries from any beta/pre-release section changelog (e.g., `## X.Y.Z-beta`) — these should be **duplicated** into the new release, NOT moved |
| 61 | + - Review git history since the last release tag for any significant PRs that may have been missed |
| 62 | + - Do NOT include PRs that only bump dependency versions (e.g., "bump @microsoft/xxx from A to B") |
| 63 | + - Each entry should be a clickable link: `- #NNNN Description` where `#NNNN` links to the GitHub PR |
| 64 | + |
| 65 | + **CRITICAL: NEVER strip or remove sub-bullet details from changelog entries.** If an entry in the Unreleased section or a prior release includes sub-bullets with additional context (e.g., potential breaking changes, enhancement notes, configuration details), those sub-bullets MUST be preserved exactly as-is in the new release changelog. Do not flatten detailed entries into single-line summaries. |
| 66 | + |
| 67 | +5. **Add a comparison link** at the end of the new release section: |
| 68 | + ``` |
| 69 | + **Full Changelog**: https://github.com/microsoft/ApplicationInsights-JS/compare/PREV_VERSION...X.Y.Z |
| 70 | + ``` |
| 71 | + Where `PREV_VERSION` is the previous release version tag. |
| 72 | + |
| 73 | +6. **Clean up the Unreleased section only**: Remove or comment out the `## Unreleased Changes (from Main)` section content. Leave behind a commented placeholder: |
| 74 | + ``` |
| 75 | + <!-- ## Unreleased Changes --> |
| 76 | + ``` |
| 77 | + |
| 78 | + **CRITICAL: NEVER delete or remove any existing release entries from RELEASES.md** — this includes beta, alpha, RC, and all prior full releases. Even if a beta/pre-release contains the same changes as the new full release, the beta entry must remain in the file. The only section that gets removed is the `## Unreleased Changes (from Main)` section. |
| 79 | + |
| 80 | + Even when told to use version X.Y.Z as the "previous release" for changelog purposes, this only affects which PRs to include in the new entry and the comparison link — it does NOT mean you should delete any intervening release entries (beta, alpha, etc.) from the file. |
| 81 | + |
| 82 | +## Step 4: Update gruntfile.js perfTestVersions |
| 83 | + |
| 84 | +In [gruntfile.js](../gruntfile.js), update the `perfTestVersions` array to include the new version: |
| 85 | + |
| 86 | +```javascript |
| 87 | +const perfTestVersions=["X.Y.Z"]; |
| 88 | +``` |
| 89 | + |
| 90 | +Replace the existing version value — this array should contain only the new release version. |
| 91 | + |
| 92 | +## Step 5: Run lint-fix |
| 93 | + |
| 94 | +Run the following command to ensure all files are properly formatted: |
| 95 | + |
| 96 | +``` |
| 97 | +npm run lint-fix |
| 98 | +``` |
| 99 | + |
| 100 | +## Step 6: Commit |
| 101 | + |
| 102 | +Stage all changes and commit with the message: |
| 103 | + |
| 104 | +``` |
| 105 | +[Release] Increase version to X.Y.Z |
| 106 | +``` |
| 107 | + |
| 108 | +If there are significant changes worth calling out (breaking changes, major new features), add them as additional lines after the subject line. It is valid for this commit to have no additional body content beyond the subject. |
| 109 | + |
| 110 | +Do NOT push the branch — just create the local commit. |
| 111 | + |
| 112 | +## Step 7: Validate the Build |
| 113 | + |
| 114 | +Run the full clean build to ensure no build issues: |
| 115 | + |
| 116 | +``` |
| 117 | +npm run fullCleanBuild |
| 118 | +``` |
| 119 | + |
| 120 | +- **If running from GitHub Actions, automation, or a CI environment**: Run this command directly before creating the PR. Resolve any unexpected build failures before proceeding. |
| 121 | +- **If running interactively from VS Code or Visual Studio**: This command cannot be run from within the editor because open editors and extensions hold file locks that will cause the clean build step to fail. Instead, inform the user that they need to **manually** run `npm run fullCleanBuild` from a **separate terminal** (e.g., Windows Terminal, PowerShell, or Command Prompt) pointed at the repo root, and resolve any issues before creating the PR. |
0 commit comments