From 1cfb77fec2186146e1db0f8abcdac726dde7030d Mon Sep 17 00:00:00 2001 From: Kim Pohas Date: Wed, 2 Sep 2026 05:57:31 -0700 Subject: [PATCH 1/3] DOCS-12 - Remove marketing language from release note templates and style guide Co-Authored-By: Claude Sonnet 4.6 --- .claude/commands/release-note-collector.md | 14 +++++++------- .claude/commands/release-note-cse.md | 2 +- .claude/commands/release-note-csoar.md | 2 ++ .claude/commands/release-note-developer.md | 8 +++++--- .claude/commands/release-note-service.md | 8 +++++++- .claude/skills/sumo-style/SKILL.md | 1 + docs/contributing/style-guide.md | 10 ++++++++++ 7 files changed, 33 insertions(+), 12 deletions(-) diff --git a/.claude/commands/release-note-collector.md b/.claude/commands/release-note-collector.md index faef82018f6..50858dd4d25 100644 --- a/.claude/commands/release-note-collector.md +++ b/.claude/commands/release-note-collector.md @@ -122,7 +122,7 @@ import useBaseUrl from '@docusaurus/useBaseUrl'; #### Installed Collector Release Structure ```markdown -In this release, we've enhanced the security and stability of the Collector with added support for security patches. +This release includes security and stability fixes. #### Security fix @@ -136,7 +136,7 @@ In this release, we've enhanced the security and stability of the Collector with ``` **Installed Collector Guidelines:** -* Start with standard intro: "In this release, we've enhanced the security and stability of the Collector with added support for {security patches/bug fixes/features}." +* Start with a direct intro: "This release includes {security patches/bug fixes/features}." * Use H4 (`####`) for section headings: Security fix, Bug fix, Feature * List items use bullet points with dashes. * Include specific version numbers for dependencies. @@ -146,7 +146,7 @@ In this release, we've enhanced the security and stability of the Collector with **Example:** ```markdown -In this release, we've enhanced the security and stability of the Collector with added support for security patches. +This release includes security and stability fixes. #### Security fix @@ -161,7 +161,7 @@ In this release, we've enhanced the security and stability of the Collector with #### OpenTelemetry Release Structure ```markdown -We're excited to {announce/introduce} {feature description}. {What it does and benefits}. [Learn more](/docs/path/to/doc). +{Feature name} {is now available / now supports X / now includes Y}. {What it does and benefits}. [Learn more](/docs/path/to/doc). {Optional: Additional paragraphs with more details} @@ -171,7 +171,7 @@ We're excited to {announce/introduce} {feature description}. {What it does and b ``` **OpenTelemetry Guidelines:** -* Start with "We're excited to announce..." or "We're excited to introduce...". +* Open with a direct statement: "[Feature] is now available." or "[Feature] now supports [X]." * Write 2-3 sentences in first paragraph. * Focus on user benefits and business value. * End first paragraph with "Learn more" link. @@ -183,14 +183,14 @@ We're excited to {announce/introduce} {feature description}. {What it does and b ```markdown import useBaseUrl from '@docusaurus/useBaseUrl'; -We're excited to announce that you can now convert Installed Collector (IC) local file sources to OpenTelemetry (OTel) source templates for a more modern, scalable, and consistent data collection experience. This conversion helps future-proof your setup, making it easier to manage collectors at scale while benefiting from ongoing OTel improvements and support. [Learn more](/docs/send-data/installed-collectors/sources/convert-ic-local-file-source-to-otel-st/). +You can now convert Installed Collector (IC) local file sources to OpenTelemetry (OTel) source templates for a more modern, scalable, and consistent data collection experience. This conversion makes it easier to manage collectors at scale while benefiting from ongoing OTel improvements and support. [Learn more](/docs/send-data/installed-collectors/sources/convert-ic-local-file-source-to-otel-st/). ``` **Example (Infrastructure change):** ```markdown import useBaseUrl from '@docusaurus/useBaseUrl'; -We're excited to announce that the OpenTelemetry collector installation files can now be downloaded from a CDN for Chef, Puppet, and Ansible. This change improves download reliability, performance, and availability while maintaining the same installation experience. +OpenTelemetry collector installation files can now be downloaded from a CDN for Chef, Puppet, and Ansible. This change improves download reliability, performance, and availability while maintaining the same installation experience. Refer to the following documentation to view the updated URLs in the UI. * [Ansible](/docs/send-data/opentelemetry-collector/install-collector/ansible/). diff --git a/.claude/commands/release-note-cse.md b/.claude/commands/release-note-cse.md index 41e36c6c668..5f99f4bc1c5 100644 --- a/.claude/commands/release-note-cse.md +++ b/.claude/commands/release-note-cse.md @@ -177,7 +177,7 @@ Additional changes are enumerated below. **Application Release Guidelines:** * Use H3 (`###`) for each feature. -* Start with clear, concise description. +* Open with a direct statement of what the feature does — not an announcement phrase ("We're excited to announce", "We're happy to introduce"). Example: "Field X now supports Y." or "Feature Z is now available." * Include "Learn more" link to relevant docs. * Keep it brief (2-3 sentences per feature). * Add screenshots using: `description` diff --git a/.claude/commands/release-note-csoar.md b/.claude/commands/release-note-csoar.md index ebe2508bbd1..54286983f3d 100644 --- a/.claude/commands/release-note-csoar.md +++ b/.claude/commands/release-note-csoar.md @@ -253,6 +253,8 @@ Fixed an issue where [description of bug and fix]. ### Step 7: Content formatting guidelines +Open with a direct statement of what the release contains. Do not use excitement or announcement phrases ("We're excited to introduce", "We're happy to announce", "We've added"). State what changed factually. + ## Content Release Formatting #### Intro Paragraph diff --git a/.claude/commands/release-note-developer.md b/.claude/commands/release-note-developer.md index 8b11cce1d06..92054e90c97 100644 --- a/.claude/commands/release-note-developer.md +++ b/.claude/commands/release-note-developer.md @@ -156,6 +156,8 @@ hide_table_of_contents: true ### Step 6: Content formatting guidelines +Open with a direct statement of what changed. Do not use announcement or excitement phrases ("We're excited to announce", "We've released", "We've made improvements to"). State the change factually: "[Feature] is now available." or "[Feature] now supports [X]." + #### API Changes For API announcements, include: @@ -172,7 +174,7 @@ image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-cente hide_table_of_contents: true --- -We're excited to announce new API endpoints for managing Field Extraction Rules (FERs) programmatically. These endpoints enable you to create, update, delete, and list FERs via the REST API, making it easier to automate and scale your field extraction configurations. +New API endpoints for managing Field Extraction Rules (FERs) are now available. These endpoints enable you to create, update, delete, and list FERs via the REST API, making it easier to automate and scale your field extraction configurations. #### New endpoints @@ -203,7 +205,7 @@ keywords: - python --- -We've released version 2.0 of the Sumo Logic Python SDK with support for the latest APIs and improved error handling. +Sumo Logic Python SDK version 2.0 is now available, with support for the latest APIs and improved error handling. #### What's new @@ -286,7 +288,7 @@ image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-cente hide_table_of_contents: true --- -We've made the following improvements to our APIs: +The following API improvements are now available: * **Audit logging**: When performing create, update, and delete requests through Sumo Logic APIs, the API accessID is now included within the operator field of your related [Audit Event Index](/docs/manage/security/audit-indexes/audit-event-index) messages. * **Search Job API**: Now returns query execution statistics in response headers for better monitoring and debugging. diff --git a/.claude/commands/release-note-service.md b/.claude/commands/release-note-service.md index 4126e3a28b4..a40cdec91a4 100644 --- a/.claude/commands/release-note-service.md +++ b/.claude/commands/release-note-service.md @@ -197,7 +197,11 @@ This enhancement streamlines your workflow by providing quick access to frequent ### Step 6: Content formatting guidelines **Write for clarity:** -* Start with a clear statement of what the feature is +* Open with a direct statement of what the feature is — never an announcement phrase ("We're excited to introduce", "We're happy to announce") + * ❌ "We're excited to announce that multi-child-org search results now include an `_orgName` field..." + * ✅ "Multi-child-org search results now include an `_orgName` field alongside `_orgId`, so MSSP users can identify which child org a result came from." + * ❌ "We are excited to announce the addition of a native Sumo Logic HTTP Source webhook integration for LiteLLM." + * ✅ "A native Sumo Logic HTTP Source webhook integration for LiteLLM is now available, enabling you to collect LiteLLM usage and proxy log data." * Explain the benefit or business value in 2-3 sentences * Use "What's new:" section for bulleted specifics (optional) * End with a "Learn more" link to relevant docs @@ -443,6 +447,8 @@ Would you like me to help refine the content or add additional details? ## Tips and best practices **For all Service releases:** +* Open with a direct statement of what changed: "[Feature] is now available." or "[Feature] now supports [X]." +* Do not open with announcement phrases: "We're excited to introduce", "We're happy to announce", and similar * Lead with user benefit, not technical implementation * Explain "what" and "why", not "how" * Keep descriptions concise (2-3 sentences) diff --git a/.claude/skills/sumo-style/SKILL.md b/.claude/skills/sumo-style/SKILL.md index 3d113e8158f..7e4d31ee28f 100644 --- a/.claude/skills/sumo-style/SKILL.md +++ b/.claude/skills/sumo-style/SKILL.md @@ -219,3 +219,4 @@ These are Sumo Logic- and repo-specific facts that override general assumptions. - **Numbered list items always use `1.`** (not `1.`, `2.`, `3.`). Docusaurus handles rendering. - **Capitalized product terms.** Collector, Source, Hosted Collector, Library. User-created objects (dashboards, folders) are lowercase. - **C2C sources and apps have distinct openers.** Do not use the app opener for a source doc or vice versa. +- **No marketing openers in release notes.** Do not open with "We're excited to introduce/announce", "We're happy to announce", "We're thrilled to share", or similar phrases. Use a direct statement instead: "[Feature] is now available." or "[Feature] now supports [X]." Example — ❌ "We're excited to announce that multi-child-org search results now include an `_orgName` field..." → ✅ "Multi-child-org search results now include an `_orgName` field..." diff --git a/docs/contributing/style-guide.md b/docs/contributing/style-guide.md index a1685750563..00f73b1cde1 100644 --- a/docs/contributing/style-guide.md +++ b/docs/contributing/style-guide.md @@ -992,6 +992,16 @@ Release notes (our changelog) publish to both the [docs site](/docs/release-note For lengthy release notes, write a 1-2 paragraph introduction, then add a truncate line (``), followed by the full set of release notes. +**Release note language** + +Open with a direct statement of what changed. Do not use excitement or announcement phrases. + +| ✅ **Do** | ❌ **Don't** | +|:---------------|:-------------------| +| "Multi-child-org search results now include an `_orgName` field alongside `_orgId`, so MSSP users can identify which child org a result came from." | "We're excited to announce that multi-child-org search results now include an `_orgName` field..." | +| "A native Sumo Logic HTTP Source webhook integration for LiteLLM is now available, enabling you to collect LiteLLM usage and proxy log data." | "We are excited to announce the addition of a native Sumo Logic HTTP Source webhook integration for LiteLLM." | +| "This release includes security and stability fixes." | "We've enhanced the security and stability of the Collector." | + ## Reusing content When the same passage appears in more than one doc, put it once in the [`/docs/reuse`](https://github.com/SumoLogic/sumologic-documentation/tree/main/docs/reuse) folder and import it where you need it. Add the import at the top of the file, then place the component where the content should appear: From 15f8091b3de65285206077c90335e724e1600a7d Mon Sep 17 00:00:00 2001 From: Kim Pohas Date: Thu, 10 Sep 2026 15:15:25 -0700 Subject: [PATCH 2/3] DOCS-12 - Rewrite the release notes section of the style guide Make this section the single source of truth for how release notes are written across all five blog folders. Restructure it into Writing style (shared rules plus the no-marketing-language do/don't table), Structure and frontmatter, and a Per-folder conventions table that replaces the interleaved per-type exceptions in the old numbered steps. Standardize the title date format to `Month D, YYYY` (full month name, no ordinal, no leading zero), per the Dates section. State that the `YYYY-MM-DD-` filename prefix is required because the Docusaurus blog plugin derives the publish date and sort order from it. Co-Authored-By: Claude Sonnet 5 --- docs/contributing/style-guide.md | 46 +++++++++++++++++++++++++------- 1 file changed, 36 insertions(+), 10 deletions(-) diff --git a/docs/contributing/style-guide.md b/docs/contributing/style-guide.md index 00f73b1cde1..ab8c9cb8dee 100644 --- a/docs/contributing/style-guide.md +++ b/docs/contributing/style-guide.md @@ -980,21 +980,17 @@ In the UI, avoid periods for single sentences on their own. Whenever there are t ## Release notes -Release notes (our changelog) publish to both the [docs site](/docs/release-notes) and an RSS feed. Keep them concise and link to the relevant documentation. +Release notes are our changelog. They publish to the [docs site](/docs/release-notes) and to an RSS feed, and readers scan them to see what changed and whether it affects them. Keep every note short and link out for detail. -1. In the matching blog folder ([blog-collector](https://github.com/SumoLogic/sumologic-documentation/tree/main/blog-collector), [blog-cse](https://github.com/SumoLogic/sumologic-documentation/tree/main/blog-cse), [blog-csoar](https://github.com/SumoLogic/sumologic-documentation/tree/main/blog-csoar), [blog-developer](https://github.com/SumoLogic/sumologic-documentation/tree/main/blog-developer), [blog-service](https://github.com/SumoLogic/sumologic-documentation/tree/main/blog-service)), add a file named like the other posts in that folder. For blog-service it's `YYYY-MM-DD-`; for Cloud SIEM and SOAR it's `YYYY-MM-DD-application-update` or `YYYY-MM-DD-content-update`. -1. Copy the frontmatter from a recent post in the same folder and update the values. Two fields are specific to release notes: - * `hide_table_of_contents: true`. Hides the TOC so the notes render clean and full-width. - * `image`. Used by the RSS feed and social card. If the note has no screenshot to feature, point it at the Sumo Logic logo: `https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg`. +Each product area has its own blog folder: [blog-service](https://github.com/SumoLogic/sumologic-documentation/tree/main/blog-service), [blog-collector](https://github.com/SumoLogic/sumologic-documentation/tree/main/blog-collector), [blog-cse](https://github.com/SumoLogic/sumologic-documentation/tree/main/blog-cse), [blog-csoar](https://github.com/SumoLogic/sumologic-documentation/tree/main/blog-csoar), and [blog-developer](https://github.com/SumoLogic/sumologic-documentation/tree/main/blog-developer). Add your note to the matching folder and copy a recent post in that folder as your model for filename, frontmatter, and structure. Conventions that differ by folder are in [Per-folder conventions](#per-folder-conventions). - For service release notes, append the category in parentheses to the `title` (for example, `Automatic Log Level Detection (Search)`). Check recent service notes for category names. -1. Write the note. Add links, bullets, and images as needed. +Every post filename must start with `YYYY-MM-DD-`. The Docusaurus blog plugin takes the publish date and sort order from that prefix, not from frontmatter or the title. -For lengthy release notes, write a 1-2 paragraph introduction, then add a truncate line (``), followed by the full set of release notes. +### Writing style -**Release note language** +These rules apply to every release note, in every folder. -Open with a direct statement of what changed. Do not use excitement or announcement phrases. +* **Open with a direct statement of what changed.** Do not use excitement or announcement phrases. Announcement framing ("We're excited to...") delays the information and adds nothing the reader can act on. This is the [Professional description](#voice-and-tone) principle applied to the changelog: state the change and let it speak for itself. This applies to the opening framing, not to warmth elsewhere in the note. | ✅ **Do** | ❌ **Don't** | |:---------------|:-------------------| @@ -1002,6 +998,36 @@ Open with a direct statement of what changed. Do not use excitement or announcem | "A native Sumo Logic HTTP Source webhook integration for LiteLLM is now available, enabling you to collect LiteLLM usage and proxy log data." | "We are excited to announce the addition of a native Sumo Logic HTTP Source webhook integration for LiteLLM." | | "This release includes security and stability fixes." | "We've enhanced the security and stability of the Collector." | +* **Lead with the benefit.** Say what the reader can now do and why it matters, not how it was built. +* **Be concise.** Two to three sentences for a feature. One sentence per list item. +* **End the opening paragraph with a "Learn more" link** to the relevant doc, using a [relative path](#links) that starts with `/docs/`. +* **Mark breaking changes and prerequisites** with an [admonition](#admonitions). +* **Add screenshots** with `useBaseUrl`, following [Images](#images). +* **Write title dates as `Month D, YYYY`.** Full month name, no ordinal, no leading zero (`March 9, 2026`, not `March 9th, 2026` or `March 09, 2026`). See [Dates](#dates). + +### Structure and frontmatter + +When a note runs long, write a one to two paragraph introduction, add a truncate line (``), then the full set of notes. List views on the site and in the RSS feed show only the text above that line. + +Copy the frontmatter from a recent post in the same folder. Two fields matter for every release note: + +* `hide_table_of_contents: true`. Renders the note clean and full-width. +* `image`. Used by the RSS feed and the social card. Use a screenshot from the note if it has one, otherwise the Sumo Logic logo: `https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg`. + +Add `keywords` when they aid discoverability. Suggest them by topic and confirm the list before publishing. + +### Per-folder conventions + +Everything above is shared. These are the differences by folder. When in doubt, match a recent post in the same folder. + +| Folder | Filename | Title | Feature heading | Notes | +|:---|:---|:---|:---|:---| +| `blog-service` | `YYYY-MM-DD-` | Feature description in title case, then the category in parentheses: `(Apps)`, `(Collection)`, `(Manage)`, `(Search)`, `(New UI)`. No date in the title. | n/a | One feature per note. | +| `blog-collector` | `YYYY-MM-DD-installed` or `YYYY-MM-DD-otel` | Installed Collector: `Installed Collector Version X.Y.Z-N`. OpenTelemetry: feature name in title case, no category. | H4: `Security fix`, `Bug fix`, `Feature` | Order sections security, then bug fixes, then features. Cite CVE or GHSA IDs. | +| `blog-cse` | `YYYY-MM-DD-content` or `YYYY-MM-DD-application` | `Month D, YYYY - Content Release` or `Month D, YYYY - Application Update` | H3 per feature | Content releases: tag entries `[New]` or `[Updated]` and group them under Rules, Log Mappers, and Parsers. | +| `blog-csoar` | `YYYY-MM-DD-content-release` or `YYYY-MM-DD-application-update` | `Month D, YYYY - Content Release` or `Month D, YYYY - Application Update` | Content: H3. Application: H3 with H4 sub-sections. | Content releases are simple lists. Application updates carry descriptions and a Bug Fixes section. | +| `blog-developer` | `YYYY-MM-DD-` | `Month D, YYYY - Topic` | H4 sub-sections | Note the impact: breaking change, deprecation, new feature, or minor change. | + ## Reusing content When the same passage appears in more than one doc, put it once in the [`/docs/reuse`](https://github.com/SumoLogic/sumologic-documentation/tree/main/docs/reuse) folder and import it where you need it. Add the import at the top of the file, then place the component where the content should appear: From 41b08680c4ee97f4116a602af35c87d12ea6f0d5 Mon Sep 17 00:00:00 2001 From: Kim Pohas Date: Thu, 10 Sep 2026 15:15:25 -0700 Subject: [PATCH 3/3] DOCS-12 - Point release note templates to the style guide Trim the five release-note-*.md commands and the sumo-style skill so editorial guidance lives only in the style guide. Remove restated voice, conciseness, and "Learn more" bullets, and the date rules that are now wrong after the Month D, YYYY standardization: the Cloud SIEM "use ordinal suffixes" rules and `{Day}th` placeholder, the Cloud SOAR "zero-padded day" rules and examples, and the Collector checklist line that still said 'Starts with "We're excited to..."'. Each spot now links to /docs/contributing/style-guide/#release-notes. Mechanical scaffolding (heading levels, [New]/[Updated] tags, CVE format, frontmatter blocks, workflow steps) is unchanged. Co-Authored-By: Claude Sonnet 5 --- .claude/commands/release-note-collector.md | 10 ++--- .claude/commands/release-note-cse.md | 35 ++++++---------- .claude/commands/release-note-csoar.md | 49 +++++++++------------- .claude/commands/release-note-developer.md | 18 +++----- .claude/commands/release-note-service.md | 23 +++------- .claude/skills/sumo-style/SKILL.md | 2 +- 6 files changed, 47 insertions(+), 90 deletions(-) diff --git a/.claude/commands/release-note-collector.md b/.claude/commands/release-note-collector.md index 50858dd4d25..27304368b20 100644 --- a/.claude/commands/release-note-collector.md +++ b/.claude/commands/release-note-collector.md @@ -141,8 +141,8 @@ This release includes security and stability fixes. * List items use bullet points with dashes. * Include specific version numbers for dependencies. * Reference CVE numbers when applicable (format: CVE-YYYY-NNNNN or GHSA-XXXX-XXXX-XXXX) -* Keep descriptions concise (one sentence per item). * Order: Security fixes first, then bug fixes, then features +* For everything else (voice, conciseness), follow [Release notes](/docs/contributing/style-guide/#release-notes) in the style guide. **Example:** ```markdown @@ -171,12 +171,8 @@ This release includes security and stability fixes. ``` **OpenTelemetry Guidelines:** -* Open with a direct statement: "[Feature] is now available." or "[Feature] now supports [X]." -* Write 2-3 sentences in first paragraph. -* Focus on user benefits and business value. -* End first paragraph with "Learn more" link. +* Follow [Release notes](/docs/contributing/style-guide/#release-notes) in the style guide for voice, conciseness, and "Learn more" links. * Can include additional paragraphs for context. -* Use relative paths for documentation links (start with `/docs/`). * Add admonitions for important notes or breaking changes. **Example (Feature announcement):** @@ -215,7 +211,7 @@ Before finishing, verify: * [ ] For installed: Sections use H4 (`####`), proper order (Security → Bug → Feature) * [ ] For installed: Version numbers in **bold** format * [ ] For installed: CVE/GHSA references included where applicable -* [ ] For OTel: Starts with "We're excited to..." +* [ ] For OTel: Opens with a direct statement, not an announcement phrase (see the [style guide](/docs/contributing/style-guide/#release-notes)) * [ ] For OTel: "Learn more" link included with relative path * [ ] No trailing whitespace. diff --git a/.claude/commands/release-note-cse.md b/.claude/commands/release-note-cse.md index 5f99f4bc1c5..478b7e654d5 100644 --- a/.claude/commands/release-note-cse.md +++ b/.claude/commands/release-note-cse.md @@ -92,7 +92,7 @@ Examples: **For Content Releases:** ```yaml --- -title: {Month} {Day}th, {Year} - Content Release +title: {Month} {Day}, {Year} - Content Release hide_table_of_contents: true keywords: * rules @@ -120,9 +120,9 @@ hide_table_of_contents: true * Application releases: Feature-specific keywords (e.g., `insights`, `entities`, `signals`, `cloud siem`) * User may want to add or modify keywords based on specific content -**Date formatting:** -* Use ordinal suffixes: "March 12th", "February 3rd", "January 21st" -* Full month name, not abbreviated. +**Title and date formatting:** +* `{Month} {D}, {Year} - Content Release` or `{Month} {D}, {Year} - Application Update` +* Follow the [style guide](/docs/contributing/style-guide/#release-notes) date format: full month name, no ordinal, no leading zero (`March 12, 2026`). ### Step 4: Add required import @@ -177,29 +177,20 @@ Additional changes are enumerated below. **Application Release Guidelines:** * Use H3 (`###`) for each feature. -* Open with a direct statement of what the feature does — not an announcement phrase ("We're excited to announce", "We're happy to introduce"). Example: "Field X now supports Y." or "Feature Z is now available." -* Include "Learn more" link to relevant docs. -* Keep it brief (2-3 sentences per feature). * Add screenshots using: `description` -* Highlight business value and user impact. +* For voice, conciseness, and "Learn more" links, follow [Release notes](/docs/contributing/style-guide/#release-notes) in the style guide. ### Step 6: Format dates and titles -**Title formatting rules:** -* Month: Full name (March, not Mar) -* Day: Ordinal suffix (12th, 3rd, 21st) - * 1st, 2nd, 3rd. - * 4th-20th end in "th". - * 21st, 22nd, 23rd, 31st. - * 24th-30th end in "th". -* Year: Full 4 digits -* Type: "Content Release" or "Application Update" +Title format: `{Month} {D}, {Year} - Content Release` or `{Month} {D}, {Year} - Application Update`. + +Dates follow the [style guide](/docs/contributing/style-guide/#release-notes): full month name, no ordinal, no leading zero. Examples: -* ✅ "March 19th, 2026 - Content Release". -* ✅ "February 3rd, 2026 - Application Update". +* ✅ "March 19, 2026 - Content Release". +* ✅ "February 3, 2026 - Application Update". * ❌ "Mar 19, 2026 - Content Release" (month abbreviated). -* ❌ "March 19 2026 - Content Release" (missing "th"). +* ❌ "March 19th, 2026 - Content Release" (ordinal suffix). ### Step 7: Validation checklist @@ -207,7 +198,7 @@ Before finishing, verify: * [ ] File created in `/blog-cse/` directory (not `/docs/`). * [ ] Filename follows pattern: `YYYY-MM-DD-{type}.md` * [ ] Frontmatter complete with all required fields. -* [ ] Title formatted correctly with ordinal suffix. +* [ ] Title date formatted correctly (`Month D, YYYY`, no ordinal). * [ ] `hide_table_of_contents: true` present * [ ] Keywords appropriate for release type. * [ ] `import useBaseUrl` statement included. @@ -228,7 +219,7 @@ Claude: 1. Confirms date: 2026-03-19 2. Confirms type: Content Release 3. Creates: blog-cse/2026-03-19-content.md -4. Generates frontmatter with proper title: "March 19th, 2026 - Content Release" +4. Generates frontmatter with proper title: "March 19, 2026 - Content Release" 5. Adds summary section 6. Creates sections for Rules and Log Mappers 7. Formats with proper [New]/[Updated] tags diff --git a/.claude/commands/release-note-csoar.md b/.claude/commands/release-note-csoar.md index 54286983f3d..1ea41aa1b2c 100644 --- a/.claude/commands/release-note-csoar.md +++ b/.claude/commands/release-note-csoar.md @@ -134,7 +134,7 @@ Examples: **For Content Release:** ```yaml --- -title: {Month DD, YYYY} - Content Release +title: {Month D, YYYY} - Content Release hide_table_of_contents: true image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 keywords: @@ -147,7 +147,7 @@ keywords: **For Application Update:** ```yaml --- -title: {Month DD, YYYY} - Application Update +title: {Month D, YYYY} - Application Update hide_table_of_contents: true image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 keywords: @@ -157,12 +157,8 @@ keywords: ``` **Title formatting:** -* Start with full date: "Month DD, YYYY" (e.g., "June 05, 2024" or "March 06, 2026") -* Follow with " - Content Release" or " - Application Update" - -**Date formatting:** -* Use full month name (January, February, March, etc.) -* Use zero-padded day (01, 05, 06, 08, not 1, 5, 6, 8) +* Start with the date, then " - Content Release" or " - Application Update" (e.g., "June 5, 2024 - Content Release") +* Dates follow the [style guide](/docs/contributing/style-guide/#release-notes): full month name, no ordinal, no leading zero **Keywords:** * **Always ask user to confirm keywords before creating file** @@ -187,7 +183,7 @@ import useBaseUrl from '@docusaurus/useBaseUrl'; **Content Release template:** ```markdown --- -title: June 05, 2024 - Content Release +title: June 5, 2024 - Content Release hide_table_of_contents: true image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 keywords: @@ -214,7 +210,7 @@ This release introduces new integrations, new playbooks, and several updates. **Application Update template:** ```markdown --- -title: March 06, 2026 - Application Update +title: March 6, 2026 - Application Update hide_table_of_contents: true image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 keywords: @@ -253,7 +249,7 @@ Fixed an issue where [description of bug and fix]. ### Step 7: Content formatting guidelines -Open with a direct statement of what the release contains. Do not use excitement or announcement phrases ("We're excited to introduce", "We're happy to announce", "We've added"). State what changed factually. +Voice and wording follow [Release notes](/docs/contributing/style-guide/#release-notes) in the style guide. The formatting below is specific to Cloud SOAR release notes. ## Content Release Formatting @@ -374,8 +370,8 @@ Fixed issues while selecting variables containing the period character in textar **For Content Release:** * [ ] File created in `/blog-csoar/` directory * [ ] Filename is `YYYY-MM-DD-content-release.md` -* [ ] Title is "Month DD, YYYY - Content Release" (zero-padded day) -* [ ] Date uses full month name with zero-padded day (e.g., "June 05") +* [ ] Title is "Month D, YYYY - Content Release" (no ordinal, no leading zero) +* [ ] Date uses full month name, no leading zero (e.g., "June 5") * [ ] Image URL: Standard Sumo Logic preview image * [ ] Keywords: automation service, cloud soar, soar (three keywords) * [ ] `hide_table_of_contents: true` is present @@ -389,8 +385,8 @@ Fixed issues while selecting variables containing the period character in textar **For Application Update:** * [ ] File created in `/blog-csoar/` directory * [ ] Filename is `YYYY-MM-DD-application-update.md` -* [ ] Title is "Month DD, YYYY - Application Update" (zero-padded day) -* [ ] Date uses full month name with zero-padded day (e.g., "March 06") +* [ ] Title is "Month D, YYYY - Application Update" (no ordinal, no leading zero) +* [ ] Date uses full month name, no leading zero (e.g., "March 6") * [ ] Image URL: Standard Sumo Logic preview image * [ ] Keywords: automation service, cloud soar (two keywords) * [ ] `hide_table_of_contents: true` is present @@ -414,7 +410,7 @@ Claude: 2. Confirms date: June 5, 2024 3. Creates: blog-csoar/2024-06-05-content-release.md 4. Generates frontmatter: - - title: "June 05, 2024 - Content Release" + - title: "June 5, 2024 - Content Release" - image: Standard Sumo Logic preview image - keywords: automation service, cloud soar, soar 5. Writes content with: @@ -435,7 +431,7 @@ Claude: 3. Confirms release month: February 4. Creates: blog-csoar/2026-03-06-application-update.md 5. Generates frontmatter: - - title: "March 06, 2026 - Application Update" + - title: "March 6, 2026 - Application Update" - keywords: automation service, cloud soar 6. Writes content with: - H2: "## February release" @@ -468,22 +464,15 @@ Cloud SOAR API docs: ## Date formatting rules -**Format: "Month DD, YYYY"** - -Month names (full): -* January, February, March, April, May, June -* July, August, September, October, November, December - -Day: Zero-padded two digits (use 01, 06, 08, 15... not 1, 6, 8) +Titles use the [style guide](/docs/contributing/style-guide/#release-notes) date format: `Month D, YYYY`, full month name, no ordinal, no leading zero. **Examples:** -* ✅ March 06, 2026 -* ✅ January 08, 2026 +* ✅ March 6, 2026 +* ✅ January 8, 2026 * ✅ December 31, 2025 -* ✅ June 05, 2024 -* ❌ March 6, 2026 (not zero-padded) -* ❌ March 6th, 2026 (has ordinal) -* ❌ Mar 06, 2026 (abbreviated month) +* ❌ March 06, 2026 (leading zero) +* ❌ March 6th, 2026 (ordinal) +* ❌ Mar 6, 2026 (abbreviated month) * ❌ 2026-03-06 (wrong format) ## Release timing diff --git a/.claude/commands/release-note-developer.md b/.claude/commands/release-note-developer.md index 92054e90c97..b76fd279e42 100644 --- a/.claude/commands/release-note-developer.md +++ b/.claude/commands/release-note-developer.md @@ -94,9 +94,7 @@ hide_table_of_contents: true * Keep topic concise but descriptive **Date formatting:** -* Use full month name (January, February, March, etc.) -* Use day without ordinal suffix (1, 9, 23, not 1st, 9th, 23rd) -* Format: "Month Day, YYYY" +* `Month D, YYYY`, per the [style guide](/docs/contributing/style-guide/#release-notes): full month name, no ordinal, no leading zero. **Image:** * Always use the standard Sumo Logic preview image @@ -156,7 +154,7 @@ hide_table_of_contents: true ### Step 6: Content formatting guidelines -Open with a direct statement of what changed. Do not use announcement or excitement phrases ("We're excited to announce", "We've released", "We've made improvements to"). State the change factually: "[Feature] is now available." or "[Feature] now supports [X]." +Follow [Release notes](/docs/contributing/style-guide/#release-notes) in the style guide for voice, conciseness, and "Learn more" links. The guidance below is only what is specific to developer release notes. #### API Changes @@ -354,19 +352,13 @@ Claude: ## Date formatting rules -**Format: "Month Day, YYYY"** - -Month names (full): -* January, February, March, April, May, June -* July, August, September, October, November, December - -Day: No ordinal suffix (use 1, 2, 3... not 1st, 2nd, 3rd) +Titles use the [style guide](/docs/contributing/style-guide/#release-notes) date format: `Month D, YYYY`, full month name, no ordinal, no leading zero. **Examples:** * ✅ March 23, 2026 * ✅ January 1, 2026 * ✅ December 31, 2025 -* ❌ March 23rd, 2026 (no ordinal) +* ❌ March 23rd, 2026 (ordinal) * ❌ Mar 23, 2026 (abbreviated month) * ❌ 2026-03-23 (wrong format) @@ -503,4 +495,4 @@ Would you like me to help refine the content or add additional details? * [Developer Release Notes](https://sumologic.com/help/release-notes-developer) * [Release Notes Index](/docs/release-notes) * [API Documentation](/docs/api) -* [Style Guide](/docs/contributing/style-guide) +* [Style Guide: Release notes](/docs/contributing/style-guide/#release-notes) diff --git a/.claude/commands/release-note-service.md b/.claude/commands/release-note-service.md index a40cdec91a4..6ec79d1c2d6 100644 --- a/.claude/commands/release-note-service.md +++ b/.claude/commands/release-note-service.md @@ -196,15 +196,9 @@ This enhancement streamlines your workflow by providing quick access to frequent ### Step 6: Content formatting guidelines -**Write for clarity:** -* Open with a direct statement of what the feature is — never an announcement phrase ("We're excited to introduce", "We're happy to announce") - * ❌ "We're excited to announce that multi-child-org search results now include an `_orgName` field..." - * ✅ "Multi-child-org search results now include an `_orgName` field alongside `_orgId`, so MSSP users can identify which child org a result came from." - * ❌ "We are excited to announce the addition of a native Sumo Logic HTTP Source webhook integration for LiteLLM." - * ✅ "A native Sumo Logic HTTP Source webhook integration for LiteLLM is now available, enabling you to collect LiteLLM usage and proxy log data." -* Explain the benefit or business value in 2-3 sentences -* Use "What's new:" section for bulleted specifics (optional) -* End with a "Learn more" link to relevant docs +**Voice and wording:** follow [Release notes](/docs/contributing/style-guide/#release-notes) in the style guide (direct-statement openers, no announcement framing, conciseness, "Learn more" links). Service-specific structure is below. + +* Use a "What's new:" section for bulleted specifics (optional). **Use formatting for readability:** * Use **bold** for section labels like "What's new:" @@ -447,13 +441,8 @@ Would you like me to help refine the content or add additional details? ## Tips and best practices **For all Service releases:** -* Open with a direct statement of what changed: "[Feature] is now available." or "[Feature] now supports [X]." -* Do not open with announcement phrases: "We're excited to introduce", "We're happy to announce", and similar -* Lead with user benefit, not technical implementation -* Explain "what" and "why", not "how" -* Keep descriptions concise (2-3 sentences) -* Link to comprehensive documentation for details -* Use "What's new" bullets for multiple specific changes +* Voice, openers, conciseness, and "Learn more" links follow [Release notes](/docs/contributing/style-guide/#release-notes) in the style guide. +* Use "What's new" bullets for multiple specific changes. **Title guidelines:** * Be specific about the feature (not "New Collection Feature") @@ -477,4 +466,4 @@ Would you like me to help refine the content or add additional details? * [Service Release Notes](https://sumologic.com/help/release-notes-service) * [Release Notes Index](/docs/release-notes) -* [Style Guide](/docs/contributing/style-guide) +* [Style Guide: Release notes](/docs/contributing/style-guide/#release-notes) diff --git a/.claude/skills/sumo-style/SKILL.md b/.claude/skills/sumo-style/SKILL.md index 7e4d31ee28f..e8e58510aca 100644 --- a/.claude/skills/sumo-style/SKILL.md +++ b/.claude/skills/sumo-style/SKILL.md @@ -219,4 +219,4 @@ These are Sumo Logic- and repo-specific facts that override general assumptions. - **Numbered list items always use `1.`** (not `1.`, `2.`, `3.`). Docusaurus handles rendering. - **Capitalized product terms.** Collector, Source, Hosted Collector, Library. User-created objects (dashboards, folders) are lowercase. - **C2C sources and apps have distinct openers.** Do not use the app opener for a source doc or vice versa. -- **No marketing openers in release notes.** Do not open with "We're excited to introduce/announce", "We're happy to announce", "We're thrilled to share", or similar phrases. Use a direct statement instead: "[Feature] is now available." or "[Feature] now supports [X]." Example — ❌ "We're excited to announce that multi-child-org search results now include an `_orgName` field..." → ✅ "Multi-child-org search results now include an `_orgName` field..." +- **Release notes have their own rules.** Voice, openers (no announcement framing), title date format, and per-folder conventions live in [Release notes](/docs/contributing/style-guide/#release-notes) in the style guide. Apply that section when writing or editing anything in `blog-service`, `blog-collector`, `blog-cse`, `blog-csoar`, or `blog-developer`.