docs(changelog): require reconciled fragments, not just new ones (#113)

scripts/build-changelog.test.ts

@@ -488,7 +488,7 @@ test('verifyPullRequestChangelog requires fragments for user-facing changes and
         changedEntries: [{ path: 'src/main-entry.ts', status: 'M' }],
         changedLabels: [],
       }),
-    /requires a changelog fragment/,
+    /requires a reconciled changelog fragment/,
   );
 
   assert.doesNotThrow(() =>
@@ -514,7 +514,7 @@ test('verifyPullRequestChangelog requires fragments for user-facing changes and
         ],
         changedLabels: [],
       }),
-    /requires a changelog fragment/,
+    /requires a reconciled changelog fragment/,
   );
 
   assert.doesNotThrow(() =>
@@ -526,6 +526,27 @@ test('verifyPullRequestChangelog requires fragments for user-facing changes and
       changedLabels: [],
     }),
   );
+
+  assert.doesNotThrow(() =>
+    verifyPullRequestChangelog({
+      changedEntries: [
+        { path: 'src/main-entry.ts', status: 'M' },
+        { path: 'changes/001.md', status: 'M' },
+      ],
+      changedLabels: [],
+    }),
+  );
+
+  assert.doesNotThrow(() =>
+    verifyPullRequestChangelog({
+      changedEntries: [
+        { path: 'src/main-entry.ts', status: 'M' },
+        { path: 'changes/001.md', status: 'A' },
+        { path: 'changes/002.md', status: 'A' },
+      ],
+      changedLabels: [],
+    }),
+  );
 });
 
 test('writePrereleaseNotesForVersion writes cumulative beta notes without mutating stable changelog artifacts', async () => {

scripts/build-changelog.ts

@@ -661,14 +661,15 @@ export function verifyPullRequestChangelog(options: PullRequestChangelogOptions)
     return;
   }
 
-  const hasFragment = normalizedEntries.some(
+  const fragmentEntries = normalizedEntries.filter(
     (entry) => entry.status !== 'D' && isFragmentPath(entry.path),
   );
+  const hasFragment = fragmentEntries.length > 0;
   const requiresFragment = normalizedEntries.some((entry) => !isIgnoredPullRequestPath(entry.path));
 
   if (requiresFragment && !hasFragment) {
     throw new Error(
-      `This pull request changes release-relevant files and requires a changelog fragment under changes/ or the ${SKIP_CHANGELOG_LABEL} label.`,
+      `This pull request changes release-relevant files and requires a reconciled changelog fragment under changes/ or the ${SKIP_CHANGELOG_LABEL} label. Before adding a new fragment, update the existing PR fragment when the new work modifies, fixes, or supersedes behavior already described there.`,
     );
   }
 }