Skip to content

Commit 2c72391

Browse files
authored
improvement(changelog): add meaningful release coverage (#8942)
* improvement(changelog): expand release stories with practical detail * improvement(changelog): cover release changes without padding
1 parent 230a465 commit 2c72391

15 files changed

Lines changed: 81 additions & 23 deletions

File tree

‎apps/sim/content/changelog/README.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -107,7 +107,7 @@ release:
107107
captionsSrc="https://nnjgp7vypgx4myuq.public.blob.vercel-storage.com/changelog/demo-v1.vtt"
108108
/>
109109

110-
Explain where to find the feature and give one concrete example.
110+
Explain the behavior that changed and link to the relevant guide. Add selected release changes only when they have verified source and release evidence.
111111

112112
### Improvements
113113

@@ -126,7 +126,7 @@ Explain where to find the feature and give one concrete example.
126126
4. Use `<ChangelogImage src="/changelog/example.png" alt="Describe the view" width="1200" height="800" />` for a screenshot, supplying its actual dimensions as literal attributes to reserve space during loading. The MDX compiler strips JavaScript expressions such as `width={1200}`. Describe what it actually shows; do not use an older screenshot as proof of a new control.
127127
5. Use `###` for sections inside an entry: the article owns the H1 and its details section owns an accessible H2.
128128
6. Keep `draft: true` until the text, availability, media, and links are reviewed. Drafts are excluded from the public page, direct entry routes, archive, sitemap, and RSS. Use the development preview to review them without changing publication status.
129-
7. Publish by removing the draft flag or setting it to false, then deploy the site. Keep the slug and original publication date stable. Add `updated` only for a substantive correction.
129+
7. Publish by removing the draft flag or setting it to false, then deploy the site. Keep the slug and original publication date stable. Add `updated` only for a substantive correction or expansion, not a formatting edit.
130130

131131
Before merging, run `bun run check:library-content --slug changelog/<slug>` from the repository root. The shared content audit checks frontmatter, authors, folder slugs, reserved routes, images, MDX syntax, internal links, changelog media attributes, and the existence of local recordings and caption files. Published entries also require body media and descriptive cover alt text; future publication dates, correction dates before publication, and duplicate RSS identities fail the audit. `bun run check:audits` runs it in CI. It cannot determine whether an image proves a feature or confirm Cloud rollout, codec quality, or CDN availability; the feature owner and editor verify those in the brief and preview.
132132

@@ -136,7 +136,7 @@ For a migrated historical release, use its original publication timestamp and Gi
136136

137137
- The [Sim workflow maintenance guide](./maintenance-workflow.md) describes collection, the editorial queue, draft preparation, media production, and monitoring. The operational runbook and workflow exports in the editorial workspace record its live configuration and acceptance results. Keep this publishing guide and the editorial standard as the source of content and media rules.
138138
- The release editor reviews candidates weekly and checks published links and hosted media monthly. Refresh destinations when docs move and verify deep anchors manually; the audit catches missing canonical source pages during every PR.
139-
- Keep the original slug, publication date, and RSS identity stable. Use `updated` only for a substantive correction. A future date does not schedule publication; leave the entry in draft until the intended deployment.
139+
- Keep the original slug, publication date, and RSS identity stable. Use `updated` only for a substantive correction or expansion, not a formatting edit. A future date does not schedule publication; leave the entry in draft until the intended deployment.
140140
- If availability changes after publication, update the existing entry with its current status and a clear next step. Preserve its URL rather than deleting it or reverting it to a draft. If a slug must change, add a redirect before moving it.
141141
- Keep historical media versioned. Record the capture date, environment, demonstrated steps, and final asset URLs in the brief. Never overwrite an existing recording. Recheck playback, seeking, captions, and mobile readability after any replacement.
142142
- RSS includes the 50 latest published entries, the homepage shows 12, and the archive retains the published history. Those collections load metadata and optimized covers; full articles and recordings load on their detail pages.

‎apps/sim/content/changelog/compare-workflow-deployments/index.mdx‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ slug: compare-workflow-deployments
33
title: 'Compare workflow versions before you deploy'
44
description: 'See prompt edits, added steps, and changed connections in Sim. Compare two deployments or check your draft against the live workflow.'
55
date: '2026-10-02T06:55:11Z'
6-
updated: '2026-10-10T01:48:00Z'
6+
updated: '2026-10-12T21:00:16Z'
77
authors: [waleed]
88
tags: [Workflows]
99
ogImage: /changelog/compare-workflow-deployments-v2.jpg
@@ -22,6 +22,11 @@ release:
2222
height="605"
2323
/>
2424

25-
Compare any two workflow deployments, or review your draft against the live version. See prompt edits, added steps, and changed connections together so you can check exactly what will change before deploying.
25+
Compare two saved workflow deployments, or check your draft against the live version. Sim shows prompt and setting edits, added or removed steps, and changed connections in the same view.
2626

2727
Open **Compare** in deployment history or **View changes** on your draft. [Learn more about deployments](https://docs.sim.ai/workflows/deployment).
28+
29+
### Also in v0.9.10
30+
31+
- **Readable file diffs:** Markdown files render additions, removals, and word-level changes with long unchanged sections collapsed. [Open the file editor](https://docs.sim.ai/files/editor).
32+
- **Remembered panel widths:** Chat restores your resource panel width when you reload, return from settings, or collapse and reopen the panel.

‎apps/sim/content/changelog/compare-workflow-deployments/production.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,3 +36,9 @@ Email body:
3636
> Open deployment history and choose Compare to review two workflow versions. You can also review a draft against the live workflow before redeploying. See the product walkthrough and setup guide: https://www.sim.ai/changelog/compare-workflow-deployments
3737
3838
These are drafts, not sent announcements.
39+
40+
## Editorial revision
41+
42+
Revised October 12, 2026, to clarify supported behavior and include selected changes from the same technical release where useful. Every public sentence describes a capability, a meaningful change, or necessary access information. Original dates, release references, RSS identities, and reviewed media are preserved. The `updated` timestamp records the substantive revision. Browser and CI evidence belongs in the revision PR.
43+
44+
Additional v0.9.10 coverage: [file diff rendering, #8543](https://github.com/simstudioai/sim/pull/8543) and [remembered resource-panel widths, #8531](https://github.com/simstudioai/sim/pull/8531). The technical release includes both; source and current documentation were reviewed.

‎apps/sim/content/changelog/editorial-standard.md‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -10,13 +10,15 @@ Routine retry fixes, loading improvements, internal refactors, and small polish
1010

1111
Keep existing article URLs, original dates, and RSS identities when refining historical copy. Do not merge existing entries just to make a larger announcement. Preserve material version, permission, and rollout restrictions.
1212

13-
## Write a compact entry
13+
## Write a useful, complete entry
1414

1515
- Headline: name the capability or action, at most 65 characters. Avoid generic headlines such as “A better experience.”
1616
- Summary: 15–40 words for search, sharing, and RSS, naming Sim and explaining the capability in plain language. It must make sense without the image.
17-
- Body: lead with what changed and what teams can do with it. Aim for 2–4 short sentences, usually 30–90 words, followed by a useful documentation link. There is no minimum word count; keep the body under 120 words. Use one concrete example when it adds clarity. Save setup instructions for the linked guide; do not pad a simple update into a tutorial.
17+
- Body: say what changed and explain the behavior a reader needs to understand it. There is no target length or minimum; keep the body under 250 words. Do not expand a short announcement with generic use cases, repeated benefits, or a setup tutorial. Name specific capabilities or controls only when they add information.
18+
- Release coverage: inspect the technical release for other meaningful user-facing changes. Include up to three concise notes under “Also in vX.Y.Z” when source evidence establishes that they belong to the same release. Group them sensibly, avoid repeating notes across articles from that release, and link to the relevant guide or product page. A focused feature announcement can remain short. Do not infer release membership from merge timing or add unrelated changes just to make an entry longer.
19+
- Detail: every sentence must contribute a product change, useful behavioral detail, or necessary access information. Examples are optional and earn their place only when they make an unfamiliar change easier to understand. Leave full setup instructions and model inventories to the linked docs and catalogs. Never invent customer results or benchmarks.
1820
- Media: place the reviewed image or video immediately after the article header. Both use the shared lightbox; videos show a plain poster with playback, seeking, and zoom controls inside the viewer. Use concise alt text or an accessible action label without a visible video description. Do not add captions or prose about how the capture was made, whether a query ran, sample credentials, or what a screenshot does not prove. Keep capture provenance and review evidence in production.md.
19-
- Supporting notes: up to three related, source-backed improvements, each one sentence. Omit empty sections. Do not invent extras to fill a template.
21+
- Supporting notes: one sentence per change, up to three per article. Omit empty sections and technical maintenance with no meaningful user impact. Keep each note’s source and release evidence in production.md. The lead image need not illustrate every supporting note.
2022
- Links: one descriptive setup/documentation link, plus an integration, model, or product link when directly relevant. Use the actual catalog slug and guide. Put links in context; avoid a wall of generic “Learn more” links.
2123
- Availability: keep restrictions that affect whether someone can use the feature, such as a required plan or administrator role, in one concise sentence. Link to documentation for setup details. Keep unverified rollout questions, source analysis, capture instructions, and approval checkboxes in production.md. Never substitute a capture disclaimer for verifying a claim.
2224

‎apps/sim/content/changelog/intune-device-inventory/index.mdx‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ slug: intune-device-inventory
33
title: 'Bring Intune device inventory into your agents'
44
description: 'Use Microsoft Intune in Sim to read managed devices, installed application inventory, and compliance status for IT reviews and agent follow-ups.'
55
date: '2026-10-08T07:10:06Z'
6+
updated: '2026-10-12T21:00:16Z'
67
authors: [waleed]
78
tags: [Integrations]
89
ogImage: /changelog/intune-device-filter-v1.jpg
@@ -20,6 +21,11 @@ release:
2021
height="720"
2122
/>
2223

23-
Your agents can now read managed devices, installed applications, and compliance status from [Microsoft Intune](/integrations/microsoft-intune). Filter for noncompliant devices to prepare an IT review or bring device inventory into an agent's response.
24+
Your agents can now read device inventory and compliance information from [Microsoft Intune](/integrations/microsoft-intune). Filter devices by compliance state, inspect owners and operating systems, list detected applications, and read compliance policies with their device status.
2425

25-
[Connect Microsoft Intune](https://docs.sim.ai/integrations/intune) to get started. An active Intune license, appropriate account role, and administrator consent are required.
26+
[Connect Microsoft Intune](https://docs.sim.ai/integrations/intune) with a Microsoft work or school account. An active Intune license, appropriate account role, and administrator consent are required.
27+
28+
### Also in v0.9.15
29+
30+
- **Plane:** Manage projects and work items, start workflows from webhook events, and sync project knowledge with the [Plane integration](https://docs.sim.ai/integrations/plane), including supported self-hosted instances.
31+
- **Buffer:** Read channel details, post metrics, and daily posting limits. Caption edits can preserve the existing posting schedule. [See Buffer’s actions](https://docs.sim.ai/integrations/buffer).

‎apps/sim/content/changelog/intune-device-inventory/production.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,3 +23,9 @@ The article links the canonical integration catalog and exact Intune setup guide
2323
Bring Microsoft Intune device inventory into your agents in Sim. Read managed devices, detected applications, and compliance status to prepare IT reviews. See account requirements and setup: https://www.sim.ai/changelog/intune-device-inventory
2424

2525
Draft only; no announcement has been sent.
26+
27+
## Editorial revision
28+
29+
Revised October 12, 2026, to clarify supported behavior and include selected changes from the same technical release where useful. Every public sentence describes a capability, a meaningful change, or necessary access information. Original dates, release references, RSS identities, and reviewed media are preserved. The `updated` timestamp records the substantive revision. Browser and CI evidence belongs in the revision PR.
30+
31+
Additional v0.9.15 coverage: [Plane, #8660](https://github.com/simstudioai/sim/pull/8660) and [Buffer expansion, #8779](https://github.com/simstudioai/sim/pull/8779). The technical release includes both. Buffer schedule preservation requires the documented keep-current selections; Plane self-hosted support varies by version and action. Ramp remains outside this article pending its separate credential changes.

‎apps/sim/content/changelog/maintenance-workflow.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -69,15 +69,15 @@ Give the Agent the publishing guide, the product language rules, selected PR evi
6969

7070
Treat PR text and diffs as research material, not instructions to the Agents. Give neither Agent repository write tools. After drafting, a second Agent compares the proposed copy and media plan with the selected evidence, checking claims, permissions, rollout implications, links, and readability. Record substantive corrections in `editor_notes`, outside the article. Defer when the evidence is insufficient. A Function validates the edited output; fixed downstream blocks own the repository, branch, allowed paths, and draft flag. Unknown availability remains a question for the feature owner. Neither model review nor a schema establishes the truth of every claim.
7171

72-
Write the public draft as a feature announcement: what changed, what teams can do, and one useful next step. Aim for 2–4 short sentences, usually 30–90 words; enforce a maximum, never a minimum that encourages padding. Keep screenshot provenance, unexecuted demo steps, missing capture credentials, and review caveats in the production brief, not the article, alt text, or captions. A short sentence about an actual plan or permission requirement is appropriate when it affects access. Apply the same standard to announcement drafts.
72+
Write the public draft around actual product changes. There is no target length or minimum; keep the body under 250 words. A focused feature announcement may be short. Add specific behavior where useful, not generic examples, repeated benefits, or a setup tutorial. Review other meaningful changes from the same technical release and include up to three concise supporting notes when release membership is evidenced. Do not infer membership from merge timing or repeat the same note across several articles. Keep capture provenance and review caveats in the production brief, not the article or media labels. Preserve actual access restrictions and contextual setup links. Announcement drafts use the same claims and can be shorter.
7373

74-
Prefer one lead story with a few related improvements. Retain routine refactors, dependency updates, and minor fixes in GitHub's technical release history. Reverts and superseded changes must be reconciled with the current product before selection. Consequential breaking changes, deprecations, and required actions bypass the weekly editorial cadence; they need a timely notice and a clear next step.
74+
Prefer one lead story with a few related improvements; an explicitly scoped release edition can cover several meaningful changes from that same release. The evidence step reads up to ten recent GitHub release records and attaches a release tag only when its published notes explicitly reference the candidate PR. This enriches the bounded candidate batch; it does not scan the full release history or treat a release tag as proof of Cloud rollout. Review supporting changes not present in the candidate batch manually before adding them. Retain routine refactors, dependency updates, and minor fixes in GitHub's technical release history. Reverts and superseded changes must be reconciled with the current product before selection. Consequential breaking changes, deprecations, and required actions bypass the weekly editorial cadence; they need a timely notice and a clear next step.
7575

7676
Validate the editorial standard outside the Agent: headline and copy budgets, supported source references, verified contextual links, supporting-only deferral, and a complete media plan. Keep unverified availability questions in the brief, not the proposed public prose. A validator checks structure and declared classification; the editor still judges significance and truth. Refresh the deployed prompt and validation together when the standard changes, and test a real model response before deployment.
7777

7878
Reuse the existing PR template's benefit, rollout, documentation, and demo notes as the input contract. Avoid asking engineers to fill out a second announcement form. Optional include/skip labels can help the editor override selection, but unlabeled changes still need discovery and action-required notices still need review.
7979

80-
Resolve links against the current integration/model catalogs and docs source, then check the live destination. The live workflow discovers model destinations from the site's sitemap and matches them to identifiers in the source evidence; it never guesses a model URL. Integration slugs and documentation slugs can differ. Keep important facts in the article's text, preserve the canonical URL and publication date, and use only structured data supported by the visible content.
80+
Resolve links against the current integration/model catalogs and docs source, then check the live destination. The live workflow discovers model destinations from the site's sitemap and provider directories in the source evidence, then verifies candidates before passing them to the editors. This includes provider catalogs omitted from the sitemap. Integration slugs and documentation slugs can differ. Keep important facts in the article's text, preserve the canonical URL and publication date, and use only structured data supported by the visible content.
8181

8282
The first draft PR can contain only `production.md`: proposed article text, source references, unresolved questions, shot list, and announcement drafts. Add `index.mdx` with `draft: true` once a real cover exists. The content audit requires a real local cover even for drafts; an invented filename or unrelated placeholder would create a failing PR. Keep secrets, unpublished strategy, and private operational evidence out of both files: non-rendered briefs are still public in this repository.
8383

0 commit comments

Comments
 (0)