From 8f506deb9a35161304f4e96514be6d19dd72808a Mon Sep 17 00:00:00 2001 From: Kim Pohas Date: Wed, 20 May 2026 00:39:21 -0700 Subject: [PATCH 01/22] DOCS-1640: Trim dead weight from Claude commands and consolidate release notes - Consolidate 5 release-note-* commands into a single release-note.md - Remove "What this command does", "When to use", "Post-completion message", "Tips", "After the X", "Example usage", and generic error-handling sections from audit-doc, doc, doc-from-jira, geo-optimize, remove-doc, rewrite-intro, seo-audit, simplify, and tone-check commands - Update CLAUDE.md slash command table to reference /release-note Co-Authored-By: Claude Sonnet 4.6 --- .claude/commands/audit-doc.md | 120 ---- .claude/commands/doc-from-jira.md | 18 - .claude/commands/doc.md | 173 +----- .claude/commands/geo-optimize.md | 18 - .claude/commands/release-note-collector.md | 404 -------------- .claude/commands/release-note-cse.md | 419 -------------- .claude/commands/release-note-csoar.md | 605 --------------------- .claude/commands/release-note-developer.md | 504 ----------------- .claude/commands/release-note-service.md | 474 ---------------- .claude/commands/release-note.md | 369 +++++++++++++ .claude/commands/remove-doc.md | 63 --- .claude/commands/rewrite-intro.md | 36 -- .claude/commands/seo-audit.md | 20 - .claude/commands/simplify.md | 37 -- .claude/commands/tone-check.md | 37 -- CLAUDE.md | 6 +- 16 files changed, 371 insertions(+), 2932 deletions(-) delete mode 100644 .claude/commands/release-note-collector.md delete mode 100644 .claude/commands/release-note-cse.md delete mode 100644 .claude/commands/release-note-csoar.md delete mode 100644 .claude/commands/release-note-developer.md delete mode 100644 .claude/commands/release-note-service.md create mode 100644 .claude/commands/release-note.md diff --git a/.claude/commands/audit-doc.md b/.claude/commands/audit-doc.md index cdaf1d4051..94848f5cba 100644 --- a/.claude/commands/audit-doc.md +++ b/.claude/commands/audit-doc.md @@ -2,27 +2,6 @@ Performs comprehensive quality checks on documentation files to ensure adherence to Sumo Logic style guidelines, proper structure, and completeness. -## What this command does - -When you invoke `/audit-doc`, Claude will: - -1. **Read and analyze the specified doc file** -2. **Check frontmatter**. Validate required fields and format -3. **Review content structure**. Check headings, sections, and organization -4. **Validate links and images**. Check paths, alt text, and references -5. **Check style adherence**. Apply Sumo Logic style guide rules -6. **Report findings**. Provide detailed feedback with specific line numbers -7. **Suggest fixes**. Offer actionable recommendations - -## When to use this command - -* Before submitting a PR to check doc quality -* After creating a new doc to validate structure -* When updating existing docs to ensure consistency -* To identify broken links or missing images -* To verify adherence to Sumo Logic style guidelines -* When reviewing community contributions - ## Workflow ### Step 1: Identify the doc to audit @@ -301,53 +280,6 @@ After presenting the audit report, ask the user if they would like Claude to: * Unclear instructions * Not linked from parent page -## Example usage - -### Basic audit - -``` -User: "/audit-doc docs/integrations/databases/postgresql.md" - -Claude: -1. Reads the file -2. Checks frontmatter (id, title, description, tags) -3. Validates structure (headings, sections) -4. Checks links and images -5. Applies style guide rules -6. Generates report with: - - 2 critical issues (missing image, broken link) - - 3 warnings (description too long, inconsistent formatting) - - 5 suggestions (add example, improve heading) -7. Asks if user wants fixes applied -``` - -### Audit with doc type - -``` -User: "/audit-doc docs/send-data/hosted-collectors/cloud-to-cloud-integration-framework/okta-source.md --type c2c-source" - -Claude: -1. Reads the file -2. Applies C2C source-specific checks -3. Validates vendor configuration section -4. Checks authentication setup steps -5. Verifies required sections present -6. Reports findings specific to C2C sources -``` - -### Audit directory - -``` -User: "/audit-doc docs/integrations/security-threat-detection/" - -Claude: -1. Finds all .md files in directory -2. Runs audit on each file -3. Generates summary report for all files -4. Highlights files needing attention -5. Provides batch fix option -``` - ## Audit checklist summary Use this checklist template for the report: @@ -420,58 +352,6 @@ Track common issues across multiple audits to identify systemic problems. * Validate CID URL mapping * Confirm cross-references -## Tips and best practices - -**For effective audits:** -* Run audit before requesting PR review -* Fix critical issues first, then warnings -* Use audit reports in PR descriptions -* Re-run audit after making fixes -* Consider doc type context (release notes vs feature docs) - -**Common quick fixes:** -* Add missing frontmatter fields -* Update relative link paths -* Add language tags to code blocks -* Fix heading capitalization -* Remove trailing whitespace - -**When to skip warnings:** -* Legacy docs with established style -* Marketing pages with intentional tone -* Third-party content that shouldn't be modified -* Temporary draft content (with noindex tag) - -## Error handling - -**If file not found:** -* Show error message -* Suggest using Tab completion for path -* Check if file was recently moved or renamed - -**If file is not markdown:** -* Show error: "Audit only works with .md files" -* Suggest appropriate file type - -**If doc type cannot be determined:** -* Ask user to specify doc type -* Provide list of supported types -* Offer generic audit without type-specific checks - -**If many issues found (>20):** -* Suggest focusing on critical issues first -* Offer to generate summary instead of full report -* Recommend gradual fixes in multiple PRs - -## References - -* [Sumo Logic Style Guide](/docs/contributing/style-guide) -* [Contributing Guide](/docs/contributing) -* [Doc Templates](/docs/contributing/templates) -* [Docusaurus Documentation](https://docusaurus.io/docs) - ---- - ## Related commands `/audit-doc` covers structure, style, links, frontmatter, and required sections. It does not diff --git a/.claude/commands/doc-from-jira.md b/.claude/commands/doc-from-jira.md index 3e06303350..3873aeb2bd 100644 --- a/.claude/commands/doc-from-jira.md +++ b/.claude/commands/doc-from-jira.md @@ -2,24 +2,6 @@ Pulls a Jira ticket from the DOCS project, extracts the content requirements, and scaffolds a fully structured documentation file ready for writing. Eliminates the blank-page problem and keeps the doc aligned with the ticket spec from the start. -## What this command does - -When you invoke `/doc-from-jira`, Claude will: - -1. **Fetch the Jira ticket**. Pull title, description, acceptance criteria, and linked resources -2. **Determine doc type**. Feature, how-to, concept, reference, or troubleshooting -3. **Infer the file path**. Based on the technical area and content type -4. **Scaffold the doc**. Generate a file with correct frontmatter, structure, and placeholder sections pre-populated from the ticket -5. **Update sidebars.ts**. Add the new doc to navigation (with user approval) -6. **Link back to Jira**. Set the Jira ticket to In Progress if not already - -## When to use this command - -* Starting a new doc for a DOCS ticket -* When a ticket has a detailed description or acceptance criteria worth preserving -* For tickets with linked specs, PRDs, or engineering docs to pull context from -* When you want to ensure the doc structure is aligned with what was requested - ## When NOT to use this command * **App integrations** — use `/app-doc` instead diff --git a/.claude/commands/doc.md b/.claude/commands/doc.md index 13fbc78697..aa72e99dc2 100644 --- a/.claude/commands/doc.md +++ b/.claude/commands/doc.md @@ -2,31 +2,11 @@ Automates the creation of general Sumo Logic documentation for features, how-tos, concepts, reference pages, and troubleshooting guides. -## What this command does - -When you invoke `doc`, Claude will guide you through: - -1. **Determine doc type**. Feature, how-to, concept, reference, or troubleshooting. -2. **Gather information**. Title, description, file path, and keywords. -3. **Create markdown file**. Generate file with proper frontmatter and basic structure. -4. **Add to navigation**. Guide on adding to sidebars.ts. -5. **Add to hub page**. Suggest adding card to parent index page. -6. **Create CID mapping**. Add permanent URL if needed for UI links. -7. **Validate and preview**. Check structure and provide next steps. - -## When to use this command - -* Creating feature documentation. -* Writing how-to guides and tutorials. -* Documenting concepts and reference material. -* Creating troubleshooting guides. -* Adding general content that does not fit specialized templates (apps, sources, release notes). - ## When NOT to use this command * **App integrations**. Use `app-doc` instead. * **Cloud-to-Cloud sources**. Use `c2c-source-doc` instead. -* **Release notes**. Use `release-note-cse` or `release-note-collector` instead. +* **Release notes**. Use `release-note` instead. ## Doc types @@ -386,40 +366,6 @@ Before finishing, verify: * [ ] No negative contractions (use "cannot", "will not", "do not"). * [ ] No trailing whitespace. -## Example usage - -### Feature Doc Example - -``` -User: "Create a doc for the new access keys feature" - -Claude: -1. Confirms type: Feature Documentation -2. Gathers info: title, path, description, keywords -3. Creates: docs/manage/security/access-keys.md -4. Generates frontmatter with proper fields -5. Scaffolds feature doc structure -6. Guides on adding to sidebars.ts under Manage category -7. Suggests adding card to docs/manage/security/index.md -8. Asks if CID mapping needed -9. Provides validation checklist -``` - -### How-to Guide Example - -``` -User: "Create a how-to guide for installing the OpenTelemetry Collector on Windows" - -Claude: -1. Confirms type: How-to Guide -2. Gathers info: title, path, description -3. Creates: docs/send-data/opentelemetry-collector/install-collector/windows.md -4. Generates frontmatter -5. Scaffolds how-to structure with prerequisites and steps -6. Guides on sidebar placement -7. Provides checklist -``` - ## Common patterns ### File path conventions @@ -472,120 +418,3 @@ keywords: - reports ``` -## Safety principles - -* **Check existing files** before creating to avoid duplicates. -* **Follow existing path conventions** in the category. -* **Use descriptive filenames** that indicate content. -* **Keep titles concise** but clear. -* **Validate frontmatter** has all required fields. -* **Use appropriate structure** for the doc type. - -## Post-completion message - -After successfully creating the doc, tell the user: - -``` -✅ Documentation file created successfully! - -File created: -* 📄 {file-path} - -Summary: -* Type: {doc-type} -* Title: {title} -* Category: {category} - -Next steps: -1. Add content to the doc sections -2. Add doc to sidebars.ts: - * Open sidebars.ts - * Find the {category} category - * Add '{doc-id}' to the items array -3. Optional: Add card to hub page at {parent-index-path} -4. Optional: Create CID mapping in cid-redirects.json -5. Preview locally: yarn start -6. Check preview at: http://localhost:3000/docs/{doc-path} -7. Submit PR: "DOCS-XXX - Add {doc-title}" - -Checklist: -* [ ] Content complete and follows structure. -* [ ] Added to sidebars.ts. -* [ ] Added to hub page (if applicable). -* [ ] CID mapping created (if needed). -* [ ] All links work. -* [ ] Style guide compliant. - -The doc will appear in the navigation menu after you add it to sidebars.ts. - -Would you like me to help add content to any specific section? -``` - -## Error handling - -**If file already exists:** -* Show existing file path and title. -* Ask if user wants to: - * Edit existing file instead. - * Use different filename. - * Overwrite (requires confirmation). - -**If title is too long:** -* Show character count. -* Suggest shorter alternative. -* Recommend using `sidebar_label` for long titles. - -**If path does not follow conventions:** -* Suggest correct path based on category. -* Explain repo conventions. - -**If no description provided:** -* Explain importance for SEO. -* Suggest generating description from title. - -## Tips and best practices - -**General:** -* Start with a clear introduction that sets expectations. -* Use second person ("you") to address readers. -* Keep paragraphs short (2-4 sentences). -* Use active voice. -* Include concrete examples. - -**Structure:** -* Use headings to organize content logically. -* Put most important information first. -* Group related information together. -* End with related topics or next steps. - -**Links:** -* Link to related docs for additional context. -* Use descriptive link text. -* Prefer relative paths for internal links. -* Test all links work. - -**Images:** -* Use images to illustrate UI steps or concepts. -* Always include descriptive alt text. -* Store images in `/static/img/` directory. -* Optimize image file sizes. - -**Code:** -* Specify language for syntax highlighting. -* Keep code examples concise and relevant. -* Include comments for complex code. -* Show realistic examples, not placeholders. - -## References - -* [Style Guide](/docs/contributing/style-guide). -* [Create or Edit a Doc](/docs/contributing/create-edit-doc). -* [Sumo Logic Word List](/docs/contributing/word-list). - ---- - -**Note:** This command is for general documentation. For specialized content types, use the appropriate command: - -* **App integrations**. Use `/app-doc` for creating app documentation with standardized templates and structure. -* **Cloud-to-Cloud sources**. Use `/c2c-source-doc` for Cloud-to-Cloud source integration documentation. -* **Release notes**. Use `/release-note-cse`, `/release-note-collector`, `/release-note-csoar`, `/release-note-developer`, or `/release-note-service` for product release notes. diff --git a/.claude/commands/geo-optimize.md b/.claude/commands/geo-optimize.md index 6710532404..0df544be63 100644 --- a/.claude/commands/geo-optimize.md +++ b/.claude/commands/geo-optimize.md @@ -2,24 +2,6 @@ Rewrites and restructures documentation to improve discoverability in AI-powered search tools (ChatGPT, Perplexity, Gemini, Claude, and similar) and to surface content as direct answers in traditional search results. Covers both **AEO** (Answer Engine Optimization — featured snippets, "People also ask") and **GEO** (Generative Engine Optimization — LLM citation and extraction). -## What this command does - -When you invoke `/geo-optimize`, Claude will: - -1. **Read the doc** -2. **Diagnose the current state**. Identify AEO and GEO gaps before making changes -3. **Propose specific improvements**. Show the user what will change and why -4. **Apply approved changes**. Rewrite only the sections the user approves -5. **Validate the result**. Confirm the doc is more answer- and citation-ready without breaking accuracy - -## When to use this command - -* New docs for features that are frequently searched in AI tools or voice search -* High-traffic docs that rarely appear in AI-generated answers or featured snippets -* Concept and reference docs where accuracy and citability matter most -* After `/seo-audit` flags AEO or GEO suggestions -* Before a product launch to maximize early visibility - ## What this command does NOT change * Technical accuracy — never alter facts, steps, code, or configuration values diff --git a/.claude/commands/release-note-collector.md b/.claude/commands/release-note-collector.md deleted file mode 100644 index faef82018f..0000000000 --- a/.claude/commands/release-note-collector.md +++ /dev/null @@ -1,404 +0,0 @@ -# Create New Collector Release Note - -Automates the creation of Collector release notes for Installed Collector versions and OpenTelemetry features. - -## What this command does - -When you invoke `release-note-collector`, Claude will guide you through: - -1. **Determine release type**. Installed Collector version or OpenTelemetry feature -2. **Gather release details**. Version number, changes, features, or fixes -3. **Create markdown file**. Generate file with proper frontmatter and structure -4. **Format content**. Apply correct formatting for version releases or features -5. **Validate and preview**. Check structure and provide next steps - -## When to use this command - -* Publishing new Installed Collector versions with bug or security fixes. -* Announcing OpenTelemetry collector features and improvements. -* Documenting collector version updates. -* Releasing new OpenTelemetry integrations or capabilities. - -## Release types - -### Installed Collector Release (`-installed.md`) - -For Installed Collector version releases: -* **Version numbers**: Format X.Y.Z-N (e.g., 19.535-6). -* **Security fixes**: CVE patches, dependency upgrades. -* **Bug fixes**: Issue resolutions and stability improvements. -* **Minor features**: Small enhancements in collector behavior. - -**Typical cadence**: As needed when versions ship - -### OpenTelemetry Release (`-otel.md`) - -For OpenTelemetry collector features: -* **New features**: Installation methods, integrations, capabilities. -* **Improvements**: Performance enhancements, reliability updates. -* **Announcements**: CDN changes, configuration updates. - -**Typical cadence**: As features are released - -## Workflow - -### Step 1: Gather information - -Ask the user for: - -**For Installed Collector releases:** -* **Version number**: Full version (e.g., 19.535-6). -* **Release date**: Date in YYYY-MM-DD format. -* **Changes**: List of security fixes, bug fixes, or features. - -**For OpenTelemetry releases:** -* **Feature name**: Name of the feature or update. -* **Release date**: Date in YYYY-MM-DD format. -* **Description**: What it does and why it matters (2-3 sentences). -* **Documentation link**: Relative path to the doc. - -**Validate:** -* Check that date is not in the future. -* For installed releases, validate version number format. -* For OTel releases, ensure documentation link exists. - -### Step 2: Create the markdown file - -**File naming convention:** -``` -blog-collector/YYYY-MM-DD-{type}.md -``` - -Examples: -* `blog-collector/2026-03-19-installed.md`. -* `blog-collector/2026-03-19-otel.md`. - -**Important**: Files are created in `/blog-collector/` directory - -### Step 3: Generate frontmatter - -**For Installed Collector releases:** -```yaml ---- -title: Installed Collector Version {X.Y.Z-N} -image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 -hide_table_of_contents: true -keywords: - - installed-collector ---- -``` - -**For OpenTelemetry releases:** -```yaml ---- -title: {Feature Name} -image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 -hide_table_of_contents: true -keywords: - - opentelemetry-collector ---- -``` - -**Title formatting:** -* Installed: "Installed Collector Version X.Y.Z-N" -* OTel: Feature name in Title Case (no category suffix) - -**Keywords:** -* Installed Collector: Always use `installed-collector` -* OpenTelemetry: Always use `opentelemetry-collector` -* These keywords are standard and do not need user confirmation - -### Step 4: Add required import - -For OpenTelemetry releases that use links or useBaseUrl: -```javascript -import useBaseUrl from '@docusaurus/useBaseUrl'; -``` - -**Note**: Only add if content uses it. For simple version releases, omit. - -### Step 5: Write content - -#### Installed Collector Release Structure - -```markdown -In this release, we've enhanced the security and stability of the Collector with added support for security patches. - -#### Security fix - -* {Security fix description with version numbers and CVE references}. -* {Additional security fixes}. - -#### Bug fix - -* {Bug fix description}. -* {Additional bug fixes}. -``` - -**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}." -* Use H4 (`####`) for section headings: Security fix, Bug fix, Feature -* 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 - -**Example:** -```markdown -In this release, we've enhanced the security and stability of the Collector with added support for security patches. - -#### Security fix - -* Upgraded `io.netty:netty-codec-http` to version **4.1.129.Final** to address known security vulnerability (CVE-2025-67735). -* Upgraded `com.fasterxml.jackson.core` packages to use patched version **2.18.6** to address known security vulnerability (GHSA-72hv-8253-57qq). - -#### Bug fix - -* Fixed an issue with forwarded Windows event collection that occurred on systems running with latest Windows version. -``` - -#### OpenTelemetry Release Structure - -```markdown -We're excited to {announce/introduce} {feature description}. {What it does and benefits}. [Learn more](/docs/path/to/doc). - -{Optional: Additional paragraphs with more details} - -{Optional: Related documentation list} - -{Optional: Important notes in admonition} -``` - -**OpenTelemetry Guidelines:** -* Start with "We're excited to announce..." or "We're excited to introduce...". -* Write 2-3 sentences in first paragraph. -* Focus on user benefits and business value. -* End first paragraph with "Learn more" link. -* 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):** -```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/). -``` - -**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. - -Refer to the following documentation to view the updated URLs in the UI. -* [Ansible](/docs/send-data/opentelemetry-collector/install-collector/ansible/). -* [Chef](/docs/send-data/opentelemetry-collector/install-collector/chef/). -* [Puppet](/docs/send-data/opentelemetry-collector/install-collector/puppet/). - -:::note -* Existing OpenTelemetry binaries and other packages remain in their current locations. -* This change does not affect the UI itself. The download process looks the same, but the underlying URL now uses a CDN to improve reliability and speed. -::: -``` - -### Step 6: Validation checklist - -Before finishing, verify: -* [ ] File created in `/blog-collector/` directory. -* [ ] Filename follows pattern: `YYYY-MM-DD-{type}.md` -* [ ] Frontmatter complete with all required fields. -* [ ] Title format correct (version number or feature name). -* [ ] `hide_table_of_contents: true` present -* [ ] Keywords correct for type (installed-collector or opentelemetry). -* [ ] 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: "Learn more" link included with relative path -* [ ] No trailing whitespace. - -## Example usage - -### Installed Collector Example - -``` -User: "Create a Collector release note for version 19.535-8 with a security fix for Netty and a bug fix for Windows events" - -Claude: -1. Confirms type: Installed Collector -2. Confirms date: 2026-03-19 -3. Creates: blog-collector/2026-03-19-installed.md -4. Generates frontmatter: "Installed Collector Version 19.535-8" -5. Adds standard intro paragraph -6. Creates Security fix section with Netty upgrade -7. Creates Bug fix section with Windows events fix -8. Provides checklist -``` - -### OpenTelemetry Example - -``` -User: "Create an OTel Collector release note about new Kubernetes monitoring support" - -Claude: -1. Confirms type: OpenTelemetry -2. Confirms date: 2026-03-19 -3. Asks for description and doc link -4. Creates: blog-collector/2026-03-19-otel.md -5. Generates frontmatter: "Kubernetes Monitoring Support" -6. Writes announcement with feature benefits -7. Adds "Learn more" link -8. Provides checklist -``` - -## Version number format - -Installed Collector versions follow this pattern: -``` -Major.Minor.Patch-Build -``` - -Examples: -* `19.535-6` — Version 19.535, build 6. -* `19.535-4` — Version 19.535, build 4. -* `20.0-1` — Version 20.0, build 1. - -**Formatting in title:** -* Always include full version with build number. -* No spaces around hyphen. -* Example: "Installed Collector Version 19.535-6" - -## Dependency upgrade format - -When listing upgraded dependencies: -* Use backticks for package names. -* Use **bold** for version numbers. -* Include full CVE or GHSA reference if applicable. - -**Examples:** -* ✅ `io.netty:netty-codec-http` to version **4.1.129.Final** to address known security vulnerability (CVE-2025-67735) -* ✅ `com.fasterxml.jackson.core` packages to use patched version **2.18.6** (GHSA-72hv-8253-57qq). -* ✅ Collector JRE to **Amazon Corretto Version 17.0.18.8.1**. -* ❌ Upgraded netty-codec-http to 4.1.129.Final (missing backticks and bold). - -## Safety principles - -* **Check existing files** before creating to avoid duplicates. -* **Validate version numbers** follow the correct format. -* **Verify CVE/GHSA references** are accurate. -* **Use consistent formatting** for dependencies and versions. -* **Keep installed releases brief**. Just the facts. -* **Focus OTel releases on benefits** not technical details. - -## Post-completion message - -After successfully creating the release note, tell the user: - -**For Installed Collector:** -``` -✅ Installed Collector release note created successfully! - -File created: -* 📄 blog-collector/{date}-installed.md. - -Summary: -* Version: {version} -* Security fixes: {count} -* Bug fixes: {count} - -Next steps: -1. Review CVE/GHSA references for accuracy -2. Verify version numbers are correct -3. Ensure all fixes are documented -4. Test locally: yarn start -5. Check preview at: http://localhost:3000/release-notes-collector -6. Submit PR: "DOCS-XXX - Installed Collector {version} release notes" - -Checklist: -* [ ] Version number is correct. -* [ ] All security vulnerabilities referenced. -* [ ] Dependencies use backticks and bold versions. -* [ ] Bug fixes are complete. - -The release note will appear on the Collector release notes page in reverse chronological order (newest first). -``` - -**For OpenTelemetry:** -``` -✅ OpenTelemetry Collector release note created successfully! - -File created: -* 📄 blog-collector/{date}-otel.md. - -Summary: -* Feature: {Feature Name} -* Keywords: opentelemetry - -Next steps: -1. Review content for accuracy and clarity -2. Verify documentation link is correct -3. Ensure feature name and description are clear -4. Test locally: yarn start -5. Check preview at: http://localhost:3000/release-notes-collector -6. Submit PR: "DOCS-XXX - OTel Collector: {Feature Name}" - -Checklist: -* [ ] Feature name is clear and concise. -* [ ] Description focuses on user benefits. -* [ ] Documentation link is correct. -* [ ] No placeholder text remaining. - -The release note will appear on the Collector release notes page in reverse chronological order (newest first). - -Would you like me to help refine the description or add additional details? -``` - -## Error handling - -**If file already exists:** -* Show existing file content. -* Ask if user wants to: - * Use different type (installed vs otel). - * Use different date. - * Overwrite (requires confirmation). - -**If version number format is invalid:** -* Show expected format: X.Y.Z-N -* Ask for correction. - -**If CVE/GHSA reference looks incomplete:** -* Warn about format. -* Ask for confirmation. - -**If documentation link looks wrong (OTel):** -* Warn if does not start with `/docs/`. -* Suggest correction. - -## Tips and best practices - -**Installed Collector releases:** -* Be specific about what was fixed or upgraded. -* Include exact version numbers. -* Reference CVEs and GHSAs when applicable. -* Keep descriptions factual and brief. -* Order matters: Security → Bugs → Features - -**OpenTelemetry releases:** -* Lead with user benefit. -* Explain why the change matters. -* Link to comprehensive documentation. -* Use admonitions for breaking changes or important notes. - -**Both types:** -* Use consistent formatting throughout. -* Keep language simple and direct. -* Avoid unnecessary technical jargon. -* Focus on what changed, not how it was implemented. - -## References - -* [Collector Release Notes](https://sumologic.com/help/release-notes-collector) -* [Release Notes Index](/docs/release-notes). -* [Style Guide](/docs/contributing/style-guide). diff --git a/.claude/commands/release-note-cse.md b/.claude/commands/release-note-cse.md deleted file mode 100644 index 41e36c6c66..0000000000 --- a/.claude/commands/release-note-cse.md +++ /dev/null @@ -1,419 +0,0 @@ -# Create New Cloud SIEM Release Note - -Automates the creation of Cloud SIEM (CSE) release notes with proper formatting, frontmatter, and structure. - -## What this command does - -When you invoke `release-note-cse`, Claude will guide you through: - -1. **Determine release type**. Content release or Application release -2. **Gather release details**. Date, changes, features, bug fixes -3. **Create markdown file**. Generate file with proper frontmatter and structure -4. **Format content**. Apply correct formatting for rules, mappers, parsers, or features -5. **Validate and preview**. Check structure and provide next steps - -## When to use this command - -* Publishing Cloud SIEM content updates (rules, log mappers, parsers). -* Announcing new Cloud SIEM features or bug fixes. -* Creating regular bi-weekly or monthly CSE release notes. -* Documenting Cloud SIEM application updates. - -## Release types - -### Content Release (`-content.md`) - -For updates to Cloud SIEM detection content: -* **Rules**: New or updated detection rules -* **Log Mappers**: New or updated log mapping configurations -* **Parsers**: Parser updates and enhancements -* **Schema changes**: New fields or tags - -**Typical cadence**: Every 1-2 weeks - -### Application Release (`-application.md`) - -For Cloud SIEM product features and updates: -* **New features**: UI improvements, new capabilities -* **Bug fixes**: Issue resolutions -* **Performance improvements**: Optimizations -* **Breaking changes or deprecations**. - -**Typical cadence**: As needed when features ship - -## Workflow - -### Step 1: Gather information - -Ask the user for: - -**Required:** -* **Release type**: Content or Application -* **Release date**: Date in YYYY-MM-DD format -* **Changes**: List of what's included - -**For Content Releases:** -* New/updated rules (rule IDs and names). -* New/updated log mappers. -* New/updated parsers. -* Brief summary of changes. - -**For Application Releases:** -* Feature name and description. -* Documentation links. -* Screenshots (if applicable). -* Any breaking changes. - -**Keywords (for both types):** -* Ask user to confirm or customize keywords -* Suggest defaults based on release type (see frontmatter section below) - -**Validate:** -* Check that date is not in the future (use today's date if not specified). -* Ensure file does not already exist for this date and type. -* Confirm changes are ready to publish. -* Confirm keywords with user before creating file. - -### Step 2: Create the markdown file - -**File naming convention:** -``` -blog-cse/YYYY-MM-DD-{type}.md -``` - -Examples: -* `blog-cse/2026-03-19-content.md`. -* `blog-cse/2026-03-19-application.md`. - -**Important**: Files are created in `/blog-cse/` directory, NOT in `/docs/` - -### Step 3: Generate frontmatter - -**For Content Releases:** -```yaml ---- -title: {Month} {Day}th, {Year} - Content Release -hide_table_of_contents: true -keywords: - * rules - * log mappers - * parsers -image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 ---- -``` - -**For Application Releases:** -```yaml ---- -title: {Month} {Day}, {Year} - Application Update -image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 -keywords: - * {relevant-keyword} -hide_table_of_contents: true ---- -``` - -**Keywords guidance:** -* **Always ask user to confirm keywords before creating file** -* Suggested defaults: - * Content releases: `rules`, `log mappers`, `parsers` - * 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. - -### Step 4: Add required import - -Always include after frontmatter: -```javascript -import useBaseUrl from '@docusaurus/useBaseUrl'; -``` - -### Step 5: Write content - -#### Content Release Structure - -```markdown -This content release includes: - - {High-level summary point 1} - - {High-level summary point 2} - - {High-level summary point 3} - -Additional changes are enumerated below. - -### Rules -* [New] MATCH-SXXXX Rule Name. -* [Updated] FIRST-SXXXX Rule Name. Brief description of what changed. - -### Log Mappers -* [New] Vendor - Event Type. -* [Updated] Vendor - Event Type. - -### Parsers -* [Updated] /Parsers/System/Vendor/Parser Name. -``` - -**Content Release Guidelines:** -* Start with bulleted summary (3-5 high-level points). -* Use indentation (4 spaces) for bullet points. -* Group changes by type: Rules, Log Mappers, Parsers -* Use `[New]` or `[Updated]` tags. -* Rule IDs use format: `MATCH-SXXXX`, `FIRST-SXXXX`, `THRESHOLD-SXXXX` -* Parser paths use full hierarchy: `/Parsers/System/Vendor/Name` -* Add brief explanations for significant updates. -* Sort items alphabetically within each section. - -#### Application Release Structure - -```markdown -### {Feature Name} - -{Feature description and business value}. [Learn more](/docs/path/to/docs). - -{Optional screenshot or additional details} -``` - -**Application Release Guidelines:** -* Use H3 (`###`) for each feature. -* Start with clear, concise description. -* 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. - -### 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" - -Examples: -* ✅ "March 19th, 2026 - Content Release". -* ✅ "February 3rd, 2026 - Application Update". -* ❌ "Mar 19, 2026 - Content Release" (month abbreviated). -* ❌ "March 19 2026 - Content Release" (missing "th"). - -### Step 7: Validation checklist - -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. -* [ ] `hide_table_of_contents: true` present -* [ ] Keywords appropriate for release type. -* [ ] `import useBaseUrl` statement included. -* [ ] Content follows proper structure (Rules → Log Mappers → Parsers). -* [ ] All `[New]` and `[Updated]` tags present. -* [ ] Parser paths use full `/Parsers/System/Vendor/Name` format. -* [ ] Links use relative paths or `useBaseUrl`. -* [ ] No trailing whitespace or extra blank lines. - -## Example usage - -### Content Release Example - -``` -User: "Create a CSE content release for today with updates to AWS CloudTrail rules and new Okta log mappers" - -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" -5. Adds summary section -6. Creates sections for Rules and Log Mappers -7. Formats with proper [New]/[Updated] tags -8. Provides checklist and next steps -``` - -### Application Release Example - -``` -User: "Create a CSE application release for March 15th about the new bulk insight update feature" - -Claude: -1. Confirms date: 2026-03-15 -2. Confirms type: Application Release -3. Creates: blog-cse/2026-03-15-application.md -4. Generates frontmatter: "March 15, 2026 - Application Update" -5. Adds feature section with H3 heading -6. Includes description and Learn more link -7. Provides checklist -``` - -## Common patterns - -### Rule ID formats - -* `MATCH-SXXXX` — Match rules (most common). -* `FIRST-SXXXX` — First Seen rules. -* `THRESHOLD-SXXXX` — Threshold rules. -* `AGGREGATION-SXXXX` — Aggregation rules. -* `CHAIN-SXXXX` — Chain rules. -* `OUTLIER-SXXXX` — Outlier rules. - -### Parser path structure - -Always use full path: -``` -/Parsers/System/{Vendor}/{Parser Name} -``` - -Examples: -* `/Parsers/System/AWS/AWS CloudTrail`. -* `/Parsers/System/Okta/Okta`. -* `/Parsers/System/Microsoft/Microsoft 365`. -* `/Parsers/System/Cisco/Cisco ASA`. - -### Log Mapper naming - -Format: `{Vendor} - {Event Type}` - -Examples: -* `Okta - Authentication Events`. -* `AWS CloudTrail - Management Events`. -* `Microsoft 365 - Audit Logs`. -* `CrowdStrike Falcon - Detection Events`. - -### Vendor consistency - -Use standard vendor names: -* ✅ "Microsoft 365" (not "Office 365", "O365"). -* ✅ "Google Workspace" (not "G Suite", "GSuite"). -* ✅ "SonicWall Firewall" (not "Dell SonicWall"). -* ✅ "AWS CloudTrail" (not "Amazon CloudTrail"). - -## Archive process - -**When to archive:** -* At year-end, older releases move to archive files. -* Archive files are in `/blog-cse/{YEAR}/12-31.md`. -* Current year + 1-2 prior years remain active. -* Older years are archived. - -**Archive structure:** -```markdown ---- -title: {Year} Release Notes Archive - Cloud SIEM -keywords: [rules, signals, schema, log mappers, parsers, cloud siem] -image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 ---- - -import useBaseUrl from '@docusaurus/useBaseUrl'; - -This is an archive of {Year} Cloud SIEM release notes. [View the full archive](/release-notes-cse/archive). - - - ---- - -### {Month} {Day}, {Year} - {Type} - -{Content} - ---- -``` - -**Note:** Users typically do not need to manage archives manually. Mention this only if they ask about archiving old releases. - -## Safety principles - -* **Check existing files** before creating to avoid duplicates. -* **Validate dates** are not in the future. -* **Use consistent vendor names** (check existing releases for precedent). -* **Preserve exact rule IDs** when user provides them. -* **Do not invent rule IDs**. Ask user if not provided. -* **Link to docs** when mentioning features. - -## Post-completion message - -After successfully creating the release note, tell the user: - -``` -✅ Cloud SIEM release note created successfully! - -File created: -* 📄 blog-cse/{date}-{type}.md. - -Summary: -* Type: {Content Release | Application Update} -* Date: {formatted date} -* Changes: {count} rules, {count} log mappers, {count} parsers - -Next steps: -1. Review content for accuracy -2. Add any missing details or descriptions -3. Verify all rule IDs and parser paths are correct -4. Add screenshots for application updates (if applicable) -5. Test locally: yarn start -6. Check preview at: http://localhost:3000/release-notes-cse -7. Submit PR: "DOCS-XXX - CSE {type} release notes for {date}" - -Checklist: -* [ ] All rule IDs verified. -* [ ] Parser paths use full /Parsers/System/ format. -* [ ] Vendor names consistent with existing releases. -* [ ] Links tested and working. -* [ ] No placeholder text remaining. - -The release note will appear on the Cloud SIEM release notes page in reverse chronological order (newest first). - -Would you like me to help fill in any additional details? -``` - -## Error handling - -**If file already exists:** -* Show existing file path and date. -* Ask if user wants to: - * Add to existing release (append content). - * Create with different date. - * Overwrite (requires confirmation). - -**If date is invalid:** -* Show error and ask for correct format (YYYY-MM-DD). -* Suggest today's date as default. - -**If rule IDs do not match pattern:** -* Warn user about non-standard format. -* Ask for confirmation before proceeding. - -**If vendor names are inconsistent:** -* Check recent releases for the vendor. -* Suggest standard name. -* Ask user to confirm. - -## Tips and best practices - -**Content releases:** -* Lead with most significant changes in summary. -* Group related changes together (e.g., all Okta updates). -* Include context for major updates ("Updated detection expression for improved query performance"). -* Keep descriptions concise (one sentence per update). - -**Application releases:** -* Lead with user benefit, not technical details. -* Always link to documentation. -* Use screenshots for UI changes. -* Mention if feature requires admin privileges. - -**General:** -* Be consistent with formatting across releases. -* Use active voice ("Added support for.." not "Support was added.."). -* Spell out acronyms on first use in each release. -* Keep release notes focused on what changed, not why. - -## References - -* [Cloud SIEM Release Notes](https://sumologic.com/help/release-notes-cse) -* [Release Notes Index](/docs/release-notes). -* [Style Guide](/docs/contributing/style-guide). diff --git a/.claude/commands/release-note-csoar.md b/.claude/commands/release-note-csoar.md deleted file mode 100644 index ebe2508bbd..0000000000 --- a/.claude/commands/release-note-csoar.md +++ /dev/null @@ -1,605 +0,0 @@ -# Create New Cloud SOAR Release Note - -Automates the creation of Cloud SOAR (Automation Service) release notes for platform updates, integration changes, and bug fixes. - -## What this command does - -When you invoke `release-note-csoar`, Claude will guide you through: - -1. **Determine release type**. Content Release or Application Update -2. **Gather release details**. Date, changes, integrations, playbooks, or platform updates -3. **Create markdown file**. Generate file with proper frontmatter and structure -4. **Format content**. Apply correct formatting for the release type -5. **Validate and preview**. Check structure and provide next steps - -## When to use this command - -* Publishing new integrations and playbooks (Content Release) -* Publishing Cloud SOAR platform updates (Application Update) -* Documenting integration updates or bug fixes -* Announcing new API endpoints or features -* Releasing playbook improvements - -## Release types - -### Content Release (`-content-release.md`) - -For releases focused on new content (integrations and playbooks): -* **New integrations**: Brand new integrations added to App Central -* **Updated integrations**: Improvements to existing integrations -* **New playbooks**: New playbooks with ID numbers and titles -* **Simple format**: Just lists of what's new/updated, minimal descriptions - -**Typical cadence**: Monthly or as content batches are released - -### Application Update (`-application-update.md`) - -For platform features, enhancements, and bug fixes: -* **Platform features**: New capabilities, UX improvements, APIs -* **Integration changes**: With detailed descriptions of what changed -* **Bug fixes**: Issues resolved in integrations, platform, or playbooks -* **Detailed format**: Sections with descriptions and context - -**Typical cadence**: Monthly, published early the following month - -## Release structure (varies by type) - -### Content Release Structure - -Simple format with just lists: - -1. **Intro paragraph** - Brief description of release -2. **Integrations** (H3) - Bulleted list of [New]/[Updated] integrations -3. **Playbooks** (H3) - Bulleted list of [New] playbooks with IDs and titles - -### Application Update Structure - -Detailed format with descriptions and bug fixes: - -1. **Release month header** (H2) - "## {Month} release" -2. **Changes and enhancements** (H3) - - **Integrations** (H4) - New or updated integrations with descriptions - - **Platform** (H4) - Platform features and improvements - - **Playbooks** (H4) - Playbook-related changes (optional) -3. **Bug Fixes** (H3) - - **Integrations** (H4) - Integration bug fixes - - **Platform** (H4) - Platform bug fixes - - **Playbooks** (H4) - Playbook bug fixes - -## Workflow - -### Step 1: Determine release type - -Ask the user which type of release: - -**Content Release** - For new integrations and playbooks -* Simple list format -* No detailed descriptions -* No bug fixes section -* Use when: Releasing batch of new content - -**Application Update** - For platform features and bug fixes -* Detailed descriptions -* Bug fixes section -* Organized by month -* Use when: Monthly platform updates - -### Step 2: Gather information - -**For Content Release:** -* **Publication date**: Date in YYYY-MM-DD format -* **New integrations**: List of integrations to add -* **Updated integrations**: List of integrations to update -* **New playbooks**: List with ID numbers and titles (if any) - -**For Application Update:** -* **Release month**: Which month is this release for? (e.g., "February") -* **Publication date**: Date in YYYY-MM-DD format (typically early next month) -* **Integration changes**: New or updated integrations with descriptions -* **Platform changes**: Platform features and improvements -* **Bug fixes**: List of bugs fixed - -**Keywords (for both types):** -* Ask user to confirm or customize keywords -* Suggested defaults (see frontmatter section below) - -**Validate:** -* Check that date is not in the future -* For Application Update: Ensure release month aligns with publication date -* Verify integration links are valid -* Confirm keywords with user before creating file - -### Step 3: Create the markdown file - -**File naming convention:** - -For Content Release: -``` -blog-csoar/YYYY-MM-DD-content-release.md -``` - -For Application Update: -``` -blog-csoar/YYYY-MM-DD-application-update.md -``` - -Examples: -* `blog-csoar/2024-06-05-content-release.md` -* `blog-csoar/2026-03-06-application-update.md` - -**Important**: Files are created in `/blog-csoar/` directory (root level) - -### Step 4: Generate frontmatter - -**For Content Release:** -```yaml ---- -title: {Month DD, 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: - - automation service - - cloud soar - - soar ---- -``` - -**For Application Update:** -```yaml ---- -title: {Month DD, 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: - - automation service - - cloud soar ---- -``` - -**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) - -**Keywords:** -* **Always ask user to confirm keywords before creating file** -* Suggested defaults: - * Content Release: `automation service`, `cloud soar`, `soar` (three keywords) - * Application Update: `automation service`, `cloud soar` (two keywords) -* User may want to add additional keywords based on specific content (e.g., `integrations`, `playbooks`, `api`, `platform`) - -**Image:** -* Both types use the same standard Sumo Logic preview image: - * `https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082` - -### Step 5: Add required import - -**For both types**, add the useBaseUrl import after frontmatter: -```javascript -import useBaseUrl from '@docusaurus/useBaseUrl'; -``` - -### Step 6: Write content structure - -**Content Release template:** -```markdown ---- -title: June 05, 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: - - automation service - - cloud soar - - soar ---- - -import useBaseUrl from '@docusaurus/useBaseUrl'; - -This release introduces new integrations, new playbooks, and several updates. - -### Integrations - -* [New] [AWS WAF](/docs/platform-services/automation-service/app-central/integrations/aws-waf) -* [Updated] [Okta](/docs/platform-services/automation-service/app-central/integrations/okta) - -### Playbooks - -* [New] 541 - Management of AWS EKS Insights -* [New] 542 - Resolution of AWS EKS Insights -``` - -**Application Update template:** -```markdown ---- -title: March 06, 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: - - automation service - - cloud soar ---- - -import useBaseUrl from '@docusaurus/useBaseUrl'; - -## {Month} release - -Following are the updates made in {Month} {YYYY}. - -### Changes and enhancements - -#### Integrations - -* [Added] [Integration Name](/docs/path/to/integration/) - Description of what was added. -* [Updated] [Integration Name](/docs/path/to/integration/) - Description of what was updated. - -#### Platform - -* Description of platform enhancement or feature. -* Description of another platform change. - -### Bug Fixes - -#### Integrations - -* In the [Integration Name](/docs/path/to/integration/) integration, description of bug fix. - -#### Platform - -Fixed an issue where [description of bug and fix]. -``` - -### Step 7: Content formatting guidelines - -## Content Release Formatting - -#### Intro Paragraph - -* Simple one-sentence description -* Format: "This release introduces {what's new}." -* Examples: - * "This release introduces new integrations, new playbooks, and several updates." - * "This release introduces new integrations and updates to existing integrations." - -#### Integrations Section (H3) - -* Simple bulleted list with [New] or [Updated] tags -* Format: `* [Tag] [Integration Name](link)` -* NO descriptions needed - just link to integration doc -* Links use full path: `/docs/platform-services/automation-service/app-central/integrations/{slug}` - -**Example:** -```markdown -### Integrations - -* [New] [AWS WAF](/docs/platform-services/automation-service/app-central/integrations/aws-waf) -* [New] [Cyberint](/docs/platform-services/automation-service/app-central/integrations/cyberint) -* [Updated] [Okta](/docs/platform-services/automation-service/app-central/integrations/okta) -* [Updated] [ServiceNow V2](/docs/platform-services/automation-service/app-central/integrations/servicenow-v2) -``` - -#### Playbooks Section (H3) - -* Optional - only if new playbooks released -* Format: `* [New] {ID} - {Playbook Title}` -* ID is a number (e.g., 541, 542, 543) -* Use "- " between ID and title - -**Example:** -```markdown -### Playbooks - -* [New] 541 - Management of AWS EKS Insights -* [New] 542 - Resolution of AWS EKS Insights -* [New] 543 - Alert and Vulnerability detection with Sysdig Secure -``` - -## Application Update Formatting - -#### Release Month Header (H2) - -* Always use H2 (`##`) for the month -* Format: "## {Month} release" -* Examples: "## February release", "## March release" -* Followed by: "Following are the updates made in {Month} {YYYY}." - -#### Changes and Enhancements Section - -**Integrations subsection:** -* Use tags: `[Added]` for new integrations, `[Updated]` for existing ones -* Format: `[Tag] [Integration Name](link) - Description.` -* Link to integration documentation in `/docs/platform-services/automation-service/app-central/integrations/` -* Be specific about what action or feature was added/updated -* Can mention specific actions: "Added 'Count Occurrence Of Value' action" - -**Example:** -```markdown -#### Integrations - -* [Added] [Sumo Logic Automation Tools](/docs/platform-services/automation-service/app-central/integrations/sumo-logic-automation-tools/) - Added "Count Occurrence Of Value" action to count the occurrence of a specified value in texts. -* [Updated] [ThreatConnect V3](/docs/platform-services/automation-service/app-central/integrations/threatconnect-v3/) - Added observations parameter to the Update Intelligence action to enable recording observation counts for indicators. -``` - -**Platform subsection:** -* List platform-wide changes or features -* Focus on user-facing improvements -* Can include UX enhancements, new APIs, or system improvements -* Use clear, simple language - -**Example:** -```markdown -#### Platform - -* Improved the sorting UX experience on all tables in Cloud SOAR and the Automation Service to align with other Sumo Logic modules. -* Deleted records will no longer be fetched during table searches unless the `Deleted` filter is applied. -* Added new public APIs: - * [Add playbooks to an incident](https://api.sumologic.com/docs/csoar/#operation/incidents_runbook_create). - * [Retrieve all playbooks attached to a specific incident](https://api.sumologic.com/docs/csoar/#operation/incidents_runbook_retrieve). -``` - -**Playbooks subsection (optional):** -* Only include if there are playbook-specific changes -* Format similar to platform changes - -#### Bug Fixes Section - -* Group by subsection: Integrations, Platform, Playbooks -* For integrations: Start with "In the [Integration Name](link) integration, ..." -* For platform/playbooks: Use "Fixed an issue where..." or direct description -* Be specific about what was fixed - -**Example:** -```markdown -### Bug Fixes - -#### Integrations - -* In the [Microsoft EWS (Graph)](/docs/platform-services/automation-service/app-central/integrations/microsoft-ews-graph/) integration, removed the default values for the `has_attachments` and `un_read` fields in the Search Emails Extended action. The change allows users to search for emails without being forced to filter by attachment status or read/unread status. - -#### Platform - -Fixed an issue where query filters were being applied incorrectly during search. - -#### Playbooks - -Fixed issues while selecting variables containing the period character in textarea fields and test node input. -``` - -### Step 8: Validation checklist - -**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") -* [ ] Image URL: Standard Sumo Logic preview image -* [ ] Keywords: automation service, cloud soar, soar (three keywords) -* [ ] `hide_table_of_contents: true` is present -* [ ] Import statement included -* [ ] Simple intro paragraph present -* [ ] Integrations section uses [New]/[Updated] tags -* [ ] Integration links have NO descriptions (just links) -* [ ] Playbooks section uses [New] with ID numbers (if included) -* [ ] No trailing whitespace - -**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") -* [ ] Image URL: Standard Sumo Logic preview image -* [ ] Keywords: automation service, cloud soar (two keywords) -* [ ] `hide_table_of_contents: true` is present -* [ ] Import statement included -* [ ] H2 header: "## {Month} release" -* [ ] Intro: "Following are the updates made in {Month} {YYYY}." -* [ ] Integration changes use [Added]/[Updated] WITH descriptions -* [ ] Integration links point to correct paths -* [ ] All sections properly formatted (H3 for main, H4 for subsections) -* [ ] No trailing whitespace - -## Example usage - -### Content Release Example - -``` -User: "Create a Cloud SOAR content release for June 5, 2024, with new AWS integrations and playbooks" - -Claude: -1. Confirms type: Content Release -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" - - image: Standard Sumo Logic preview image - - keywords: automation service, cloud soar, soar -5. Writes content with: - - Simple intro: "This release introduces new integrations, new playbooks, and several updates." - - Integrations section with [New]/[Updated] tags (no descriptions) - - Playbooks section with ID numbers -6. Provides checklist -``` - -### Application Update Example - -``` -User: "Create a Cloud SOAR release note for February 2026, published March 6, with integration updates and bug fixes" - -Claude: -1. Confirms type: Application Update -2. Confirms publication date: March 6, 2026 -3. Confirms release month: February -4. Creates: blog-csoar/2026-03-06-application-update.md -5. Generates frontmatter: - - title: "March 06, 2026 - Application Update" - - keywords: automation service, cloud soar -6. Writes content with: - - H2: "## February release" - - Intro: "Following are the updates made in February 2026." - - Changes and enhancements section (with descriptions) - - Bug fixes section -7. Provides checklist -``` - -## Integration documentation paths - -Integration docs are located at: -``` -/docs/platform-services/automation-service/app-central/integrations/{integration-slug}/ -``` - -**Common integrations:** -* Microsoft EWS (Graph): `/docs/platform-services/automation-service/app-central/integrations/microsoft-ews-graph/` -* ThreatConnect V3: `/docs/platform-services/automation-service/app-central/integrations/threatconnect-v3/` -* Atlassian Opsgenie: `/docs/platform-services/automation-service/app-central/integrations/atlassian-opsgenie/` -* Sumo Logic Automation Tools: `/docs/platform-services/automation-service/app-central/integrations/sumo-logic-automation-tools/` - -**Tip**: Integration slugs are lowercase with hyphens. If unsure, use Grep to find the integration doc. - -## API documentation links - -Cloud SOAR API docs: -* API reference: `https://api.sumologic.com/docs/csoar/` -* Cloud SOAR automation docs: `/docs/cloud-soar/automation/` - -## 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) - -**Examples:** -* ✅ March 06, 2026 -* ✅ January 08, 2026 -* ✅ December 31, 2025 -* ✅ June 05, 2024 -* ❌ March 6, 2026 (not zero-padded) -* ❌ March 6th, 2026 (has ordinal) -* ❌ Mar 06, 2026 (abbreviated month) -* ❌ 2026-03-06 (wrong format) - -## Release timing - -**Important**: Cloud SOAR release notes are typically published early the following month for the previous month's changes. - -**Pattern:** -* February changes → Published early March (e.g., March 6) -* January changes → Published early February -* December changes → Published early January - -**In the file:** -* Filename uses publication date: `2026-03-06-application-update.md` -* Title uses publication date: "March 6, 2026 - Application Update" -* H2 uses release month: "## February release" -* Intro uses release month: "Following are the updates made in February 2026." - -## Safety principles - -* **Check for existing files** before creating to avoid duplicates -* **Validate release month alignment** with publication date -* **Verify integration links** exist before including them -* **Use consistent formatting** for all integration changes -* **Include both keywords**. Automation service and cloud soar -* **Group bug fixes by category** for clarity -* **Keep descriptions concise** but informative - -## Post-completion message - -After successfully creating the release note, tell the user: - -``` -✅ Cloud SOAR release note created successfully! - -File created: -* 📄 blog-csoar/{YYYY-MM-DD}-application-update.md - -Summary: -* 📅 Publication: {Month Day, YYYY} -* 📆 Release month: {Month} -* 🔧 Integration updates: {count} -* 🐛 Bug fixes: {count} - -Next steps: -1. Review all integration links are correct -2. Verify bug fix descriptions are accurate -3. Ensure release month matches publication date -4. Test locally: yarn start -5. Check preview at: http://localhost:3000/release-notes-csoar -6. Submit PR: "DOCS-XXX - Cloud SOAR {Month} release notes" - -Checklist: -* [ ] Filename is {date}-application-update.md -* [ ] Title follows "Month Day, YYYY - Application Update" format -* [ ] H2 header is "## {Month} release" -* [ ] Integration changes use [Added]/[Updated] tags -* [ ] All integration links are valid -* [ ] Keywords include automation service and cloud soar -* [ ] Bug fixes grouped by category - -The release note will appear on the Cloud SOAR release notes page in reverse chronological order (newest first). - -Would you like me to help refine any sections or add additional details? -``` - -## Error handling - -**If file already exists:** -* Show existing file path and date -* Ask if user wants to: - * Update existing file (add more content) - * Use different date - * Create anyway (overwrite - requires confirmation) - -**If release month doesn't match date:** -* Warn user about mismatch -* Example: "March 6 publication should be for February release, not March" -* Ask for confirmation or correction - -**If integration link looks invalid:** -* Warn if doesn't follow standard path pattern -* Suggest searching for correct integration doc -* Proceed with user confirmation - -**If date is in the future:** -* Warn user and ask for confirmation -* Suggest using current date - -## Tips and best practices - -**For integration changes:** -* Be specific about what actions were added or updated -* Include the purpose or benefit of the change -* Always link to integration documentation -* Use [Added] for completely new integrations -* Use [Updated] for changes to existing integrations - -**For platform changes:** -* Focus on user-facing improvements -* Explain the benefit or impact -* Group related changes together -* Include API links when relevant - -**For bug fixes:** -* Clearly describe what was fixed -* Explain the previous behavior and new behavior -* Group by category for organization - -**All sections:** -* Keep language clear and concise -* Focus on what changed and why it matters -* Use bullet points for easy scanning -* Maintain consistent formatting - -## References - -* [Cloud SOAR Release Notes](https://sumologic.com/help/release-notes-csoar) -* [Cloud SOAR Documentation](/docs/cloud-soar) -* [Automation Service](/docs/platform-services/automation-service) -* [App Central Integrations](/docs/platform-services/automation-service/app-central/integrations) -* [Style Guide](/docs/contributing/style-guide) diff --git a/.claude/commands/release-note-developer.md b/.claude/commands/release-note-developer.md deleted file mode 100644 index 8b11cce1d0..0000000000 --- a/.claude/commands/release-note-developer.md +++ /dev/null @@ -1,504 +0,0 @@ -# Create New Developer Release Note - -Automates the creation of Developer release notes for APIs, SDKs, integrations, and platform changes relevant to developers. - -## What this command does - -When you invoke `release-note-developer`, Claude will guide you through: - -1. **Gather release details**. Category, date, title, and content -2. **Create markdown file**. Generate file with proper frontmatter and structure -3. **Format content**. Apply correct formatting for the release type -4. **Validate and preview**. Check structure and provide next steps - -## When to use this command - -* Announcing new API endpoints or features -* Documenting API changes, deprecations, or breaking changes -* Publishing SDK updates or new SDK versions -* Releasing developer tools or CLI updates -* Announcing platform changes affecting developers -* Documenting authentication or integration changes -* Publishing deprecation notices - -## Release categories - -Developer release notes typically cover: - -* **APIs**. New endpoints, changes, deprecations -* **SDKs**. New SDKs, version updates, improvements -* **CLI**. Command-line tool updates -* **Integrations**. New integrations or integration changes -* **Platform**. Platform changes affecting developers -* **Security**. Authentication, authorization changes -* **Deprecations**. End-of-life announcements - -## Workflow - -### Step 1: Gather information - -Ask the user for: - -**Required:** -* **Title/Topic**: Brief description of what this release is about -* **Release date**: Date in YYYY-MM-DD format -* **Content**: The release note content (what changed, why it matters) - -**Optional:** -* **Impact level**: Breaking change, deprecation, new feature, minor change -* **Documentation links**: Related doc pages -* **Slug**: Custom slug for filename (auto-generated from title if not provided) -* **Keywords**: Custom keywords for frontmatter (suggest defaults based on content) - -**Validate:** -* Check that date is not in the future -* Ensure content is clear and concise -* Verify any doc links are valid relative paths -* Ask user to confirm keywords before creating file - -### Step 2: Create the markdown file - -**File naming convention:** -``` -blog-developer/YYYY-MM-DD-{slug}.md -``` - -**Slug generation:** -* Lowercase the title -* Replace spaces with hyphens -* Remove special characters -* Keep concise (3-5 words max) - -Examples: -* `blog-developer/2026-03-23-api-endpoints.md` -* `blog-developer/2026-04-09-india-datacenter-deprecation.md` -* `blog-developer/2026-05-15-python-sdk-v2.md` - -**Important**: Files are created in `/blog-developer/` directory (root level, no subdirectories) - -### Step 3: Generate frontmatter - -**Standard frontmatter:** -```yaml ---- -title: {Month Day, YYYY} - {Topic} -image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 -hide_table_of_contents: true ---- -``` - -**Title formatting:** -* Start with full date: "Month Day, YYYY" (e.g., "April 9, 2025") -* Follow with " - " separator -* Add topic in Title Case (e.g., "Deprecation of Sumo Logic India Data Center") -* 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" - -**Image:** -* Always use the standard Sumo Logic preview image -* URL: `https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082` - -**Keywords (optional but recommended):** -* **Always ask user if they want to include keywords** -* Suggest keywords based on content type: - * API changes: `api`, `endpoints`, `rest-api` - * SDK updates: `sdk`, `python`, `java`, etc. - * Deprecations: `deprecation`, `end-of-life` - * Breaking changes: `breaking-change` - * Platform updates: `platform`, `datacenter` -* Format: - ```yaml - keywords: - - api - - deprecation - ``` -* User can choose to omit keywords or customize the list - -### Step 4: Add optional import - -For release notes that use links or useBaseUrl: -```javascript -import useBaseUrl from '@docusaurus/useBaseUrl'; -``` - -**Note**: Only add if content uses it. For simple text-only releases, omit. - -**Title guidelines:** -* Keep concise (2-5 words) -* Use title case -* Common patterns: "APIs", "SDKs", "CLI Tools", "Platform Updates" -* Can be more specific: "Python SDK", "REST API", "Management APIs" - -### Step 5: Write content - -Content goes directly after frontmatter (and optional import). No H3 heading needed — the title is in frontmatter. - -**Basic structure:** -```markdown ---- -title: March 23, 2026 - New Field Extraction Rules API -image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 -hide_table_of_contents: true ---- - -{Main content paragraph(s)} - -{Optional: H4 sections for subsections} - -{Optional: code blocks, lists, links} - -{Optional: admonitions for important notes} -``` - -### Step 6: Content formatting guidelines - -#### API Changes - -For API announcements, include: -* What changed (new endpoints, parameters, behavior) -* Impact on existing integrations -* Links to API documentation -* Migration guidance if breaking change - -**Example:** -```markdown ---- -title: March 23, 2026 - New Field Extraction Rules API -image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 -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 endpoints - -* **Field Extraction Rules API**: Create and manage Field Extraction Rules programmatically. See [Field Extraction Rules API](/docs/api/field-extraction-rules). -* **Webhook Connections API**: Create and manage webhook connections via API. See [Connections API](/docs/api/connections). - -#### Breaking changes - -**Monitors API**: The `notificationGroupFields` parameter is now required when creating monitors. Update your integrations before June 1, 2026. See the [Monitors API documentation](/docs/api/monitors) for details. -``` - -#### SDK Updates - -For SDK releases: -* Version number -* What's new or changed -* Installation instructions -* Link to SDK docs or GitHub - -**Example:** -```markdown ---- -title: March 23, 2026 - Python SDK Version 2.0 -image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 -hide_table_of_contents: true -keywords: - - sdk - - python ---- - -We've released version 2.0 of the Sumo Logic Python SDK with support for the latest APIs and improved error handling. - -#### What's new - -* Support for Field Extraction Rules API -* Async client support for better performance -* Improved error messages and debugging - -#### Installation - -```python -pip install sumologic-sdk==2.0.0 -``` - -Learn more in the [Python SDK documentation](/docs/api/python-client). -``` - -#### Deprecations - -For deprecation notices: -* What's being deprecated -* Why it's being deprecated (optional, if relevant) -* When it will be removed (end-of-life date) -* Migration path or alternatives -* Impact on existing users - -**Example (matches your template):** -```markdown ---- -title: April 9, 2025 - Deprecation of Sumo Logic India Data Center -image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 -hide_table_of_contents: true -keywords: - - deprecation - - datacenter ---- - -As previously communicated to impacted customers, effective as of April 30, 2025, customers will no longer be able to ingest data into the Sumo Logic Mumbai data center (`https://api.in.sumologic.com/`). Customers will retain access to historical data and basic search functionality until April 30, 2026, at which point all access will be terminated. - -Historical data will not be migrated to other deployments. - -**Reminder**: If you're still referencing the India endpoint, please update your integrations. For supported alternatives, see the [endpoint guide](/docs/api/about-apis/getting-started/#sumo-logic-endpoints-by-deployment-and-firewall-security). - -For help, contact [Support](https://support.sumologic.com/). -``` - -**Example (API deprecation):** -```markdown ---- -title: March 23, 2026 - Legacy Metrics API Deprecation -image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 -hide_table_of_contents: true -keywords: - - api - - deprecation ---- - -Effective **September 30, 2026**, the following legacy metrics API endpoints will be retired: -* `/v1/metrics/query` (use `/v2/metrics/query` instead) -* `/v1/metrics/catalog` (use `/v2/metrics/catalog` instead) - -**Migration**: Update your integrations to use the v2 endpoints. See the [Metrics API migration guide](/docs/api/metrics-migration) for details. - -**Impact**: After September 30, 2026, requests to legacy endpoints will return HTTP 410 (Gone). - -For help, contact [Support](https://support.sumologic.com/). -``` - -#### Minor Changes - -For small updates or enhancements: -* Brief description of the change -* Link to relevant docs -* Optional impact note - -**Example:** -```markdown ---- -title: March 23, 2026 - API Enhancements -image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 -hide_table_of_contents: true ---- - -We've made the following improvements to our APIs: - -* **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. -``` - -### Step 7: Validation checklist - -Before finishing, verify: -* [ ] File created in `/blog-developer/` directory (root level) -* [ ] Filename follows pattern: `YYYY-MM-DD-{slug}.md` -* [ ] Frontmatter complete with all required fields -* [ ] Title starts with "Month Day, YYYY - " format -* [ ] Date format uses full month name, no ordinal (e.g., "April 9" not "April 9th") -* [ ] `hide_table_of_contents: true` is present -* [ ] Standard image URL is used -* [ ] Content is clear and includes relevant links -* [ ] Breaking changes are clearly marked (use bold or H4 sections) -* [ ] Documentation links use relative paths (start with `/docs/`) -* [ ] Keywords added if applicable (deprecation, api, sdk, etc.) -* [ ] No trailing whitespace - -## Example usage - -### API Feature Example - -``` -User: "Create a developer release note for new Field Extraction Rules API endpoints, dated March 23, 2026" - -Claude: -1. Confirms date: March 23, 2026 -2. Generates slug: "field-extraction-rules-api" -3. Creates: blog-developer/2026-03-23-field-extraction-rules-api.md -4. Generates frontmatter: - - title: "March 23, 2026 - New Field Extraction Rules API" - - image: Standard Sumo Logic image - - hide_table_of_contents: true -5. Writes content with: - - Description of new endpoints - - Link to API documentation - - Impact notes -6. Provides checklist -``` - -### Deprecation Example - -``` -User: "Create a deprecation notice for Sumo Logic India Data Center, dated April 9, 2025" - -Claude: -1. Confirms date: April 9, 2025 -2. Generates slug: "india-datacenter-deprecation" -3. Creates: blog-developer/2025-04-09-india-datacenter-deprecation.md -4. Generates frontmatter: - - title: "April 9, 2025 - Deprecation of Sumo Logic India Data Center" - - keywords: deprecation, datacenter -5. Writes content with: - - What's being deprecated - - Timeline and dates - - Migration guidance - - Support contact -6. Provides checklist -``` - -## 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) - -**Examples:** -* ✅ March 23, 2026 -* ✅ January 1, 2026 -* ✅ December 31, 2025 -* ❌ March 23rd, 2026 (no ordinal) -* ❌ Mar 23, 2026 (abbreviated month) -* ❌ 2026-03-23 (wrong format) - -## Content formatting guidelines - -**Use formatting for clarity:** -* Use **bold** for important terms or breaking changes -* Use H4 sections (`####`) for subsections when needed -* Use bullet lists for multiple related items -* Use admonitions (`:::note`, `:::warning`) for important callouts - -**Example:** -```markdown -#### Breaking changes - -**Monitors API**: The `notificationGroupFields` parameter is now required when creating monitors. Update your integrations before June 1, 2026. - -:::warning -This is a breaking change. Existing integrations must be updated by June 1, 2026. -::: - -**Links:** -* Always use relative paths starting with `/docs/` -* Use descriptive link text (not "click here") -* Example: `[Metrics API documentation](/docs/api/metrics)` - -**Code blocks:** -* Use appropriate language tags (```python, ```bash, ```json) -* Keep examples concise and relevant -* Show before/after for migration guides - -## Safety principles - -* **Check for existing files** before creating to avoid duplicates -* **Use clear, descriptive slugs** that indicate content -* **Validate dates**. Ensure date is not in future -* **Include documentation links**. Help users find more info -* **Mark breaking changes clearly**. Use bold text or H4 sections -* **Use standard frontmatter**. Consistent image URL and structure -* **Keep content focused**. One topic per release note - -## Post-completion message - -After successfully creating the release note, tell the user: - -``` -✅ Developer release note created successfully! - -File created: -* 📄 blog-developer/{YYYY-MM-DD-slug}.md - -Summary: -* 📅 Title: {Month Day, YYYY} - {Topic} -* 📝 {Brief summary of content} -* 🏷️ Keywords: {keywords if added} - -Next steps: -1. Review content for accuracy and clarity -2. Verify documentation links are correct -3. Ensure breaking changes are clearly marked -4. Test locally: yarn start -5. Check preview at: http://localhost:3000/release-notes-developer -6. Submit PR: "DOCS-XXX - Developer release note: {Topic}" - -Checklist: -* [ ] Title format is correct (Month Day, YYYY - Topic) -* [ ] Date uses full month name, no ordinal -* [ ] Standard image URL is used -* [ ] hide_table_of_contents: true is present -* [ ] Documentation links use relative paths -* [ ] Breaking changes clearly marked -* [ ] Content is clear and concise - -The release note will appear on the Developer release notes page in reverse chronological order (newest first). - -Would you like me to help refine the content or add additional details? -``` - -## Error handling - -**If file already exists:** -* Show existing file path and creation date -* Ask if user wants to: - * Use different slug (e.g., add `-v2` or more specific topic) - * Use different date - * Overwrite (requires explicit confirmation) - -**If date is in the future:** -* Warn user and ask for confirmation -* Suggest using current date - -**If slug is too generic:** -* Warn if slug is too short or vague (e.g., "api", "update") -* Suggest more descriptive slug (e.g., "field-extraction-rules-api") - -**If documentation link looks invalid:** -* Warn if doesn't start with `/docs/` -* Suggest correction -* Proceed with user confirmation - -**If content is too long:** -* Suggest breaking into subsections (H4) -* Recommend creating separate doc page and linking to it from release note - -## Tips and best practices - -**For API changes:** -* Be specific about what endpoints changed -* Include examples of new request/response formats -* Provide migration timeline for breaking changes -* Link to comprehensive API documentation - -**For deprecations:** -* Give ample notice (3-6 months minimum) -* Clearly state end-of-life date -* Provide migration path with examples -* Offer support contact for questions - -**For SDK releases:** -* Include version number prominently -* Show installation/upgrade commands -* Highlight breaking changes separately -* Link to changelog or GitHub release - -**All release notes:** -* Write for developers (assume technical knowledge) -* Focus on impact and action items -* Use clear, direct language -* Provide links for more information -* Keep entries concise but complete - -## References - -* [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) diff --git a/.claude/commands/release-note-service.md b/.claude/commands/release-note-service.md deleted file mode 100644 index 4126e3a28b..0000000000 --- a/.claude/commands/release-note-service.md +++ /dev/null @@ -1,474 +0,0 @@ -# Create New Service Release Note - -Automates the creation of Service release notes for new features, updates, and improvements across Sumo Logic platform categories. - -## What this command does - -When you invoke `release-note-service`, Claude will guide you through: - -1. **Determine category**. Apps, Manage, Collection, Search, or UI -2. **Gather release details**. Feature name, description, and changes -3. **Create markdown file**. Generate file with proper frontmatter and structure -4. **Format content**. Apply correct formatting for the feature announcement -5. **Validate and preview**. Check structure and provide next steps - -## When to use this command - -* Announcing new platform features or capabilities -* Documenting updates to existing features -* Publishing UI improvements and enhancements -* Releasing new collection methods or integrations -* Announcing management and admin features -* Publishing app-related updates - -## Categories - -Service release notes are organized by platform area: - -* **Apps**. App-related features and updates -* **Collection**. Data collection features, sources, authentication -* **Manage**. Management and administration features -* **Search**. Search features, queries, analytics -* **UI**. User interface updates and improvements (often labeled "New UI") - -## Workflow - -### Step 1: Gather information - -Ask the user for: - -**Required:** -* **Category**: Which platform area (apps, collection, manage, search, ui) -* **Feature name**: Brief, descriptive name of the feature or update -* **Release date**: Date in YYYY-MM-DD format -* **Description**: What the feature does and why it matters (2-3 sentences) - -**Optional:** -* **Documentation link**: Relative path to the doc (e.g., `/docs/manage/...`) -* **"What's new" details**: Bulleted list of specific changes or capabilities -* **Keywords**: Custom keywords for frontmatter (suggest defaults based on content) - -**Validate:** -* Check that date is not in the future -* Ensure category is valid (apps, collection, manage, search, ui) -* Verify documentation link is valid relative path if provided -* Ask user to confirm keywords before creating file - -### Step 2: Create the markdown file - -**File naming convention:** -``` -blog-service/YYYY-MM-DD-{category}.md -``` - -Examples: -* `blog-service/2026-03-20-collection.md` -* `blog-service/2026-03-18-apps.md` -* `blog-service/2026-02-12-ui.md` - -**Important**: Files are created in `/blog-service/` directory - -**Note on file conflicts**: If a file already exists for the same date and category, ask the user: -* Use a different date -* Append to existing file (if related features) -* Use more specific category suffix (e.g., `-collection-m365` if needed) - -### Step 3: Generate frontmatter - -**Standard frontmatter:** -```yaml ---- -title: {Feature Description} ({Category}) -image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 -keywords: - - {keyword1} - - {keyword2} -hide_table_of_contents: true ---- -``` - -**Title formatting:** -* Feature description in Title Case -* Category in parentheses: (Apps), (Collection), (Manage), (Search), (New UI) -* NO date in title (unlike other release note types) -* Keep concise but descriptive -* Examples: - * "App Registration Authentication for Microsoft 365 Audit Source (Collection)" - * "Data Volume for MSSP (Apps)" - * "Content Item Actions Available Directly From Navigation Menus (New UI)" - -**Category labels in titles:** -* apps → (Apps) -* collection → (Collection) -* manage → (Manage) -* search → (Search) -* ui → (New UI) - -**Image:** -* Always use the standard Sumo Logic preview image -* URL: `https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082` - -**Keywords:** -* **Always ask user to confirm keywords before creating file** -* Suggest keywords based on content: - * Feature-specific terms (e.g., "Microsoft 365 Audit", "authentication") - * Category keywords (e.g., "apps", "ui", "collection") - * Product names or technologies mentioned -* Format: - ```yaml - keywords: - - keyword1 - - keyword2 - ``` -* User can customize the list - -### Step 4: Add optional import - -For release notes that use links or useBaseUrl: -```javascript -import useBaseUrl from '@docusaurus/useBaseUrl'; -``` - -**Note**: Only add if content uses it. For simple text-only releases, omit. - -### Step 5: Write content - -Content goes directly after frontmatter (and optional import). No H3 heading needed — the title is in frontmatter. - -**Basic structure:** -```markdown ---- -title: Feature Name (Category) -image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 -keywords: - - keyword1 - - keyword2 -hide_table_of_contents: true ---- - -{Description paragraph explaining the feature and its benefits} - -{Optional: What's new section with bulleted list} - -{Optional: Documentation links} -``` - -#### Simple Feature Announcement - -For straightforward feature updates: -```markdown ---- -title: App Registration Authentication for Microsoft 365 Audit Source (Collection) -image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 -keywords: - - Microsoft 365 Audit - - authentication -hide_table_of_contents: true ---- - -The Microsoft 365 Audit Source now supports the App Registration authentication method. This enhancement allows organizations to authenticate using Azure Active Directory App Registrations, providing a more secure and flexible authentication option for collecting Microsoft 365 audit logs. - -[Learn more](/docs/send-data/hosted-collectors/cloud-to-cloud-integration-framework/microsoft-365-audit-source/). -``` - -#### Feature with "What's new" Section - -For features with multiple specific changes: -```markdown ---- -title: Content Item Actions Available Directly From Navigation Menus (New UI) -image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 -keywords: - - ui -hide_table_of_contents: true ---- - -You can now perform common actions on content items directly from the navigation menus in the left-hand sidebar, making it faster and easier to manage your content without opening each item. - -**What's new:** -* Right-click on any content item in the sidebar to access a context menu -* Available actions: Open, Open in New Tab, Copy, Move, Delete, Share, Schedule Report -* Works for dashboards, searches, folders, and other content items -* Same functionality as the Actions menu in the Content Library - -This enhancement streamlines your workflow by providing quick access to frequently used actions. [Learn more](/docs/get-started/library/). -``` - -### Step 6: Content formatting guidelines - -**Write for clarity:** -* Start with a clear statement of what the feature is -* 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 - -**Use formatting for readability:** -* Use **bold** for section labels like "What's new:" -* Use bullet lists for multiple related items -* Use admonitions (`:::note`, `:::warning`) for important callouts if needed -* Keep paragraphs concise (2-4 sentences max) - -**Links:** -* Always use relative paths starting with `/docs/` -* Use descriptive link text (typically "Learn more") -* Example: `[Learn more](/docs/send-data/...)` - -**Examples by category:** - -**Apps:** -```markdown ---- -title: Data Volume for MSSP (Apps) -image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 -keywords: - - data-volume-for-mssp - - apps -hide_table_of_contents: true ---- - -The Data Volume for MSSP app is now available, providing managed security service providers with visibility into data usage across multiple customer accounts. This app helps MSSPs track, analyze, and optimize data ingestion to improve cost management and capacity planning. - -[Learn more](/docs/integrations/sumo-apps/data-volume-for-mssp). -``` - -**Collection:** -```markdown ---- -title: Enhanced Authentication Options for Cloud Sources (Collection) -image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 -keywords: - - authentication - - cloud-to-cloud - - collection -hide_table_of_contents: true ---- - -Cloud-to-Cloud sources now support additional authentication methods including OAuth 2.0 client credentials flow and service account authentication. These new options provide more flexibility for enterprise customers to integrate with cloud services using their preferred authentication standards. - -**What's new:** -* OAuth 2.0 client credentials flow for machine-to-machine authentication -* Service account support for Google Cloud and AWS integrations -* Enhanced security with token rotation and expiration handling -* Backward compatible with existing authentication methods - -[Learn more](/docs/send-data/hosted-collectors/cloud-to-cloud-integration-framework/). -``` - -**UI:** -```markdown ---- -title: Improved Dashboard Loading Performance (New UI) -image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 -keywords: - - ui - - dashboards - - performance -hide_table_of_contents: true ---- - -Dashboards now load up to 50% faster in the new UI through optimized query execution and progressive rendering. Large dashboards with many panels will see the most significant improvements, reducing wait times and improving the overall user experience. -``` - -### Step 7: Validation checklist - -Before finishing, verify: -* [ ] File created in `/blog-service/` directory -* [ ] Filename follows pattern: `YYYY-MM-DD-{category}.md` -* [ ] Frontmatter complete with all required fields -* [ ] Title includes feature description and category in parentheses -* [ ] Title does NOT include date -* [ ] `hide_table_of_contents: true` is present -* [ ] Standard image URL is used -* [ ] Keywords confirmed with user -* [ ] Category label uses correct format: (Apps), (Collection), (Manage), (Search), (New UI) -* [ ] Content is clear and focused on user benefits -* [ ] Documentation link uses relative path (starts with `/docs/`) -* [ ] No trailing whitespace - -## Example usage - -### Collection Feature Example - -``` -User: "Create a Service release note for Microsoft 365 Audit Source App Registration authentication, collection category, dated March 20, 2026" - -Claude: -1. Confirms category: Collection -2. Confirms date: 2026-03-20 -3. Asks for keywords (suggests: "Microsoft 365 Audit", "authentication") -4. Creates: blog-service/2026-03-20-collection.md -5. Generates frontmatter: - - title: "App Registration Authentication for Microsoft 365 Audit Source (Collection)" - - keywords: Microsoft 365 Audit, authentication -6. Writes content with: - - Description of new authentication method - - Business value - - Link to documentation -7. Provides checklist -``` - -### UI Feature Example - -``` -User: "Create a Service release note for new context menu actions in the sidebar, UI category, dated February 12, 2026" - -Claude: -1. Confirms category: UI -2. Confirms date: 2026-02-12 -3. Asks for keywords (suggests: "ui", "navigation") -4. Creates: blog-service/2026-02-12-ui.md -5. Generates frontmatter: - - title: "Content Item Actions Available Directly From Navigation Menus (New UI)" - - keywords: ui -6. Writes content with: - - Feature description - - "What's new" section with bullets - - Link to documentation -7. Provides checklist -``` - -## Category guidelines - -**Apps**. Use for: -* New apps or app updates -* App integrations -* App-specific features -* MSSP or multi-tenant features - -**Collection**. Use for: -* New sources or source types -* Collection authentication changes -* Collector features -* Data ingestion enhancements - -**Manage**. Use for: -* Account management features -* User and role management -* Security and compliance features -* Settings and configuration updates - -**Search**. Use for: -* Search language enhancements -* Query performance improvements -* Analytics features -* Data parsing updates - -**UI**. Use for: -* User interface changes -* Navigation improvements -* Visual design updates -* Workflow enhancements -* Label as "(New UI)" in title - -## Safety principles - -* **Check for existing files** before creating (same date + category = conflict) -* **Validate category** is one of: apps, collection, manage, search, ui -* **Use clear, descriptive titles** that explain the feature -* **Include documentation links**. Help users find more info -* **Use standard frontmatter**. Consistent image URL and structure -* **Keep content focused**. One feature per release note -* **Always ask user to confirm keywords** before creating file - -## Post-completion message - -After successfully creating the release note, tell the user: - -``` -✅ Service release note created successfully! - -File created: -* 📄 blog-service/{YYYY-MM-DD-category}.md - -Summary: -* 📋 Category: {Category} -* 📝 Title: {Feature Description} ({Category}) -* 🏷️ Keywords: {keywords} - -Next steps: -1. Review content for accuracy and clarity -2. Verify documentation link is correct -3. Ensure keywords are appropriate -4. Test locally: yarn start -5. Check preview at: http://localhost:3000/release-notes-service -6. Submit PR: "DOCS-XXX - Service release note: {Feature Description}" - -Checklist: -* [ ] Title format is correct (Feature Description (Category)) -* [ ] Title does NOT include date -* [ ] Category label uses correct format -* [ ] Standard image URL is used -* [ ] hide_table_of_contents: true is present -* [ ] Documentation link uses relative path -* [ ] Content is clear and concise -* [ ] Keywords confirmed with user - -The release note will appear on the Service release notes page in reverse chronological order (newest first). - -Would you like me to help refine the content or add additional details? -``` - -## Error handling - -**If file already exists:** -* Show existing file path and creation date -* Ask if user wants to: - * Use different date - * Append to existing file (if related features) - * Use more specific category suffix (e.g., `-collection-m365`) - * Overwrite (requires explicit confirmation) - -**If date is in the future:** -* Warn user and ask for confirmation -* Suggest using current date - -**If category is invalid:** -* Show error: "Category must be one of: apps, collection, manage, search, ui" -* Ask user to select valid category - -**If documentation link looks invalid:** -* Warn if doesn't start with `/docs/` -* Suggest correction -* Proceed with user confirmation - -**If title is too long:** -* Warn if title exceeds 100 characters -* Suggest shorter, more concise wording -* Category label must stay in title - -**If keywords not confirmed:** -* Do not create file until user confirms keywords -* Show suggested keywords and wait for approval/modification - -## Tips and best practices - -**For all Service releases:** -* 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 - -**Title guidelines:** -* Be specific about the feature (not "New Collection Feature") -* Use active language ("Enhanced...", "New...", "Improved...") -* Include category in parentheses at end -* No date in title (unlike other release types) -* Keep under 100 characters including category - -**Content structure:** -* First paragraph: What is it and why does it matter? -* Optional "What's new" section: Specific capabilities or changes -* Final element: "Learn more" link to docs - -**Keywords:** -* Include feature-specific terms -* Add category keyword (apps, ui, collection, etc.) -* Mention product names or technologies -* Keep list focused (2-5 keywords) - -## References - -* [Service Release Notes](https://sumologic.com/help/release-notes-service) -* [Release Notes Index](/docs/release-notes) -* [Style Guide](/docs/contributing/style-guide) diff --git a/.claude/commands/release-note.md b/.claude/commands/release-note.md new file mode 100644 index 0000000000..1d819cb272 --- /dev/null +++ b/.claude/commands/release-note.md @@ -0,0 +1,369 @@ +# Release Note + +Creates release notes for Sumo Logic products. Ask the user which type before proceeding. + +## Types + +| Type | Blog dir | File pattern | +|---|---|---| +| **Service** | `blog-service/` | `YYYY-MM-DD-{category}.md` | +| **Collector** | `blog-collector/` | `YYYY-MM-DD-{type}.md` | +| **Cloud SIEM** | `blog-cse/` | `YYYY-MM-DD-{type}.md` | +| **Cloud SOAR** | `blog-csoar/` | `YYYY-MM-DD-{subtype}.md` | +| **Developer** | `blog-developer/` | `YYYY-MM-DD-{slug}.md` | + +Ask the user which type, then follow the appropriate section below. + +**Shared frontmatter values (all types):** +- `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` + +If a file already exists for the same date and type, ask the user to use a different date, append to the existing file, or add a more specific suffix. + +--- + +## Service (`blog-service/`) + +**Subtypes**: apps, collection, manage, search, ui + +**Gather**: category, feature name, release date, description (2–3 sentences), doc link (optional), "What's new" bullets (optional), keywords (confirm with user before creating file). + +**File**: `blog-service/YYYY-MM-DD-{category}.md` + +**Frontmatter**: +```yaml +--- +title: {Feature Description} ({Category Label}) +image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 +keywords: + - {keyword1} +hide_table_of_contents: true +--- +``` + +**Title**: Feature description in Title Case + category label in parentheses. No date in title. +- apps → (Apps) | collection → (Collection) | manage → (Manage) | search → (Search) | ui → (New UI) + +**Content**: +```markdown +{Description — what the feature is and why it matters} + +**What's new:** +* {Specific capability} + +[Learn more](/docs/path/to/doc). +``` + +"What's new:" is optional — use for multiple specific changes, omit for single-point announcements. Only add `import useBaseUrl` if the content uses it. + +**Validation**: +- [ ] `blog-service/YYYY-MM-DD-{category}.md` +- [ ] Title: feature description + category label in parens, no date +- [ ] `hide_table_of_contents: true` +- [ ] Keywords confirmed with user +- [ ] Doc link uses `/docs/...` relative path + +--- + +## Collector (`blog-collector/`) + +**File**: `blog-collector/YYYY-MM-DD-{type}.md` (`-installed` or `-otel`) + +### Installed Collector + +**Gather**: version number (X.Y.Z-N), release date, list of security fixes / bug fixes / features. + +**Frontmatter**: +```yaml +--- +title: Installed Collector Version {X.Y.Z-N} +image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 +hide_table_of_contents: true +keywords: + - installed-collector +--- +``` + +**Content**: +```markdown +In this release, we've enhanced the security and stability of the Collector with added support for {security patches/bug fixes/features}. + +#### Security fix + +* Upgraded `{package}` to version **{version}** to address known security vulnerability ({CVE-YYYY-NNNNN}). + +#### Bug fix + +* {Bug fix description}. +``` + +- Sections use H4 (`####`). Order: Security fix → Bug fix → Feature. +- Package names in backticks, version numbers in **bold**. +- Include CVE/GHSA references (CVE-YYYY-NNNNN or GHSA-XXXX-XXXX-XXXX). +- Keywords are always `installed-collector` — no user confirmation needed. + +**Validation**: +- [ ] Title: "Installed Collector Version X.Y.Z-N" +- [ ] H4 sections in correct order (Security → Bug → Feature) +- [ ] Versions in **bold**, packages in backticks +- [ ] CVE/GHSA references where applicable + +### OpenTelemetry Collector + +**Gather**: feature name, release date, description (focus on user benefit), doc link. + +**Frontmatter**: +```yaml +--- +title: {Feature Name} +image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 +hide_table_of_contents: true +keywords: + - opentelemetry-collector +--- +``` + +**Content**: +```markdown +import useBaseUrl from '@docusaurus/useBaseUrl'; + +We're excited to announce {feature description}. {Benefits}. [Learn more](/docs/path/to/doc). +``` + +Start with "We're excited to announce..." or "We're excited to introduce...". Keywords are always `opentelemetry-collector` — no user confirmation needed. Use admonitions for important notes or breaking changes. + +**Validation**: +- [ ] Starts with "We're excited to..." +- [ ] "Learn more" link with relative path +- [ ] Keywords: `opentelemetry-collector` + +--- + +## Cloud SIEM (`blog-cse/`) + +**File**: `blog-cse/YYYY-MM-DD-{type}.md` (`-content` or `-application`) + +Always include `import useBaseUrl from '@docusaurus/useBaseUrl';` after frontmatter. + +### Content release + +**Gather**: release date, new/updated rules (IDs and names), log mappers, parsers, 3–5 high-level summary points, keywords (confirm with user; default: rules, log mappers, parsers). + +**Frontmatter**: +```yaml +--- +title: {Month} {Day ordinal}, {Year} - Content Release +hide_table_of_contents: true +keywords: + - rules + - log mappers + - parsers +image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 +--- +``` + +Title uses ordinal suffix (12th, 3rd, 21st). Full month name, not abbreviated. Examples: "March 19th, 2026 - Content Release", "February 3rd, 2026 - Content Release". + +**Content**: +```markdown +This content release includes: + - {Summary point 1} + - {Summary point 2} + +Additional changes are enumerated below. + +### Rules +* [New] MATCH-SXXXX Rule Name. +* [Updated] FIRST-SXXXX Rule Name. Brief description of what changed. + +### Log Mappers +* [New] Vendor - Event Type. + +### Parsers +* [Updated] /Parsers/System/Vendor/Parser Name. +``` + +- Summary bullets use 4-space indentation. +- `[New]` or `[Updated]` tag on every item. +- Rule ID formats: `MATCH-SXXXX`, `FIRST-SXXXX`, `THRESHOLD-SXXXX`, `AGGREGATION-SXXXX`, `CHAIN-SXXXX`, `OUTLIER-SXXXX` +- Parser paths use full hierarchy: `/Parsers/System/Vendor/Name` +- Log mapper format: `Vendor - Event Type` +- Sort alphabetically within each section. +- Do not invent rule IDs — ask the user if not provided. + +### Application release + +**Gather**: release date, features with descriptions and doc links, screenshots (if applicable), keywords (confirm with user). + +**Frontmatter**: +```yaml +--- +title: {Month} {Day}, {Year} - Application Update +image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 +keywords: + - {keyword} +hide_table_of_contents: true +--- +``` + +**Content**: +```markdown +### {Feature Name} + +{Description and business value}. [Learn more](/docs/path/to/docs). +``` + +H3 for each feature. Add screenshots with `description` for UI changes. + +**Validation (both CSE types)**: +- [ ] `blog-cse/YYYY-MM-DD-{type}.md` +- [ ] Title uses ordinal suffix for content releases +- [ ] `import useBaseUrl` included +- [ ] `hide_table_of_contents: true` +- [ ] Content: `[New]`/`[Updated]` tags on all items; parser paths complete +- [ ] Keywords confirmed with user + +--- + +## Cloud SOAR (`blog-csoar/`) + +**File**: `blog-csoar/YYYY-MM-DD-{subtype}.md` +- Content release: `YYYY-MM-DD-content-release.md` +- Application update: `YYYY-MM-DD-application-update.md` + +Always include `import useBaseUrl from '@docusaurus/useBaseUrl';` after frontmatter. + +**Date format in title**: "Month DD, YYYY" — full month name, zero-padded day, no ordinal. Examples: "March 06, 2026" ✅, "March 6, 2026" ❌, "March 6th, 2026" ❌. + +Application Updates are published early the following month for the previous month's changes. Filename and title use the publication date; the H2 header and intro use the release month. + +**Keywords** (confirm with user): +- Content release: `automation service`, `cloud soar`, `soar` +- Application update: `automation service`, `cloud soar` + +**Integration doc path**: `/docs/platform-services/automation-service/app-central/integrations/{slug}/` + +### Content release + +**Frontmatter**: +```yaml +--- +title: {Month DD, 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: + - automation service + - cloud soar + - soar +--- +``` + +**Content**: +```markdown +This release introduces {what's new}. + +### Integrations + +* [New] [Integration Name](/docs/platform-services/automation-service/app-central/integrations/{slug}/) +* [Updated] [Integration Name](/docs/platform-services/automation-service/app-central/integrations/{slug}/) + +### Playbooks + +* [New] {ID} - {Playbook Title} +``` + +Integration entries are link-only — no descriptions. Playbooks section is optional. + +### Application update + +**Frontmatter**: +```yaml +--- +title: {Month DD, 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: + - automation service + - cloud soar +--- +``` + +**Content**: +```markdown +## {Release month} release + +Following are the updates made in {Month} {YYYY}. + +### Changes and enhancements + +#### Integrations + +* [Added] [Integration Name](/docs/path/) - Description of what was added. +* [Updated] [Integration Name](/docs/path/) - Description of what was updated. + +#### Platform + +* Platform enhancement description. + +### Bug Fixes + +#### Integrations + +* In the [Integration Name](/docs/path/) integration, description of fix. + +#### Platform + +Fixed an issue where {description}. +``` + +Integration changes use `[Added]` for new integrations, `[Updated]` for existing. Always include descriptions (unlike content releases). + +**Validation (both SOAR types)**: +- [ ] `blog-csoar/`; filename uses full suffix (`-content-release.md` or `-application-update.md`) +- [ ] Title: "Month DD, YYYY" format (zero-padded, no ordinal) +- [ ] `import useBaseUrl` included +- [ ] `hide_table_of_contents: true` +- [ ] Keywords confirmed with user +- [ ] Application update: H2 header uses release month, not publication month + +--- + +## Developer (`blog-developer/`) + +**Gather**: title/topic, release date, content (what changed, why it matters, impact), doc links, keywords (optional; ask user). + +**File**: `blog-developer/YYYY-MM-DD-{slug}.md` + +Slug: lowercase, hyphens, 3–5 words. Examples: `api-endpoints`, `india-datacenter-deprecation`, `python-sdk-v2`. + +**Frontmatter**: +```yaml +--- +title: {Month Day, YYYY} - {Topic} +image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 +hide_table_of_contents: true +--- +``` + +**Title format**: "Month Day, YYYY - Topic" — full month, no ordinal. Examples: "April 9, 2025" ✅, "April 9th, 2025" ❌, "Apr 9, 2025" ❌. + +**Content**: +```markdown +{Main paragraph — what changed, why it matters} + +#### {Subsection if needed} + +* {Item} +``` + +- H4 (`####`) for subsections. +- `:::warning` admonitions for breaking changes. +- Doc links always use relative paths (`/docs/...`). +- Only add `import useBaseUrl` if content uses images. + +**Validation**: +- [ ] `blog-developer/YYYY-MM-DD-{slug}.md` +- [ ] Title: "Month Day, YYYY - Topic" (no ordinal) +- [ ] `hide_table_of_contents: true` +- [ ] Breaking changes clearly marked +- [ ] Doc links use relative paths diff --git a/.claude/commands/remove-doc.md b/.claude/commands/remove-doc.md index 6a2821a8fe..1755ba360f 100644 --- a/.claude/commands/remove-doc.md +++ b/.claude/commands/remove-doc.md @@ -2,24 +2,6 @@ Automates the complete workflow for removing or moving a Sumo Logic doc while preventing broken links and maintaining SEO health. -## What this command does - -When you invoke `/remove-doc`, Claude will guide you through: - -1. **Create 301 redirect**. Add redirect mapping to `cid-redirects.json`. -2. **Update internal links**. Find and replace all references to the old URL. -3. **Remove from hub pages**. Delete card from parent `index.md` and Product List. -4. **Delete the doc file**. Remove the actual markdown file. -5. **Remove from navigation**. Delete entry from `sidebars.ts`. -6. **Optional steps**. Add deprecation notes, hide from search engines. - -## When to use this command - -* Deprecating legacy docs in favor of new versions. -* Consolidating duplicate content. -* Removing outdated documentation. -* Moving docs to new locations. - ## Workflow ### Step 1: Gather information @@ -102,24 +84,6 @@ Before finishing, verify: * [ ] JSON files valid (no syntax errors). * [ ] Build test passes (optional: `yarn build`). -## Example usage - -``` -User: "Remove the nginx-legacy.md doc and redirect to nginx.md" - -Claude: -1. Confirms old path: docs/integrations/web-servers/nginx-legacy.md -2. Confirms new path: docs/integrations/web-servers/nginx.md -3. Adds redirect: "/docs/integrations/web-servers/nginx-legacy": "/docs/integrations/web-servers/nginx" -4. Searches for all references to nginx-legacy -5. Updates links in 3 files -6. Removes from web-servers index.md hub page -7. Deletes nginx-legacy.md -8. Removes from sidebars.ts -9. Asks about deprecation note -10. Provides verification checklist -``` - ## Safety principles * **Always create the redirect first** before deleting anything. @@ -169,30 +133,3 @@ Create: Multiple redirects, all pointing to unified-doc.md * Revert the change. * Fix and retry. -## Post-completion message - -After successfully removing a doc, tell the user: - -``` -✅ Doc removal complete! - -Summary: -* Added 301 redirect: /old-path → /new-path -* Updated X internal links across Y files -* Removed from hub page and sidebar -* Deleted old doc file - -Next steps: -1. Test locally: yarn start -2. Verify redirect works -3. Submit PR with description: "DOCS-XXX - Remove deprecated [doc name]" -4. Note: Google may take weeks to update search results - -Would you like me to run a build test or create a commit? -``` - -## References - -* [Contributing guide: Move or Remove a Doc](/docs/contributing/remove-doc). -* [CID redirects documentation](/docs/contributing/create-edit-doc#step-6-create-cid-url). -* [Sidebar configuration patterns](.claude/skills/docusaurus/). diff --git a/.claude/commands/rewrite-intro.md b/.claude/commands/rewrite-intro.md index f460af749c..e5b8f63425 100644 --- a/.claude/commands/rewrite-intro.md +++ b/.claude/commands/rewrite-intro.md @@ -2,26 +2,6 @@ Rewrites the intro/opening paragraph of a documentation page to match Sumo Logic voice and tone standards. -## What this command does - -When you invoke `/rewrite-intro`, Claude will: - -1. **Fetch the style guide**. Get latest voice and tone rules from live style guide -2. **Read the documentation file**. Analyze the current introduction -3. **Identify issues**. Find voice/tone violations, branding issues, clarity problems -4. **Rewrite the intro**. Create a new opening that matches Sumo Logic standards -5. **Present changes**. Show before/after with explanation of what changed -6. **Apply edits**. Update the file with user approval - -## When to use this command - -* Improving existing documentation intros that don't match Sumo Logic voice -* Converting formal or stiff language to conversational tone -* Fixing branding issues (missing app/source openers) -* Simplifying overly complex opening paragraphs -* Applying 8th-grade reading level to introductions -* Fixing passive voice in opening content - ## Workflow ### Step 1: Fetch Style Guide @@ -297,19 +277,3 @@ Metrics provide quantitative measurements of your infrastructure and application - Simplified: "This functionality" → direct statement - Added specific use cases (track, alert, visualize) -## Tips for Good Rewrites - -1. **Lead with value**. Start with what it is and what it does, not background -2. **Be specific**. "monitor login patterns" not "gain visibility" -3. **Show benefits**. Tell the reader why they should care -4. **Keep it short**. 2-3 sentences is usually enough for an intro -5. **Match document type**. Apps and sources have specific openers -6. **Test reading level**. Read it aloud; if it sounds stiff, simplify -7. **Focus on the user**. "You can..." not "This allows users to..." - -## After the Rewrite - -Once applied, suggest: -- Review the rest of the document for similar issues -- Consider using `/tone-check` on the full file -- Verify that the intro flows into the next section diff --git a/.claude/commands/seo-audit.md b/.claude/commands/seo-audit.md index c31de4d476..472e1e94fb 100644 --- a/.claude/commands/seo-audit.md +++ b/.claude/commands/seo-audit.md @@ -2,26 +2,6 @@ Audits documentation for search engine optimization (SEO), answer engine optimization (AEO), and generative engine optimization (GEO) signals. Produces a prioritized report and offers to apply fixes. -## What this command does - -When you invoke `/seo-audit`, Claude will: - -1. **Read the specified file or directory** -2. **Check SEO signals**. Title length, meta description, keywords, heading structure -3. **Check AEO signals**. Question-format headings, direct answers, featured snippet readiness -4. **Check GEO signals**. Authoritative statements, structured facts, LLM citation patterns -5. **Check internal linking**. Presence of links, descriptive anchor text -6. **Generate a prioritized report**. Issues ranked by impact -7. **Offer to fix issues**. Apply improvements with user approval - -## When to use this command - -* Before submitting a PR for new or updated content -* Auditing a section or category for discoverability gaps -* Preparing docs for a product launch or announcement -* Quarterly content health checks -* After rewriting or restructuring a doc - ## Signal definitions **SEO** (Search Engine Optimization): signals that help traditional search engines rank and surface pages. diff --git a/.claude/commands/simplify.md b/.claude/commands/simplify.md index abdefb2024..7f978b80d1 100644 --- a/.claude/commands/simplify.md +++ b/.claude/commands/simplify.md @@ -2,26 +2,6 @@ Simplifies overly complex, verbose, or hard-to-understand documentation content to meet 8th-grade reading level standards. -## What this command does - -When you invoke `/simplify`, Claude will: - -1. **Read target content**. Get the file, section, or text to simplify -2. **Analyze complexity**. Identify reading level, passive voice, long sentences, jargon -3. **Rewrite content**. Simplify while maintaining technical accuracy -4. **Present comparison**. Show before/after with complexity analysis -5. **Apply changes**. Update with user approval - -## When to use this command - -* Content is too technical or wordy -* Reading level above 8th grade -* Long, complex sentences (20+ words) -* Excessive passive voice -* Unnecessary jargon or filler words -* User feedback that docs are "hard to understand" -* Preparing content for broader audience - ## Workflow ### Step 1: Get Target Content @@ -376,20 +356,3 @@ May already be optimal: - Remove filler only - Don't over-engineer -## Tips for Good Simplification - -1. **Read aloud**. If it sounds stiff or confusing, simplify more -2. **One idea per sentence**. Don't combine unrelated concepts -3. **Front-load information**. Put the main point first -4. **Use familiar words**. Choose words most people know -5. **Provide examples**. Concrete examples clarify abstract concepts -6. **Test with fresh eyes**. Would a new user understand this? -7. **Maintain voice**. Keep Sumo Logic conversational tone - -## After Simplification - -Suggest: -- Review the rest of the document for similar issues -- Use `/tone-check` to validate voice and tone -- Consider if other sections need simplification -- Test with someone unfamiliar with the topic diff --git a/.claude/commands/tone-check.md b/.claude/commands/tone-check.md index 3a5c217c08..97715675ea 100644 --- a/.claude/commands/tone-check.md +++ b/.claude/commands/tone-check.md @@ -2,26 +2,6 @@ Validates documentation against Sumo Logic voice and tone rules, identifying violations and suggesting fixes. -## What this command does - -When you invoke `/tone-check`, Claude will: - -1. **Fetch style guide**. Get latest voice and tone rules -2. **Read documentation**. Analyze the specified file -3. **Identify violations**. Find voice/tone issues with line numbers -4. **Generate report**. Categorize by severity (Critical, Warning, Suggestion) -5. **Offer fixes**. Show specific corrections -6. **Apply changes**. Update with user approval - -## When to use this command - -* Before submitting a pull request -* After writing new documentation -* Validating existing docs for compliance -* Checking docs flagged in reviews -* Ensuring voice/tone consistency -* Training on Sumo Logic style - ## Workflow ### Step 1: Fetch Style Guide @@ -478,14 +458,6 @@ Some documents may have valid exceptions: Flag these as suggestions, not critical issues. -## After the Tone Check - -Suggest next steps: -- If many issues: Use `/rewrite-intro` or `/simplify` on problematic sections -- If clean: Ready for PR -- If medium issues: Fix and re-run tone check -- Consider running `/audit-doc` for full quality check - ## Common Patterns ### Serial Offenders @@ -512,12 +484,3 @@ For 1-2 violations, just fix them: "Found one negative contraction on line 45. Should I fix it?" ``` -## Tips for Running Tone Checks - -1. **Run early and often**. Catch issues before they multiply -2. **Check before PRs**. Don't let violations reach review -3. **Use with /simplify**. Tone check after simplifying content -4. **Train your eye**. Learn common patterns to avoid them -5. **Focus on critical first**. Don't get bogged down in suggestions -6. **Batch similar fixes**. Fix all passive voice at once -7. **Re-run after fixes**. Verify all issues resolved diff --git a/CLAUDE.md b/CLAUDE.md index b2d98bcf07..4ab72c8ed7 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -72,11 +72,7 @@ When a user asks "what can I do", "what commands are available", or similar, sha | Command | What it does | |---------|-------------| -| `/release-note-service` | New service release note | -| `/release-note-collector` | New Collector release note | -| `/release-note-cse` | New Cloud SIEM release note | -| `/release-note-csoar` | New Cloud SOAR release note | -| `/release-note-developer` | New developer/API release note | +| `/release-note` | New release note (service, collector, Cloud SIEM, Cloud SOAR, or developer) | **Editing and reviewing** From e509b6126505fa35d5df1ab1dde7c15e3fe02870 Mon Sep 17 00:00:00 2001 From: Kim Pohas Date: Wed, 20 May 2026 02:29:15 -0700 Subject: [PATCH 02/22] DOCS-1640: Add review.md command for PR-level doc quality checks MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Applies audit-doc checks to all changed .md files in a PR and produces a consolidated review comment. Read-only — surfaces issues without fixing. Also fixes sentence case rule in audit-doc.md (was incorrectly Title Case). Co-Authored-By: Claude Sonnet 4.6 --- .claude/commands/audit-doc.md | 2 +- .claude/commands/review.md | 115 ++++++++++++++++++++++++++++++++++ CLAUDE.md | 2 +- 3 files changed, 117 insertions(+), 2 deletions(-) create mode 100644 .claude/commands/review.md diff --git a/.claude/commands/audit-doc.md b/.claude/commands/audit-doc.md index 94848f5cba..0400b1dee3 100644 --- a/.claude/commands/audit-doc.md +++ b/.claude/commands/audit-doc.md @@ -46,7 +46,7 @@ Check for required fields and proper formatting: * [ ] Only one H1 heading (the title in frontmatter) * [ ] H2 sections used for main sections * [ ] No skipped heading levels (H2 → H4 without H3) -* [ ] Headings use Title Case +* [ ] Headings use sentence case (only first word and proper nouns capitalized) **Required sections (by doc type):** diff --git a/.claude/commands/review.md b/.claude/commands/review.md new file mode 100644 index 0000000000..4dff1db6f4 --- /dev/null +++ b/.claude/commands/review.md @@ -0,0 +1,115 @@ +# Review Pull Request — Documentation Quality Review + +Reviews all changed `.md` files in a pull request using the same checks as `/audit-doc`, then produces a single consolidated PR review comment. + +## Workflow + +### Step 1: Get the PR + +If a PR number or URL is provided, use it. Otherwise run `gh pr list` and ask the user which PR to review. + +Extract the PR number from URLs (e.g., `https://github.com/.../pull/6707` → `6707`). + +### Step 2: Fetch PR details and diff + +Run in parallel: +- `gh pr view --json title,body,author,headRefName,baseRefName,changedFiles` +- `gh pr diff ` + +### Step 3: Identify changed doc files + +From the diff, collect all files with a `.md` extension that were added or modified (ignore deletions). Skip non-doc files (`.ts`, `.json`, `.js`, `.yml`, etc.). + +If no `.md` files changed, report: "No documentation files changed in this PR." + +### Step 4: Determine doc type for each file + +Use the file path to infer the doc type: + +| Path pattern | Doc type | +|---|---| +| `blog-service/`, `blog-collector/`, `blog-cse/`, `blog-csoar/`, `blog-developer/` | Release note | +| `docs/integrations/` or `docs/platform-services/automation-service/app-central/` | App doc | +| `docs/send-data/hosted-collectors/cloud-to-cloud-integration-framework/` | C2C source doc | +| Everything else under `docs/` | Feature / how-to / concept / reference | + +If the type is ambiguous, read the file's frontmatter `tags` field or intro paragraph to confirm. + +### Step 5: Read each changed file + +Use the Read tool to fetch the full current content of each changed `.md` file (not just the diff lines — the full file is needed to check structure, frontmatter, and links in context). + +### Step 6: Apply audit-doc checks to each file + +Apply all checks from `/audit-doc` — frontmatter, structure, links, images, style guide, doc-type-specific requirements — using the same severity levels: + +- **Critical**: must fix before merging +- **Warning**: should fix +- **Suggestion**: nice to have + +See `/audit-doc` for the full checklist. Key things to flag in a PR review: + +- Missing or invalid frontmatter fields (`id`, `title`, `description`) +- Branding violations ("Sumo" instead of "Sumo Logic", wrong app/source opener) +- Wrong heading case (sentence case required — only first word and proper nouns capitalized) +- Missing required sections for the doc type +- Negative contractions (can't, won't, don't → cannot, will not, do not) +- "the user" or "users" instead of "you" +- Bare URLs, missing alt text, missing code block language tags +- Release note format violations (date format, `[New]`/`[Updated]` tags, rule ID patterns) + +Focus on issues introduced by this PR. If the file has pre-existing issues that weren't touched by the diff, note them briefly but do not block the PR over them. + +### Step 7: Produce the review + +Output a single consolidated review covering all changed files. Format: + +``` +## PR review: {PR title} + +{N} doc file(s) changed: {list of filenames} + +--- + +### {filename} +**Type**: {doc type} + +**Critical issues** (must fix): +- {issue with line reference if possible} + +**Warnings** (should fix): +- {issue} + +**Suggestions**: +- {issue} + +✅ No issues / ⚠️ {N} warnings / ❌ {N} critical + +--- + +### {next filename} +... + +--- + +## Overall + +{Pass | Pass with warnings | Needs work} + +{1-2 sentence summary of the most important things to address} +``` + +If a file has no issues: `✅ {filename} — looks good.` + +### Step 8: Offer next steps + +After the review, offer: +- "Run `/audit-doc {file}` to get a detailed report with line numbers and fix options" +- "Run `/seo-audit {file}` to check discoverability signals" + +## Constraints + +- **Read-only**. Do not edit any files. The purpose is to surface issues, not fix them. +- **Diff-aware**. Prioritize issues in lines added or modified by the PR. Flag pre-existing issues separately as "pre-existing" if needed. +- **Concise**. This is a PR review, not a full audit report. One line per issue where possible. +- **No duplication**. The checks live in `/audit-doc`. Do not re-list every rule here — apply them, don't describe them. diff --git a/CLAUDE.md b/CLAUDE.md index 4ab72c8ed7..70151007ef 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -84,7 +84,7 @@ When a user asks "what can I do", "what commands are available", or similar, sha | `/tone-check` | Check voice and tone against Sumo Logic style rules | | `/rewrite-intro` | Rewrite a doc's opening paragraph | | `/simplify` | Simplify overly complex content | -| `/review` | Review a pull request | +| `/review` | Review a pull request — applies audit-doc checks to all changed `.md` files | **Jira** From d3c78ac1f1f324882b7f069ca74087db8833d074 Mon Sep 17 00:00:00 2001 From: Kim Pohas Date: Wed, 20 May 2026 02:31:06 -0700 Subject: [PATCH 03/22] DOCS-1640: Delete tone-check, simplify, rewrite-intro commands Rules are covered by the sumo-style skill. Standalone commands were unlikely to be invoked and added clutter to the command list. Co-Authored-By: Claude Sonnet 4.6 --- .claude/commands/audit-doc.md | 1 - .claude/commands/rewrite-intro.md | 279 ----------------- .claude/commands/simplify.md | 358 ---------------------- .claude/commands/tone-check.md | 486 ------------------------------ CLAUDE.md | 3 - 5 files changed, 1127 deletions(-) delete mode 100644 .claude/commands/rewrite-intro.md delete mode 100644 .claude/commands/simplify.md delete mode 100644 .claude/commands/tone-check.md diff --git a/.claude/commands/audit-doc.md b/.claude/commands/audit-doc.md index 0400b1dee3..46312d92e4 100644 --- a/.claude/commands/audit-doc.md +++ b/.claude/commands/audit-doc.md @@ -359,4 +359,3 @@ check SEO/AEO/GEO signals. For discoverability, run both: * **`/seo-audit`** — checks title length, description quality, question headings, GEO patterns * **`/geo-optimize`** — rewrites content to improve AI citation and search visibility -* **`/tone-check`** — checks voice and tone against Sumo Logic style rules (standalone voice check) diff --git a/.claude/commands/rewrite-intro.md b/.claude/commands/rewrite-intro.md deleted file mode 100644 index e5b8f63425..0000000000 --- a/.claude/commands/rewrite-intro.md +++ /dev/null @@ -1,279 +0,0 @@ -# Rewrite Intro — Documentation Opening Paragraph Rewrite - -Rewrites the intro/opening paragraph of a documentation page to match Sumo Logic voice and tone standards. - -## Workflow - -### Step 1: Fetch Style Guide - -Before rewriting, always fetch the live style guide: -- https://www.sumologic.com/help/docs/contributing/style-guide/ -- https://www.sumologic.com/help/docs/contributing/word-list/ - -These contain the authoritative voice and tone rules. - -### Step 2: Get the File - -Ask the user which file to rewrite if not specified. Accept: -- **Full path**: `/Users/kpohas/sumologic-documentation/docs/integrations/amazon-aws/cloudtrail.md` -- **Relative path**: `docs/integrations/amazon-aws/cloudtrail.md` -- **Filename only**: `cloudtrail.md` (search for it) - -### Step 3: Analyze Current Intro - -Read the file and identify: - -1. **The introduction section** - - Usually first 1-3 paragraphs after frontmatter - - Before the first H2 heading - - May include multiple paragraphs - -2. **Document type** - - App doc (requires app opener) - - C2C source doc (requires source opener) - - Feature documentation - - Tutorial or guide - - Release note - -3. **Current issues** - - Voice and tone violations - - Branding compliance - - Reading level - - Clarity and conciseness - -### Step 4: Apply Rewrite Rules - -#### Branding Requirements - -**App docs MUST open with:** -```markdown -The Sumo Logic app for [Vendor] [what it does and why you'd use it]. -``` - -Examples: -- "The Sumo Logic app for AWS CloudTrail provides comprehensive visibility into AWS API activity and security events." -- "The Sumo Logic app for Salesforce helps you monitor user activity, track performance, and analyze security events." - -**C2C source docs MUST open with:** -```markdown -The Sumo Logic source for [Vendor] [what it does]. -``` - -Examples: -- "The Sumo Logic source for Okta collects authentication logs, system logs, and user activity events." -- "The Sumo Logic source for GitHub ingests repository events, pull request activity, and security alerts." - -#### Voice and Tone Principles - -**Address reader as "you":** -- ❌ "Users can configure the source" -- ✅ "You can configure the source" -- ❌ "One should consider performance" -- ✅ "You should consider performance" - -**Active voice:** -- ❌ "Data is collected by the Collector" -- ✅ "The Collector collects data" -- ❌ "Logs are parsed and indexed" -- ✅ "Sumo Logic parses and indexes logs" - -**Conversational but professional:** -- ❌ "This document delineates the methodology for configuration" -- ✅ "This guide explains how to configure the source" -- ❌ "Utilize the subsequent instructions" -- ✅ "Follow these steps" - -**8th-grade reading level:** -- Short sentences (under 20 words) -- Common words over technical jargon -- Simple sentence structure -- One idea per sentence - -**No "please" in directives:** -- ❌ "Please configure the source" -- ✅ "Configure the source" -- ❌ "Please refer to the documentation" -- ✅ "Learn more in the documentation" - -**Use "need to" not "must":** -- ❌ "You must configure authentication" -- ✅ "You need to configure authentication" - -**No filler adjectives:** -- ❌ "very important", "simply click", "just add", "easy to use", "straightforward process" -- ✅ Remove or rewrite without filler - -**Spell out negative contractions:** -- ❌ "can't", "won't", "don't", "isn't" -- ✅ "cannot", "will not", "do not", "is not" - -#### Introduction Structure - -Good intros typically follow this pattern: - -1. **What this is** (1-2 sentences) - - For apps: Branded opener + what it monitors - - For sources: Branded opener + what data it collects - - For features: What the feature does - -2. **Why you'd use it** (1-2 sentences) - - Key benefits - - Main use cases - - Problems it solves - -3. **What you'll learn** (1 sentence, optional for tutorials/guides) - - "This guide shows you how to..." - - "You'll learn to..." - -**Example - App doc intro:** -```markdown -The Sumo Logic app for AWS CloudTrail provides visibility into AWS account activity and API usage. The app includes dashboards that help you monitor user activity, detect security threats, and maintain compliance. This guide shows you how to install the app and configure data collection. -``` - -**Example - Source doc intro:** -```markdown -The Sumo Logic source for Okta collects authentication logs, system logs, and user activity events from your Okta organization. You can use this data to monitor login patterns, detect suspicious activity, and audit user permissions. This guide explains how to configure the source and verify data collection. -``` - -### Step 5: Present Rewrite - -Show the user: - -```markdown -## Current intro -[Show original text with line numbers] - -## Rewritten intro -[Show new text] - -## Changes made -- Fixed passive voice in sentence 2: "data is collected" → "the source collects data" -- Added proper app opener branding: "The Sumo Logic app for [Vendor]..." -- Removed filler words: "simply", "just", "easy" (3 instances) -- Spelled out "can't" → "cannot" -- Broke 42-word sentence into two shorter sentences -- Changed "users can" → "you can" (addressing reader directly) -- Simplified "utilize" → "use", "in order to" → "to" -- Reduced reading level from 11th grade to 8th grade -``` - -Be specific about what changed and why. - -### Step 6: Apply Changes - -After user approval: - -1. **Use Edit tool** to replace the intro section -2. **Preserve all other content**. only replace the intro paragraphs -3. **Maintain formatting**. keep existing markdown structure, images, code blocks -4. **Confirm success**. Let user know the changes were applied - -## Safety Guidelines - -- **NEVER modify files automatically**. always show the rewrite and get user approval first -- **Preserve existing content**. only replace the intro section, don't touch anything else -- **Maintain formatting**. keep existing markdown structure, line breaks, spacing -- **Don't change frontmatter**. unless specifically asked -- **Verify document type**. apply correct branding rules (app vs. source vs. feature) - -## Edge Cases - -### No intro exists -If the doc has no introduction: -- Offer to write one from scratch -- Use document type to determine opener format -- Ask user for key information (what it does, why use it) - -### Intro is already good -If intro already meets standards: -- Tell the user it's in good shape -- Suggest only minor tweaks if any -- Don't rewrite just for the sake of rewriting - -### Multiple intro paragraphs -If there are 3+ intro paragraphs: -- Ask user which paragraphs to include in rewrite scope -- Consider if all are needed (may be too long) -- Suggest condensing if appropriate - -### Different doc types -Apply appropriate rules: -- **App docs**: Must have app opener -- **Source docs**: Must have source opener -- **Feature docs**: No special opener, focus on clarity -- **Tutorials**: Include "what you'll learn" -- **Release notes**: Different format, may not need rewrite - -### Technical content -If intro contains necessary technical terms: -- Keep technical terms that are unavoidable -- Define acronyms on first use -- Simplify surrounding prose -- Don't sacrifice accuracy for simplicity - -## Examples - -### Example 1: App Doc - -**User:** `/rewrite-intro docs/integrations/amazon-aws/cloudtrail.md` - -**Original:** -``` -CloudTrail is utilized by organizations to monitor AWS API activity. The application can be used by users to gain visibility into account activity. Data is collected and visualized through various dashboards which are very helpful for security teams. -``` - -**Rewritten:** -``` -The Sumo Logic app for AWS CloudTrail provides visibility into AWS account activity and API usage. You can monitor user actions, detect security threats, and maintain compliance with pre-built dashboards and alerts. -``` - -**Changes:** -- Added proper app opener: "The Sumo Logic app for AWS CloudTrail" -- Changed passive voice: "Data is collected" → "You can monitor" -- Addressed reader as "you" instead of "users" -- Removed filler: "very helpful" -- Simplified: "utilized" → "provides", "gain visibility" → "monitor" -- Combined ideas into two focused sentences - -### Example 2: Source Doc - -**User:** `/rewrite-intro docs/send-data/hosted-collectors/cloud-to-cloud-integration-framework/okta-source.md` - -**Original:** -``` -This source integration is designed to collect logs from Okta. Users must configure the source properly. The logs that are collected can include authentication events and system logs. -``` - -**Rewritten:** -``` -The Sumo Logic source for Okta collects authentication logs, system logs, and user activity events from your Okta organization. You can use this data to monitor login patterns, detect suspicious activity, and audit user permissions. -``` - -**Changes:** -- Added proper source opener: "The Sumo Logic source for Okta" -- Removed passive voice: "logs that are collected" → "collects authentication logs" -- Changed "Users must" → "You can" -- Added value proposition (what you can do with the data) -- More specific about log types - -### Example 3: Feature Doc - -**User:** `/rewrite-intro docs/metrics/introduction.md` - -**Original:** -``` -Metrics are utilized within Sumo Logic to provide quantitative measurements of your infrastructure and applications. This functionality is very powerful and can be used by organizations to monitor performance. The system enables users to create visualizations. -``` - -**Rewritten:** -``` -Metrics provide quantitative measurements of your infrastructure and applications. You can track performance trends, set up alerts, and create visualizations to monitor system health in real time. -``` - -**Changes:** -- Removed passive voice: "are utilized" → "provide" -- Changed "users" → "You" -- Removed filler: "very powerful" -- Simplified: "This functionality" → direct statement -- Added specific use cases (track, alert, visualize) - diff --git a/.claude/commands/simplify.md b/.claude/commands/simplify.md deleted file mode 100644 index 7f978b80d1..0000000000 --- a/.claude/commands/simplify.md +++ /dev/null @@ -1,358 +0,0 @@ -# Simplify — Documentation Content Simplification - -Simplifies overly complex, verbose, or hard-to-understand documentation content to meet 8th-grade reading level standards. - -## Workflow - -### Step 1: Get Target Content - -Ask the user to specify what to simplify: - -**Option 1: Full file** -``` -/simplify docs/send-data/collect-from-other-sources/azure-monitoring.md -``` -Simplifies the entire document. - -**Option 2: Specific section** -``` -/simplify the Prerequisites section in docs/integrations/saas-cloud/salesforce.md -``` -Simplifies just that section. - -**Option 3: Line range** -``` -/simplify lines 45-78 in docs/metrics/introduction.md -``` -Simplifies specific lines. - -**Option 4: User provides text** -User pastes text directly for simplification. - -### Step 2: Analyze Complexity - -Check for these complexity indicators: - -#### Reading Level -- **Above 8th grade?** Needs simplification -- Use short words, simple sentences -- One idea per sentence - -**Tools to assess:** -- Long words (3+ syllables) -- Sentence length (words per sentence) -- Complex sentence structures - -#### Passive Voice -Passive voice makes content harder to read. - -❌ **Passive examples:** -- "Data is ingested by Sumo Logic" -- "The dashboard can be configured by users" -- "Logs are parsed and indexed" -- "Alerts are triggered when thresholds are exceeded" - -✅ **Active alternatives:** -- "Sumo Logic ingests data" -- "You can configure the dashboard" -- "Sumo Logic parses and indexes logs" -- "Sumo Logic triggers alerts when thresholds are exceeded" - -#### Long Sentences -Sentences over 20 words are hard to follow. - -❌ **Too long (42 words):** -"In order to configure the source properly, you need to navigate to the Cloud-to-Cloud Integration page in Sumo Logic, select the appropriate integration type from the dropdown menu, and then enter your authentication credentials in the fields provided." - -✅ **Broken up:** -"To configure the source, go to the Cloud-to-Cloud Integration page in Sumo Logic. Select your integration type from the dropdown menu. Enter your authentication credentials in the fields." - -#### Jargon and Technical Terms -Undefined jargon confuses readers. - -❌ **Undefined jargon:** -- "Instantiate a new collector" -- "Leverage the API endpoint" -- "Utilize the following methodology" - -✅ **Plain language:** -- "Create a new collector" -- "Use the API endpoint" -- "Follow these steps" - -**When technical terms are necessary:** -- Define acronyms on first use: "Application Load Balancer (ALB)" -- Provide context: "The collector (a lightweight agent that sends data)" -- Link to glossary if available - -#### Filler Words -Remove these unnecessary words: - -| Filler | Example | Better | -|--------|---------|--------| -| simply | simply click the button | click the button | -| just | just add the field | add the field | -| very | very important | important | -| easy | easy to configure | configure | -| straightforward | straightforward process | (remove or rewrite) | -| actually | actually sends data | sends data | -| basically | basically allows you | allows you | - -#### Nested Clauses -Multiple commas and dependent clauses make sentences hard to parse. - -❌ **Nested (hard to read):** -"The collector, which runs on your infrastructure, collects logs from various sources, including applications, servers, and network devices, and then sends them to Sumo Logic, where they are parsed and indexed." - -✅ **Simplified:** -"The collector runs on your infrastructure and collects logs from applications, servers, and network devices. It sends the logs to Sumo Logic for parsing and indexing." - -#### Redundancy -Common redundant phrases: - -| Replace | With | -|---------|------| -| in order to | to | -| due to the fact that | because | -| at this point in time | now | -| in the event that | if | -| prior to | before | -| subsequent to | after | -| a number of | several, many | -| is able to | can | -| in close proximity to | near | -| for the purpose of | to, for | -| has the ability to | can | -| at the present time | now | - -### Step 3: Apply Simplification Rules - -#### Sentence Structure Rules - -1. **Keep sentences under 20 words** - - Average 15-17 words per sentence - - Vary sentence length for readability - - One main idea per sentence - -2. **Use active voice** - - Subject performs the action - - More direct and clear - - Easier to understand - -3. **Start with the action or subject** - - Don't bury the main point - - Front-load important information - - Avoid long introductory clauses - -4. **Break up complex sentences** - - Multiple ideas → multiple sentences - - Dependent clauses → independent sentences - - Use periods instead of commas - -#### Word Choice Rules - -1. **Use common words** - - "use" not "utilize" - - "start" not "initiate" - - "end" not "terminate" - - "get" not "obtain" - -2. **Replace jargon** - - Technical terms → plain language when possible - - Define acronyms on first use - - Provide context for unfamiliar concepts - -3. **Remove filler adjectives** - - Delete: very, simply, just, easy, straightforward - - Only keep if adds meaning - -4. **Spell out contractions** - - Negative contractions: can't → cannot - - Keep common positive: you'll, they're, we're - -#### Paragraph Structure Rules - -1. **Keep paragraphs short** - - 3-5 sentences maximum - - One main point per paragraph - - Use white space for readability - -2. **Lead with the main point** - - Topic sentence first - - Supporting details after - - Don't bury the lead - -3. **Use bullets for lists** - - 3+ similar items → bullet list - - Easier to scan - - Better comprehension - -### Step 4: Simplification Examples - -#### Example 1: Passive Voice + Jargon - -**Original (Grade 12):** -``` -The data is ingested by the collector which then utilizes various parsing methodologies to transform the logs into a structured format that can be leveraged by the analytics engine. -``` - -**Simplified (Grade 8):** -``` -The collector ingests data and parses logs into a structured format. You can then use this data in the analytics engine. -``` - -**Changes:** -- Passive → active: "data is ingested" → "collector ingests" -- Removed jargon: "utilizes" → "parses", "leveraged" → "use" -- Split 31-word sentence into two shorter sentences (10 and 11 words) -- Added "you" to engage reader - -#### Example 2: Long Sentence + Nested Clauses - -**Original (Grade 13):** -``` -In order to configure the AWS CloudTrail source, which collects API activity logs from your AWS account, you need to first navigate to the Sumo Logic console, then select the Manage Data option from the left navigation menu, and finally click on Collection in order to access the configuration page where you can add a new source. -``` - -**Simplified (Grade 7):** -``` -To configure the AWS CloudTrail source, go to the Sumo Logic console. Select **Manage Data** from the left menu, then click **Collection**. This opens the configuration page where you can add the source. The source collects API activity logs from your AWS account. -``` - -**Changes:** -- Removed "in order to" → "To" (2 instances) -- Split 52-word sentence into 4 shorter sentences (9, 10, 11, 10 words) -- Removed nested clause, moved to separate sentence -- Added bold formatting for UI elements -- More direct instructions - -#### Example 3: Technical Jargon - -**Original (Grade 14):** -``` -The application leverages a sophisticated algorithm to instantiate correlations between disparate data points, thereby enabling users to ascertain patterns that would otherwise remain obfuscated within the raw log data. -``` - -**Simplified (Grade 8):** -``` -The app finds connections between different data points. This helps you spot patterns that are hard to see in raw logs. -``` - -**Changes:** -- "leverages" → "uses" (then simplified to implicit) -- "instantiate correlations" → "finds connections" -- "disparate" → "different" -- "ascertain patterns" → "spot patterns" -- "remain obfuscated" → "hard to see" -- Split into two short sentences (8 and 11 words) - -#### Example 4: Filler Words + Redundancy - -**Original (Grade 10):** -``` -Simply navigate to the configuration page and just enter your credentials. This is a very straightforward process that is actually quite easy to complete, due to the fact that the interface is basically self-explanatory. -``` - -**Simplified (Grade 6):** -``` -Go to the configuration page and enter your credentials. The interface is self-explanatory. -``` - -**Changes:** -- Removed fillers: "Simply", "just", "very", "actually quite", "basically" -- Removed redundancy: "due to the fact that" → (removed) -- "navigate to" → "Go to" -- Cut from 28 words to 13 words -- More direct and confident - -### Step 5: Present Simplified Version - -Show the user: - -```markdown -## Original -**Reading level:** 12th grade -**Average sentence length:** 28 words -**Passive voice:** 4 instances - -[Original text] - -## Simplified -**Reading level:** 8th grade -**Average sentence length:** 14 words -**Passive voice:** 0 instances - -[Simplified text] - -## Changes made -- Broke 3 long sentences (25+ words) into 7 shorter sentences -- Changed 4 passive voice constructions to active voice -- Removed jargon: "instantiate" → "create", "utilize" → "use", "leverage" → "use" -- Removed filler words: "simply", "very", "just" (5 instances) -- Defined acronym: ALB (Application Load Balancer) -- Removed redundancy: "in order to" → "to" (3 instances) -- Split complex paragraph into two focused paragraphs -- Reduced word count from 247 to 178 words (28% reduction) -``` - -### Step 6: Apply Changes - -After user approval: - -1. **Use Edit tool** to replace the content -2. **Preserve structure**. keep headings, lists, code blocks unchanged -3. **Maintain formatting**. line breaks, markdown syntax -4. **Confirm success** - -## Safety Guidelines - -- **NEVER modify automatically**. always show simplified version first and get approval -- **Preserve technical accuracy**. don't oversimplify to the point of incorrectness -- **Keep code unchanged**. only simplify prose, not code snippets or examples -- **Maintain original meaning**. clarify, don't change intent or facts -- **Don't remove necessary technical terms**. if a term is required, define it instead - -## What NOT to Simplify - -1. **Code snippets or examples**. Leave code as-is -2. **API endpoint names**. Don't change technical identifiers -3. **Product names**. Proper nouns stay the same -4. **Quotes or references**. Don't modify quoted content -5. **Already-simple content**. If it's 8th grade or below, leave it -6. **URLs or file paths**. Technical paths must stay exact -7. **Version numbers**. Don't change technical specifications - -## Edge Cases - -### Already simple content -If content already meets readability standards: -``` -This content already meets the 8th-grade reading level standard. The average sentence length is 15 words, and there's no passive voice or excessive jargon. No simplification needed. -``` - -### Highly technical content -If content must stay technical: -- Simplify the surrounding explanation -- Define technical terms clearly -- Add examples or analogies -- Don't sacrifice accuracy - -Example: -``` -Before: "The OAuth 2.0 authorization framework leverages bearer tokens." -After: "The OAuth 2.0 authorization framework uses bearer tokens (credentials that grant access without additional verification)." -``` - -### Lists and tables -Focus on descriptive text, not list items: -- Simplify list introductions -- Clarify bullet descriptions -- Don't change list structure - -### Short content (1-2 sentences) -May already be optimal: -- Check reading level -- Fix passive voice if present -- Remove filler only -- Don't over-engineer - diff --git a/.claude/commands/tone-check.md b/.claude/commands/tone-check.md deleted file mode 100644 index 97715675ea..0000000000 --- a/.claude/commands/tone-check.md +++ /dev/null @@ -1,486 +0,0 @@ -# Tone Check — Sumo Logic Voice and Tone Validation - -Validates documentation against Sumo Logic voice and tone rules, identifying violations and suggesting fixes. - -## Workflow - -### Step 1: Fetch Style Guide - -Always fetch before analyzing: -- https://www.sumologic.com/help/docs/contributing/style-guide/ -- https://www.sumologic.com/help/docs/contributing/word-list/ - -These are the authoritative sources for voice and tone rules. - -### Step 2: Get the File - -Ask user which file to check if not specified: -- **Full path**: `/Users/kpohas/sumologic-documentation/docs/integrations/amazon-aws/cloudtrail.md` -- **Relative path**: `docs/integrations/amazon-aws/cloudtrail.md` -- **Filename**: `cloudtrail.md` (search for it) - -### Step 3: Analyze Voice and Tone - -Check for specific violations in order of severity: - -## Critical Issues (Must Fix) - -These MUST be fixed before merging. - -### Wrong Pronouns - -❌ **Violations:** -- "the user can configure" -- "users should navigate" -- "one can access" -- "customers will receive" - -✅ **Correct:** -- "you can configure" -- "you should navigate" or "Navigate" -- "you can access" -- "you'll receive" - -**Why it matters:** Directly addressing the reader as "you" is conversational and engaging. Third-person references ("the user", "one") create distance and feel institutional. - -### Negative Contractions - -❌ **Violations:** -- can't → **cannot** -- won't → **will not** -- don't → **do not** -- isn't → **is not** -- aren't → **are not** -- wasn't → **was not** -- weren't → **were not** -- hasn't → **has not** -- haven't → **have not** -- didn't → **did not** -- doesn't → **does not** -- shouldn't → **should not** -- wouldn't → **would not** -- couldn't → **could not** - -✅ **Correct:** Always spell out negative contractions - -**Why it matters:** This is a firm Sumo Logic style rule. Negative contractions must always be spelled out, even in conversational tone. - -**Positive contractions are OK:** -- you'll, they're, we're, it's, you've, we've - -### Incorrect Branding - -❌ **Violations:** -- "Sumo" (in prose, not code) -- App doc without proper opener -- Source doc without proper opener - -✅ **Correct:** -- "Sumo Logic" or "we" -- App docs: "The Sumo Logic app for [Vendor]..." -- Source docs: "The Sumo Logic source for [Vendor]..." - -**Why it matters:** Consistent branding and proper document openers establish authority and professionalism. - -## Warnings (Should Fix) - -These should be fixed but won't block merging. - -### Passive Voice - -Passive voice is wordy and less direct. - -❌ **Passive examples:** -- "Data is ingested by Sumo Logic" -- "The dashboard can be configured by users" -- "Logs are parsed and indexed" -- "Alerts are triggered when thresholds are exceeded" -- "The source can be set up in minutes" - -✅ **Active alternatives:** -- "Sumo Logic ingests data" -- "You can configure the dashboard" -- "Sumo Logic parses and indexes logs" -- "Sumo Logic triggers alerts when thresholds are exceeded" -- "You can set up the source in minutes" - -**How to identify:** -- Look for "is/are/was/were + past participle" -- Look for "by [actor]" phrases -- Ask: "Who/what is doing the action?" - -**When passive is OK:** -- When the actor is unknown or unimportant -- In technical specifications -- In rare cases for emphasis - -### "Please" in Directives - -Don't use "please" in task instructions. - -❌ **Violations:** -- "Please configure the source" -- "Please click **Save**" -- "Please refer to the documentation" -- "Please note that..." - -✅ **Correct:** -- "Configure the source" -- "Click **Save**" -- "Learn more in the documentation" or "See [link]" -- "Note that..." or just state the fact - -**Why it matters:** Instructional directives should be clear and confident, not apologetic. "Please" makes them sound tentative. - -### "Must" Instead of "Need To" - -Prefer "need to" over "must" for a friendlier tone. - -❌ **Violations:** -- "You must configure authentication" -- "Users must have admin access" -- "You must restart the service" - -✅ **Correct:** -- "You need to configure authentication" -- "You need admin access" -- "You need to restart the service" - -**Exception:** "Must" is OK for hard requirements in technical specifications or legal compliance. - -### Filler Adjectives - -Remove words that add no meaning. - -❌ **Common fillers:** -- **very** (very important, very useful) -- **simply** (simply click, simply add) -- **just** (just navigate, just enter) -- **easy** (easy to use, easy to configure) -- **straightforward** (straightforward process) -- **quickly** (quickly set up) — unless specific time is meant -- **easily** (easily configure) -- **basic** (basic setup) — unless contrasting with advanced - -✅ **Correct:** -- "important" (not "very important") -- "click" (not "simply click") -- "navigate" (not "just navigate") -- "configure" (not "easy to configure") -- Remove or rewrite without filler - -**Why it matters:** Filler words dilute meaning and make content less confident. They often telegraph that something is harder than claimed. - -## Suggestions (Nice to Have) - -These improve quality but are lower priority. - -### Overly Formal Language - -Replace stiff, institutional language with conversational alternatives. - -❌ **Formal:** -- utilize → **use** -- in order to → **to** -- due to the fact that → **because** -- at this point in time → **now** -- in the event that → **if** -- prior to → **before** -- subsequent to → **after** -- commence → **start, begin** -- terminate → **end, stop** -- ascertain → **find out, determine** -- facilitate → **help, enable** -- leverage → **use** - -✅ **Conversational:** Use simpler alternatives - -### Uncommon Contractions - -Avoid contractions that sound awkward when read aloud. - -❌ **Uncommon:** -- should've -- it'll -- they'd -- you'd -- there'd - -✅ **Alternatives:** -- "should have" or rewrite -- "it will" or rewrite -- "they would" or rewrite -- "you would" or rewrite -- "there would" or rewrite - -**Common contractions are OK:** -- you'll, they're, we're, it's, you've, we've, that's, here's - -### Regional Idioms - -Avoid phrases that may not translate well. - -❌ **Regional idioms:** -- "hit the ground running" -- "low-hanging fruit" -- "ballpark figure" -- "touch base" -- "circle back" -- "boil the ocean" - -✅ **Clear alternatives:** -- "start quickly" -- "quick wins" or "easy improvements" -- "rough estimate" -- "check in" or "follow up" -- "revisit this" -- "attempt too much" - -### Step 4: Generate Report - -Format the report with severity levels: - -```markdown -# Tone Check Report -**File**: docs/integrations/amazon-aws/cloudtrail.md -**Date**: March 23, 2026 -**Status**: ⚠️ 12 issues found - -## Summary -- 3 Critical issues (must fix) -- 6 Warnings (should fix) -- 3 Suggestions (nice to have) - ---- - -## Critical Issues (Must Fix) - -### Wrong Pronouns (2 instances) - -**Line 45:** -``` -the user can configure the source -``` -→ Should be: `you can configure the source` - -**Line 67:** -``` -Users should navigate to the Collection page -``` -→ Should be: `You should navigate to the Collection page` or `Navigate to the Collection page` - ---- - -### Negative Contractions (1 instance) - -**Line 89:** -``` -The field can't be modified after creation -``` -→ Should be: `The field cannot be modified after creation` - ---- - -## Warnings (Should Fix) - -### Passive Voice (4 instances) - -**Line 23:** -``` -Data is collected by the Collector -``` -→ Should be: `The Collector collects data` - -**Line 34:** -``` -Logs are parsed and indexed by Sumo Logic -``` -→ Should be: `Sumo Logic parses and indexes logs` - -**Line 56:** -``` -The dashboard can be customized by users -``` -→ Should be: `You can customize the dashboard` - -**Line 78:** -``` -Alerts are triggered when thresholds are exceeded -``` -→ Should be: `Sumo Logic triggers alerts when thresholds are exceeded` - ---- - -### "Please" in Directives (2 instances) - -**Line 12:** -``` -Please click **Save** to apply changes. -``` -→ Should be: `Click **Save** to apply changes.` - -**Line 91:** -``` -Please refer to the troubleshooting guide for help. -``` -→ Should be: `See the troubleshooting guide for help.` or `Learn more in the troubleshooting guide.` - ---- - -## Suggestions (Nice to Have) - -### Filler Words (3 instances) - -**Line 15:** -``` -Simply click the **Add** button to begin. -``` -→ Should be: `Click the **Add** button to begin.` - -**Line 42:** -``` -This feature is very important for security. -``` -→ Should be: `This feature is important for security.` - -**Line 73:** -``` -The source is easy to configure in just a few steps. -``` -→ Should be: `Configure the source in a few steps.` or `You can configure the source in a few steps.` - ---- - -## Next Steps - -Would you like me to: -1. **Auto-fix all issues**. Apply all corrections automatically -2. **Fix critical issues only**. Just fix the must-have items -3. **Show specific fixes**. Let me walk through each fix -4. **Generate checklist**. Create a manual review checklist -5. **Export report**. Save this report as a markdown file -``` - -### Step 5: Offer Fixes - -After presenting the report, ask what the user wants to do: - -**Option 1: Auto-fix all** -- Apply all corrections using Edit tool -- Show summary of changes made -- Re-run tone check to verify - -**Option 2: Fix by severity** -- Critical only -- Critical + warnings -- Custom selection - -**Option 3: Manual review** -- User fixes themselves -- Provide checklist -- Available for questions - -## Safety Guidelines - -- **NEVER modify automatically without asking**. always present report first -- **Provide context**. explain WHY something violates tone rules, not just WHAT -- **Show specific fixes**. don't just flag issues, suggest corrections with line numbers -- **Preserve technical accuracy**. tone fixes should not change meaning -- **Respect user decisions**. if they decline a fix, respect that choice - -## What NOT to Flag - -1. **Code blocks**. Don't check voice/tone in code snippets -2. **Quoted content**. Don't flag violations in quotations -3. **Product names**. Don't flag "Sumo" in product names like "Sumo App" -4. **URLs and paths**. Don't check tone in technical identifiers -5. **Examples of wrong usage**. Don't flag intentionally incorrect examples -6. **Comments or notes**. May use different tone - -## Edge Cases - -### No Issues Found - -If content passes all checks: -```markdown -# Tone Check Report -**File**: docs/integrations/amazon-aws/cloudtrail.md -**Status**: ✅ All checks passed - -This document meets all Sumo Logic voice and tone standards: -- No pronoun violations -- No negative contractions -- No passive voice -- No "please" in directives -- No filler words -- Proper branding - -Great work! -``` - -### Too Many Issues - -If there are 20+ violations: -```markdown -# Tone Check Report -**Status**: ⚠️ 47 issues found - -This document has significant voice and tone issues. I recommend: - -1. Start with critical issues (12 found) -2. Review patterns (passive voice appears 23 times) -3. Consider rewriting sections instead of fixing individually -4. Use /rewrite-intro for the opening -5. Use /simplify for complex sections - -Would you like me to: -- Fix all critical issues first? -- Rewrite the most problematic sections? -- Provide a training overview of the main issues? -``` - -### Mixed Content Types - -Different sections may have different standards: -- **Prose**: Apply all voice/tone rules -- **Code**: Skip tone checks -- **Examples**: Check explanatory text, not examples themselves -- **Quotes**: Don't check quoted content -- **Technical specs**: More lenient on passive voice - -### Document-Specific Exceptions - -Some documents may have valid exceptions: -- **API reference**: May use passive voice for specifications -- **Release notes**: May use past tense and passive voice -- **Legal/compliance**: May need formal language -- **Migration guides**: May reference "users" when describing old vs. new behavior - -Flag these as suggestions, not critical issues. - -## Common Patterns - -### Serial Offenders - -**Passive voice throughout:** -``` -Recommend: "I found 15 instances of passive voice. Would you like me to convert them all to active voice?" -``` - -**Wrong pronouns everywhere:** -``` -Recommend: "The document consistently uses 'users' instead of 'you'. Let me update all 12 instances." -``` - -**Filler word addiction:** -``` -Recommend: "'Simply' appears 8 times and 'just' appears 11 times. These can all be removed." -``` - -### One-Off Violations - -For 1-2 violations, just fix them: -``` -"Found one negative contraction on line 45. Should I fix it?" -``` - diff --git a/CLAUDE.md b/CLAUDE.md index 70151007ef..57c21a2d7d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -81,9 +81,6 @@ When a user asks "what can I do", "what commands are available", or similar, sha | `/audit-doc` | Full quality audit: structure, style, links, frontmatter, completeness | | `/seo-audit` | Discoverability audit: SEO, AEO, and GEO signals — run this before a PR | | `/geo-optimize` | Rewrite a doc to improve AI citation and generative engine visibility | -| `/tone-check` | Check voice and tone against Sumo Logic style rules | -| `/rewrite-intro` | Rewrite a doc's opening paragraph | -| `/simplify` | Simplify overly complex content | | `/review` | Review a pull request — applies audit-doc checks to all changed `.md` files | **Jira** From afa776c018da6289f053dbd6814f8497459cd8ed Mon Sep 17 00:00:00 2001 From: Kim Pohas Date: Fri, 5 Jun 2026 00:26:21 -0700 Subject: [PATCH 04/22] revert release notes --- .claude/commands/release-note-collector.md | 102 ++++++ .claude/commands/release-note-cse.md | 111 +++++++ .claude/commands/release-note-csoar.md | 131 ++++++++ .claude/commands/release-note-developer.md | 63 ++++ .claude/commands/release-note-service.md | 57 ++++ .claude/commands/release-note.md | 369 --------------------- CLAUDE.md | 6 +- 7 files changed, 469 insertions(+), 370 deletions(-) create mode 100644 .claude/commands/release-note-collector.md create mode 100644 .claude/commands/release-note-cse.md create mode 100644 .claude/commands/release-note-csoar.md create mode 100644 .claude/commands/release-note-developer.md create mode 100644 .claude/commands/release-note-service.md delete mode 100644 .claude/commands/release-note.md diff --git a/.claude/commands/release-note-collector.md b/.claude/commands/release-note-collector.md new file mode 100644 index 0000000000..9e6474d99d --- /dev/null +++ b/.claude/commands/release-note-collector.md @@ -0,0 +1,102 @@ +# Create New Collector Release Note + +Creates a Collector release note — either an Installed Collector version release or an OpenTelemetry Collector feature announcement. + +## Workflow + +### Step 1: Determine release type + +Ask the user: **Installed Collector** (version release with security/bug fixes) or **OpenTelemetry Collector** (feature announcement)? + +### Step 2: Gather information + +**For Installed Collector:** +- Version number (X.Y.Z-N format, e.g. 19.535-6) +- Release date (YYYY-MM-DD) +- List of security fixes, bug fixes, and/or features + +**For OpenTelemetry Collector:** +- Feature name +- Release date (YYYY-MM-DD) +- Description (focus on user benefit, 2–3 sentences) +- Doc link (relative path) + +### Step 3: Create the file + +**File**: `blog-collector/YYYY-MM-DD-{type}.md` — type is `-installed` or `-otel` + +If a file already exists for the same date and type, ask the user to use a different date or append. + +--- + +#### Installed Collector + +**Frontmatter**: +```yaml +--- +title: Installed Collector Version {X.Y.Z-N} +image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 +hide_table_of_contents: true +keywords: + - installed-collector +--- +``` + +**Content**: +```markdown +In this release, we've enhanced the security and stability of the Collector with added support for {security patches/bug fixes/features}. + +#### Security fix + +* Upgraded `{package}` to version **{version}** to address known security vulnerability ({CVE-YYYY-NNNNN}). + +#### Bug fix + +* {Bug fix description}. +``` + +- Sections use H4 (`####`). Order: Security fix → Bug fix → Feature. +- Package names in backticks, version numbers in **bold**. +- Include CVE/GHSA references where applicable (CVE-YYYY-NNNNN or GHSA-XXXX-XXXX-XXXX). +- Keywords are always `installed-collector` — no confirmation needed. + +--- + +#### OpenTelemetry Collector + +**Frontmatter**: +```yaml +--- +title: {Feature Name} +image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 +hide_table_of_contents: true +keywords: + - opentelemetry-collector +--- +``` + +**Content**: +```markdown +import useBaseUrl from '@docusaurus/useBaseUrl'; + +We're excited to announce {feature description}. {Benefits}. [Learn more](/docs/path/to/doc). +``` + +- Start with "We're excited to announce..." or "We're excited to introduce..." +- Keywords are always `opentelemetry-collector` — no confirmation needed. +- Use admonitions for important notes or breaking changes. + +### Step 4: Validate + +**Installed Collector:** +- [ ] `blog-collector/YYYY-MM-DD-installed.md` +- [ ] Title: "Installed Collector Version X.Y.Z-N" +- [ ] H4 sections in correct order (Security → Bug → Feature) +- [ ] Versions in **bold**, packages in backticks +- [ ] CVE/GHSA references where applicable + +**OpenTelemetry Collector:** +- [ ] `blog-collector/YYYY-MM-DD-otel.md` +- [ ] Starts with "We're excited to..." +- [ ] "Learn more" link with relative path +- [ ] Keywords: `opentelemetry-collector` diff --git a/.claude/commands/release-note-cse.md b/.claude/commands/release-note-cse.md new file mode 100644 index 0000000000..bbb7238631 --- /dev/null +++ b/.claude/commands/release-note-cse.md @@ -0,0 +1,111 @@ +# Create New Cloud SIEM Release Note + +Creates a Cloud SIEM (CSE) release note — either a content release (rules, log mappers, parsers) or an application release (features, bug fixes, UI updates). + +## Workflow + +### Step 1: Determine release type + +Ask the user: **Content release** (rules, log mappers, parsers — typically bi-weekly) or **Application release** (new features, bug fixes, UI improvements)? + +### Step 2: Gather information + +**For content releases:** +- Release date (YYYY-MM-DD) +- New/updated rules (IDs and names) — do not invent rule IDs, ask the user +- New/updated log mappers +- New/updated parsers +- 3–5 high-level summary points +- Keywords (confirm with user; default: rules, log mappers, parsers) + +**For application releases:** +- Release date (YYYY-MM-DD) +- Features with descriptions and doc links +- Keywords (confirm with user) + +### Step 3: Create the file + +**File**: `blog-cse/YYYY-MM-DD-{type}.md` — type is `-content` or `-application` + +Always include `import useBaseUrl from '@docusaurus/useBaseUrl';` after frontmatter. + +If a file already exists for the same date and type, ask the user to use a different date or append. + +--- + +#### Content release + +**Frontmatter**: +```yaml +--- +title: {Month} {Day ordinal}, {Year} - Content Release +hide_table_of_contents: true +keywords: + - rules + - log mappers + - parsers +image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 +--- +``` + +Title uses ordinal suffix: "March 19th, 2026 - Content Release", "February 3rd, 2026 - Content Release". Full month name, not abbreviated. + +**Content**: +```markdown +This content release includes: + - {Summary point 1} + - {Summary point 2} + +Additional changes are enumerated below. + +### Rules +* [New] MATCH-SXXXX Rule Name. +* [Updated] FIRST-SXXXX Rule Name. Brief description of what changed. + +### Log Mappers +* [New] Vendor - Event Type. + +### Parsers +* [Updated] /Parsers/System/Vendor/Parser Name. +``` + +- Summary bullets use 4-space indentation. +- `[New]` or `[Updated]` tag on every item. +- Rule ID formats: `MATCH-SXXXX`, `FIRST-SXXXX`, `THRESHOLD-SXXXX`, `AGGREGATION-SXXXX`, `CHAIN-SXXXX`, `OUTLIER-SXXXX` +- Parser paths use full hierarchy: `/Parsers/System/Vendor/Name` +- Log mapper format: `Vendor - Event Type` +- Sort alphabetically within each section. + +--- + +#### Application release + +**Frontmatter**: +```yaml +--- +title: {Month} {Day}, {Year} - Application Update +image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 +keywords: + - {keyword} +hide_table_of_contents: true +--- +``` + +**Content**: +```markdown +### {Feature Name} + +{Description and business value}. [Learn more](/docs/path/to/docs). +``` + +H3 for each feature. Add screenshots with `description` for UI changes. + +### Step 4: Validate + +- [ ] `blog-cse/YYYY-MM-DD-{type}.md` +- [ ] Title uses ordinal suffix for content releases +- [ ] `import useBaseUrl` included +- [ ] `hide_table_of_contents: true` +- [ ] Content: `[New]`/`[Updated]` tags on all items; parser paths complete +- [ ] Keywords confirmed with user +- [ ] No trailing whitespace diff --git a/.claude/commands/release-note-csoar.md b/.claude/commands/release-note-csoar.md new file mode 100644 index 0000000000..9c0ff2bc39 --- /dev/null +++ b/.claude/commands/release-note-csoar.md @@ -0,0 +1,131 @@ +# Create New Cloud SOAR Release Note + +Creates a Cloud SOAR (Automation Service) release note — either a content release (new integrations and playbooks) or an application update (platform features, enhancements, bug fixes). + +## Workflow + +### Step 1: Determine release type + +Ask the user: **Content release** (new/updated integrations and playbooks) or **Application update** (platform features, enhancements, bug fixes — published early the following month)? + +### Step 2: Gather information + +**For content releases:** +- Publication date (YYYY-MM-DD) +- New/updated integrations (names and doc links) +- New playbooks (ID numbers and titles) +- Keywords (confirm with user; default: automation service, cloud soar, soar) + +**For application updates:** +- Publication date (YYYY-MM-DD) — typically early the month following the release month +- Release month (e.g. "February" if published in March) +- Integration changes with descriptions +- Platform changes +- Bug fixes +- Keywords (confirm with user; default: automation service, cloud soar) + +### Step 3: Create the file + +**File**: +- Content release: `blog-csoar/YYYY-MM-DD-content-release.md` +- Application update: `blog-csoar/YYYY-MM-DD-application-update.md` + +Always include `import useBaseUrl from '@docusaurus/useBaseUrl';` after frontmatter. + +**Date format in title**: "Month DD, YYYY" — full month name, zero-padded day, no ordinal. +- ✅ "March 06, 2026" | ❌ "March 6, 2026" | ❌ "March 6th, 2026" + +**Integration doc path**: `/docs/platform-services/automation-service/app-central/integrations/{slug}/` + +If a file already exists, ask the user to use a different date or append. + +--- + +#### Content release + +**Frontmatter**: +```yaml +--- +title: {Month DD, 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: + - automation service + - cloud soar + - soar +--- +``` + +**Content**: +```markdown +This release introduces {what's new}. + +### Integrations + +* [New] [Integration Name](/docs/platform-services/automation-service/app-central/integrations/{slug}/) +* [Updated] [Integration Name](/docs/platform-services/automation-service/app-central/integrations/{slug}/) + +### Playbooks + +* [New] {ID} - {Playbook Title} +``` + +Integration entries are link-only — no descriptions. Playbooks section is optional. + +--- + +#### Application update + +Application Updates cover the previous month's changes. Filename and title use the publication date; the H2 header and intro use the release month. + +**Frontmatter**: +```yaml +--- +title: {Month DD, 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: + - automation service + - cloud soar +--- +``` + +**Content**: +```markdown +## {Release month} release + +Following are the updates made in {Month} {YYYY}. + +### Changes and enhancements + +#### Integrations + +* [Added] [Integration Name](/docs/path/) - Description of what was added. +* [Updated] [Integration Name](/docs/path/) - Description of what was updated. + +#### Platform + +* Platform enhancement description. + +### Bug Fixes + +#### Integrations + +* In the [Integration Name](/docs/path/) integration, description of fix. + +#### Platform + +Fixed an issue where {description}. +``` + +Integration changes use `[Added]` for new integrations, `[Updated]` for existing — always include descriptions (unlike content releases). + +### Step 4: Validate + +- [ ] Filename uses full suffix (`-content-release.md` or `-application-update.md`) +- [ ] Title: "Month DD, YYYY" format (zero-padded, no ordinal) +- [ ] `import useBaseUrl` included +- [ ] `hide_table_of_contents: true` +- [ ] Keywords confirmed with user +- [ ] Application update: H2 header uses release month, not publication month +- [ ] No trailing whitespace diff --git a/.claude/commands/release-note-developer.md b/.claude/commands/release-note-developer.md new file mode 100644 index 0000000000..50913bc53f --- /dev/null +++ b/.claude/commands/release-note-developer.md @@ -0,0 +1,63 @@ +# Create New Developer Release Note + +Creates a Developer release note for API changes, SDK updates, deprecations, CLI updates, or other developer-facing platform changes. + +## Workflow + +### Step 1: Gather information + +Ask the user for: +- **Title/topic**: brief description (e.g. "New Field Extraction Rules API", "Deprecation of India Data Center") +- **Release date**: YYYY-MM-DD format +- **Content**: what changed, why it matters, impact on existing users +- **Doc links**: relative paths to relevant docs +- **Keywords**: optional; ask the user — suggest based on content type: + - API changes: `api`, `endpoints` + - SDK updates: `sdk`, `python`, `java`, etc. + - Deprecations: `deprecation`, `end-of-life` + - Breaking changes: `breaking-change` + +### Step 2: Create the file + +**File**: `blog-developer/YYYY-MM-DD-{slug}.md` + +Slug: lowercase, hyphens, 3–5 words. Examples: `api-endpoints`, `india-datacenter-deprecation`, `python-sdk-v2`. + +If a file already exists, ask the user to use a different date or a more specific slug. + +**Frontmatter**: +```yaml +--- +title: {Month Day, YYYY} - {Topic} +image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 +hide_table_of_contents: true +--- +``` + +**Title format**: "Month Day, YYYY - Topic" — full month name, no ordinal. +- ✅ "April 9, 2025" | ❌ "April 9th, 2025" | ❌ "Apr 9, 2025" + +Add `keywords` to frontmatter only if the user wants them. + +**Content**: +```markdown +{Main paragraph — what changed, why it matters} + +#### {Subsection if needed} + +* {Item} +``` + +- H4 (`####`) for subsections (new endpoints, breaking changes, migration steps, etc.). +- Use `:::warning` admonitions for breaking changes. +- Doc links always use relative paths (`/docs/...`). +- Only add `import useBaseUrl` if content uses images. + +### Step 3: Validate + +- [ ] `blog-developer/YYYY-MM-DD-{slug}.md` +- [ ] Title: "Month Day, YYYY - Topic" (no ordinal) +- [ ] `hide_table_of_contents: true` +- [ ] Breaking changes clearly marked +- [ ] Doc links use relative paths +- [ ] No trailing whitespace diff --git a/.claude/commands/release-note-service.md b/.claude/commands/release-note-service.md new file mode 100644 index 0000000000..09ca45aff9 --- /dev/null +++ b/.claude/commands/release-note-service.md @@ -0,0 +1,57 @@ +# Create New Service Release Note + +Creates a Service release note for a new feature, update, or improvement across Sumo Logic platform categories. + +## Workflow + +### Step 1: Gather information + +Ask the user for: +- **Category**: apps, collection, manage, search, or ui +- **Feature name**: brief, descriptive name +- **Release date**: YYYY-MM-DD format +- **Description**: 2–3 sentences — what the feature is and why it matters +- **Doc link**: relative path (optional) +- **"What's new" bullets**: optional, for multiple specific changes +- **Keywords**: confirm with user before creating file + +### Step 2: Create the file + +**File**: `blog-service/YYYY-MM-DD-{category}.md` + +If a file already exists for the same date and category, ask the user to use a different date, append to the existing file, or add a more specific suffix. + +**Frontmatter**: +```yaml +--- +title: {Feature Description} ({Category Label}) +image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 +keywords: + - {keyword1} +hide_table_of_contents: true +--- +``` + +**Title**: Feature description in Title Case + category label in parentheses. No date in title. +- apps → (Apps) | collection → (Collection) | manage → (Manage) | search → (Search) | ui → (New UI) + +**Content**: +```markdown +{Description — what the feature is and why it matters} + +**What's new:** +* {Specific capability} + +[Learn more](/docs/path/to/doc). +``` + +"What's new:" is optional — use for multiple specific changes, omit for single-point announcements. Only add `import useBaseUrl` if the content uses it. + +### Step 3: Validate + +- [ ] `blog-service/YYYY-MM-DD-{category}.md` +- [ ] Title: feature description + category label in parens, no date +- [ ] `hide_table_of_contents: true` +- [ ] Keywords confirmed with user +- [ ] Doc link uses `/docs/...` relative path +- [ ] No trailing whitespace diff --git a/.claude/commands/release-note.md b/.claude/commands/release-note.md deleted file mode 100644 index 1d819cb272..0000000000 --- a/.claude/commands/release-note.md +++ /dev/null @@ -1,369 +0,0 @@ -# Release Note - -Creates release notes for Sumo Logic products. Ask the user which type before proceeding. - -## Types - -| Type | Blog dir | File pattern | -|---|---|---| -| **Service** | `blog-service/` | `YYYY-MM-DD-{category}.md` | -| **Collector** | `blog-collector/` | `YYYY-MM-DD-{type}.md` | -| **Cloud SIEM** | `blog-cse/` | `YYYY-MM-DD-{type}.md` | -| **Cloud SOAR** | `blog-csoar/` | `YYYY-MM-DD-{subtype}.md` | -| **Developer** | `blog-developer/` | `YYYY-MM-DD-{slug}.md` | - -Ask the user which type, then follow the appropriate section below. - -**Shared frontmatter values (all types):** -- `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` - -If a file already exists for the same date and type, ask the user to use a different date, append to the existing file, or add a more specific suffix. - ---- - -## Service (`blog-service/`) - -**Subtypes**: apps, collection, manage, search, ui - -**Gather**: category, feature name, release date, description (2–3 sentences), doc link (optional), "What's new" bullets (optional), keywords (confirm with user before creating file). - -**File**: `blog-service/YYYY-MM-DD-{category}.md` - -**Frontmatter**: -```yaml ---- -title: {Feature Description} ({Category Label}) -image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 -keywords: - - {keyword1} -hide_table_of_contents: true ---- -``` - -**Title**: Feature description in Title Case + category label in parentheses. No date in title. -- apps → (Apps) | collection → (Collection) | manage → (Manage) | search → (Search) | ui → (New UI) - -**Content**: -```markdown -{Description — what the feature is and why it matters} - -**What's new:** -* {Specific capability} - -[Learn more](/docs/path/to/doc). -``` - -"What's new:" is optional — use for multiple specific changes, omit for single-point announcements. Only add `import useBaseUrl` if the content uses it. - -**Validation**: -- [ ] `blog-service/YYYY-MM-DD-{category}.md` -- [ ] Title: feature description + category label in parens, no date -- [ ] `hide_table_of_contents: true` -- [ ] Keywords confirmed with user -- [ ] Doc link uses `/docs/...` relative path - ---- - -## Collector (`blog-collector/`) - -**File**: `blog-collector/YYYY-MM-DD-{type}.md` (`-installed` or `-otel`) - -### Installed Collector - -**Gather**: version number (X.Y.Z-N), release date, list of security fixes / bug fixes / features. - -**Frontmatter**: -```yaml ---- -title: Installed Collector Version {X.Y.Z-N} -image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 -hide_table_of_contents: true -keywords: - - installed-collector ---- -``` - -**Content**: -```markdown -In this release, we've enhanced the security and stability of the Collector with added support for {security patches/bug fixes/features}. - -#### Security fix - -* Upgraded `{package}` to version **{version}** to address known security vulnerability ({CVE-YYYY-NNNNN}). - -#### Bug fix - -* {Bug fix description}. -``` - -- Sections use H4 (`####`). Order: Security fix → Bug fix → Feature. -- Package names in backticks, version numbers in **bold**. -- Include CVE/GHSA references (CVE-YYYY-NNNNN or GHSA-XXXX-XXXX-XXXX). -- Keywords are always `installed-collector` — no user confirmation needed. - -**Validation**: -- [ ] Title: "Installed Collector Version X.Y.Z-N" -- [ ] H4 sections in correct order (Security → Bug → Feature) -- [ ] Versions in **bold**, packages in backticks -- [ ] CVE/GHSA references where applicable - -### OpenTelemetry Collector - -**Gather**: feature name, release date, description (focus on user benefit), doc link. - -**Frontmatter**: -```yaml ---- -title: {Feature Name} -image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 -hide_table_of_contents: true -keywords: - - opentelemetry-collector ---- -``` - -**Content**: -```markdown -import useBaseUrl from '@docusaurus/useBaseUrl'; - -We're excited to announce {feature description}. {Benefits}. [Learn more](/docs/path/to/doc). -``` - -Start with "We're excited to announce..." or "We're excited to introduce...". Keywords are always `opentelemetry-collector` — no user confirmation needed. Use admonitions for important notes or breaking changes. - -**Validation**: -- [ ] Starts with "We're excited to..." -- [ ] "Learn more" link with relative path -- [ ] Keywords: `opentelemetry-collector` - ---- - -## Cloud SIEM (`blog-cse/`) - -**File**: `blog-cse/YYYY-MM-DD-{type}.md` (`-content` or `-application`) - -Always include `import useBaseUrl from '@docusaurus/useBaseUrl';` after frontmatter. - -### Content release - -**Gather**: release date, new/updated rules (IDs and names), log mappers, parsers, 3–5 high-level summary points, keywords (confirm with user; default: rules, log mappers, parsers). - -**Frontmatter**: -```yaml ---- -title: {Month} {Day ordinal}, {Year} - Content Release -hide_table_of_contents: true -keywords: - - rules - - log mappers - - parsers -image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 ---- -``` - -Title uses ordinal suffix (12th, 3rd, 21st). Full month name, not abbreviated. Examples: "March 19th, 2026 - Content Release", "February 3rd, 2026 - Content Release". - -**Content**: -```markdown -This content release includes: - - {Summary point 1} - - {Summary point 2} - -Additional changes are enumerated below. - -### Rules -* [New] MATCH-SXXXX Rule Name. -* [Updated] FIRST-SXXXX Rule Name. Brief description of what changed. - -### Log Mappers -* [New] Vendor - Event Type. - -### Parsers -* [Updated] /Parsers/System/Vendor/Parser Name. -``` - -- Summary bullets use 4-space indentation. -- `[New]` or `[Updated]` tag on every item. -- Rule ID formats: `MATCH-SXXXX`, `FIRST-SXXXX`, `THRESHOLD-SXXXX`, `AGGREGATION-SXXXX`, `CHAIN-SXXXX`, `OUTLIER-SXXXX` -- Parser paths use full hierarchy: `/Parsers/System/Vendor/Name` -- Log mapper format: `Vendor - Event Type` -- Sort alphabetically within each section. -- Do not invent rule IDs — ask the user if not provided. - -### Application release - -**Gather**: release date, features with descriptions and doc links, screenshots (if applicable), keywords (confirm with user). - -**Frontmatter**: -```yaml ---- -title: {Month} {Day}, {Year} - Application Update -image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 -keywords: - - {keyword} -hide_table_of_contents: true ---- -``` - -**Content**: -```markdown -### {Feature Name} - -{Description and business value}. [Learn more](/docs/path/to/docs). -``` - -H3 for each feature. Add screenshots with `description` for UI changes. - -**Validation (both CSE types)**: -- [ ] `blog-cse/YYYY-MM-DD-{type}.md` -- [ ] Title uses ordinal suffix for content releases -- [ ] `import useBaseUrl` included -- [ ] `hide_table_of_contents: true` -- [ ] Content: `[New]`/`[Updated]` tags on all items; parser paths complete -- [ ] Keywords confirmed with user - ---- - -## Cloud SOAR (`blog-csoar/`) - -**File**: `blog-csoar/YYYY-MM-DD-{subtype}.md` -- Content release: `YYYY-MM-DD-content-release.md` -- Application update: `YYYY-MM-DD-application-update.md` - -Always include `import useBaseUrl from '@docusaurus/useBaseUrl';` after frontmatter. - -**Date format in title**: "Month DD, YYYY" — full month name, zero-padded day, no ordinal. Examples: "March 06, 2026" ✅, "March 6, 2026" ❌, "March 6th, 2026" ❌. - -Application Updates are published early the following month for the previous month's changes. Filename and title use the publication date; the H2 header and intro use the release month. - -**Keywords** (confirm with user): -- Content release: `automation service`, `cloud soar`, `soar` -- Application update: `automation service`, `cloud soar` - -**Integration doc path**: `/docs/platform-services/automation-service/app-central/integrations/{slug}/` - -### Content release - -**Frontmatter**: -```yaml ---- -title: {Month DD, 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: - - automation service - - cloud soar - - soar ---- -``` - -**Content**: -```markdown -This release introduces {what's new}. - -### Integrations - -* [New] [Integration Name](/docs/platform-services/automation-service/app-central/integrations/{slug}/) -* [Updated] [Integration Name](/docs/platform-services/automation-service/app-central/integrations/{slug}/) - -### Playbooks - -* [New] {ID} - {Playbook Title} -``` - -Integration entries are link-only — no descriptions. Playbooks section is optional. - -### Application update - -**Frontmatter**: -```yaml ---- -title: {Month DD, 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: - - automation service - - cloud soar ---- -``` - -**Content**: -```markdown -## {Release month} release - -Following are the updates made in {Month} {YYYY}. - -### Changes and enhancements - -#### Integrations - -* [Added] [Integration Name](/docs/path/) - Description of what was added. -* [Updated] [Integration Name](/docs/path/) - Description of what was updated. - -#### Platform - -* Platform enhancement description. - -### Bug Fixes - -#### Integrations - -* In the [Integration Name](/docs/path/) integration, description of fix. - -#### Platform - -Fixed an issue where {description}. -``` - -Integration changes use `[Added]` for new integrations, `[Updated]` for existing. Always include descriptions (unlike content releases). - -**Validation (both SOAR types)**: -- [ ] `blog-csoar/`; filename uses full suffix (`-content-release.md` or `-application-update.md`) -- [ ] Title: "Month DD, YYYY" format (zero-padded, no ordinal) -- [ ] `import useBaseUrl` included -- [ ] `hide_table_of_contents: true` -- [ ] Keywords confirmed with user -- [ ] Application update: H2 header uses release month, not publication month - ---- - -## Developer (`blog-developer/`) - -**Gather**: title/topic, release date, content (what changed, why it matters, impact), doc links, keywords (optional; ask user). - -**File**: `blog-developer/YYYY-MM-DD-{slug}.md` - -Slug: lowercase, hyphens, 3–5 words. Examples: `api-endpoints`, `india-datacenter-deprecation`, `python-sdk-v2`. - -**Frontmatter**: -```yaml ---- -title: {Month Day, YYYY} - {Topic} -image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 -hide_table_of_contents: true ---- -``` - -**Title format**: "Month Day, YYYY - Topic" — full month, no ordinal. Examples: "April 9, 2025" ✅, "April 9th, 2025" ❌, "Apr 9, 2025" ❌. - -**Content**: -```markdown -{Main paragraph — what changed, why it matters} - -#### {Subsection if needed} - -* {Item} -``` - -- H4 (`####`) for subsections. -- `:::warning` admonitions for breaking changes. -- Doc links always use relative paths (`/docs/...`). -- Only add `import useBaseUrl` if content uses images. - -**Validation**: -- [ ] `blog-developer/YYYY-MM-DD-{slug}.md` -- [ ] Title: "Month Day, YYYY - Topic" (no ordinal) -- [ ] `hide_table_of_contents: true` -- [ ] Breaking changes clearly marked -- [ ] Doc links use relative paths diff --git a/CLAUDE.md b/CLAUDE.md index 57c21a2d7d..52d6c2d086 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -72,7 +72,11 @@ When a user asks "what can I do", "what commands are available", or similar, sha | Command | What it does | |---------|-------------| -| `/release-note` | New release note (service, collector, Cloud SIEM, Cloud SOAR, or developer) | +| `/release-note-service` | New service release note | +| `/release-note-collector` | New Collector release note | +| `/release-note-cse` | New Cloud SIEM release note | +| `/release-note-csoar` | New Cloud SOAR release note | +| `/release-note-developer` | New developer/API release note | **Editing and reviewing** From 27ffa95e4498b20146855cfbae5703ab81476f5e Mon Sep 17 00:00:00 2001 From: Kim Pohas Date: Fri, 5 Jun 2026 00:35:33 -0700 Subject: [PATCH 05/22] revert release notes --- .claude/commands/release-note-collector.md | 410 ++++++++++++-- .claude/commands/release-note-cse.md | 422 +++++++++++++-- .claude/commands/release-note-csoar.md | 590 +++++++++++++++++++-- .claude/commands/release-note-developer.md | 507 ++++++++++++++++-- .claude/commands/release-note-service.md | 471 +++++++++++++++- 5 files changed, 2171 insertions(+), 229 deletions(-) diff --git a/.claude/commands/release-note-collector.md b/.claude/commands/release-note-collector.md index 9e6474d99d..faef82018f 100644 --- a/.claude/commands/release-note-collector.md +++ b/.claude/commands/release-note-collector.md @@ -1,37 +1,83 @@ # Create New Collector Release Note -Creates a Collector release note — either an Installed Collector version release or an OpenTelemetry Collector feature announcement. +Automates the creation of Collector release notes for Installed Collector versions and OpenTelemetry features. + +## What this command does + +When you invoke `release-note-collector`, Claude will guide you through: + +1. **Determine release type**. Installed Collector version or OpenTelemetry feature +2. **Gather release details**. Version number, changes, features, or fixes +3. **Create markdown file**. Generate file with proper frontmatter and structure +4. **Format content**. Apply correct formatting for version releases or features +5. **Validate and preview**. Check structure and provide next steps + +## When to use this command + +* Publishing new Installed Collector versions with bug or security fixes. +* Announcing OpenTelemetry collector features and improvements. +* Documenting collector version updates. +* Releasing new OpenTelemetry integrations or capabilities. + +## Release types + +### Installed Collector Release (`-installed.md`) + +For Installed Collector version releases: +* **Version numbers**: Format X.Y.Z-N (e.g., 19.535-6). +* **Security fixes**: CVE patches, dependency upgrades. +* **Bug fixes**: Issue resolutions and stability improvements. +* **Minor features**: Small enhancements in collector behavior. + +**Typical cadence**: As needed when versions ship + +### OpenTelemetry Release (`-otel.md`) + +For OpenTelemetry collector features: +* **New features**: Installation methods, integrations, capabilities. +* **Improvements**: Performance enhancements, reliability updates. +* **Announcements**: CDN changes, configuration updates. + +**Typical cadence**: As features are released ## Workflow -### Step 1: Determine release type +### Step 1: Gather information -Ask the user: **Installed Collector** (version release with security/bug fixes) or **OpenTelemetry Collector** (feature announcement)? +Ask the user for: -### Step 2: Gather information +**For Installed Collector releases:** +* **Version number**: Full version (e.g., 19.535-6). +* **Release date**: Date in YYYY-MM-DD format. +* **Changes**: List of security fixes, bug fixes, or features. -**For Installed Collector:** -- Version number (X.Y.Z-N format, e.g. 19.535-6) -- Release date (YYYY-MM-DD) -- List of security fixes, bug fixes, and/or features +**For OpenTelemetry releases:** +* **Feature name**: Name of the feature or update. +* **Release date**: Date in YYYY-MM-DD format. +* **Description**: What it does and why it matters (2-3 sentences). +* **Documentation link**: Relative path to the doc. -**For OpenTelemetry Collector:** -- Feature name -- Release date (YYYY-MM-DD) -- Description (focus on user benefit, 2–3 sentences) -- Doc link (relative path) +**Validate:** +* Check that date is not in the future. +* For installed releases, validate version number format. +* For OTel releases, ensure documentation link exists. -### Step 3: Create the file +### Step 2: Create the markdown file -**File**: `blog-collector/YYYY-MM-DD-{type}.md` — type is `-installed` or `-otel` +**File naming convention:** +``` +blog-collector/YYYY-MM-DD-{type}.md +``` -If a file already exists for the same date and type, ask the user to use a different date or append. +Examples: +* `blog-collector/2026-03-19-installed.md`. +* `blog-collector/2026-03-19-otel.md`. ---- +**Important**: Files are created in `/blog-collector/` directory -#### Installed Collector +### Step 3: Generate frontmatter -**Frontmatter**: +**For Installed Collector releases:** ```yaml --- title: Installed Collector Version {X.Y.Z-N} @@ -42,61 +88,317 @@ keywords: --- ``` -**Content**: +**For OpenTelemetry releases:** +```yaml +--- +title: {Feature Name} +image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 +hide_table_of_contents: true +keywords: + - opentelemetry-collector +--- +``` + +**Title formatting:** +* Installed: "Installed Collector Version X.Y.Z-N" +* OTel: Feature name in Title Case (no category suffix) + +**Keywords:** +* Installed Collector: Always use `installed-collector` +* OpenTelemetry: Always use `opentelemetry-collector` +* These keywords are standard and do not need user confirmation + +### Step 4: Add required import + +For OpenTelemetry releases that use links or useBaseUrl: +```javascript +import useBaseUrl from '@docusaurus/useBaseUrl'; +``` + +**Note**: Only add if content uses it. For simple version releases, omit. + +### Step 5: Write content + +#### Installed Collector Release Structure + ```markdown -In this release, we've enhanced the security and stability of the Collector with added support for {security patches/bug fixes/features}. +In this release, we've enhanced the security and stability of the Collector with added support for security patches. #### Security fix -* Upgraded `{package}` to version **{version}** to address known security vulnerability ({CVE-YYYY-NNNNN}). +* {Security fix description with version numbers and CVE references}. +* {Additional security fixes}. #### Bug fix * {Bug fix description}. +* {Additional bug fixes}. ``` -- Sections use H4 (`####`). Order: Security fix → Bug fix → Feature. -- Package names in backticks, version numbers in **bold**. -- Include CVE/GHSA references where applicable (CVE-YYYY-NNNNN or GHSA-XXXX-XXXX-XXXX). -- Keywords are always `installed-collector` — no confirmation needed. +**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}." +* Use H4 (`####`) for section headings: Security fix, Bug fix, Feature +* 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 ---- +**Example:** +```markdown +In this release, we've enhanced the security and stability of the Collector with added support for security patches. -#### OpenTelemetry Collector +#### Security fix -**Frontmatter**: -```yaml ---- -title: {Feature Name} -image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 -hide_table_of_contents: true -keywords: - - opentelemetry-collector ---- +* Upgraded `io.netty:netty-codec-http` to version **4.1.129.Final** to address known security vulnerability (CVE-2025-67735). +* Upgraded `com.fasterxml.jackson.core` packages to use patched version **2.18.6** to address known security vulnerability (GHSA-72hv-8253-57qq). + +#### Bug fix + +* Fixed an issue with forwarded Windows event collection that occurred on systems running with latest Windows version. +``` + +#### OpenTelemetry Release Structure + +```markdown +We're excited to {announce/introduce} {feature description}. {What it does and benefits}. [Learn more](/docs/path/to/doc). + +{Optional: Additional paragraphs with more details} + +{Optional: Related documentation list} + +{Optional: Important notes in admonition} ``` -**Content**: +**OpenTelemetry Guidelines:** +* Start with "We're excited to announce..." or "We're excited to introduce...". +* Write 2-3 sentences in first paragraph. +* Focus on user benefits and business value. +* End first paragraph with "Learn more" link. +* 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):** ```markdown import useBaseUrl from '@docusaurus/useBaseUrl'; -We're excited to announce {feature description}. {Benefits}. [Learn more](/docs/path/to/doc). +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/). ``` -- Start with "We're excited to announce..." or "We're excited to introduce..." -- Keywords are always `opentelemetry-collector` — no confirmation needed. -- Use admonitions for important notes or breaking changes. +**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. + +Refer to the following documentation to view the updated URLs in the UI. +* [Ansible](/docs/send-data/opentelemetry-collector/install-collector/ansible/). +* [Chef](/docs/send-data/opentelemetry-collector/install-collector/chef/). +* [Puppet](/docs/send-data/opentelemetry-collector/install-collector/puppet/). + +:::note +* Existing OpenTelemetry binaries and other packages remain in their current locations. +* This change does not affect the UI itself. The download process looks the same, but the underlying URL now uses a CDN to improve reliability and speed. +::: +``` + +### Step 6: Validation checklist + +Before finishing, verify: +* [ ] File created in `/blog-collector/` directory. +* [ ] Filename follows pattern: `YYYY-MM-DD-{type}.md` +* [ ] Frontmatter complete with all required fields. +* [ ] Title format correct (version number or feature name). +* [ ] `hide_table_of_contents: true` present +* [ ] Keywords correct for type (installed-collector or opentelemetry). +* [ ] 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: "Learn more" link included with relative path +* [ ] No trailing whitespace. + +## Example usage + +### Installed Collector Example + +``` +User: "Create a Collector release note for version 19.535-8 with a security fix for Netty and a bug fix for Windows events" + +Claude: +1. Confirms type: Installed Collector +2. Confirms date: 2026-03-19 +3. Creates: blog-collector/2026-03-19-installed.md +4. Generates frontmatter: "Installed Collector Version 19.535-8" +5. Adds standard intro paragraph +6. Creates Security fix section with Netty upgrade +7. Creates Bug fix section with Windows events fix +8. Provides checklist +``` + +### OpenTelemetry Example + +``` +User: "Create an OTel Collector release note about new Kubernetes monitoring support" + +Claude: +1. Confirms type: OpenTelemetry +2. Confirms date: 2026-03-19 +3. Asks for description and doc link +4. Creates: blog-collector/2026-03-19-otel.md +5. Generates frontmatter: "Kubernetes Monitoring Support" +6. Writes announcement with feature benefits +7. Adds "Learn more" link +8. Provides checklist +``` + +## Version number format + +Installed Collector versions follow this pattern: +``` +Major.Minor.Patch-Build +``` + +Examples: +* `19.535-6` — Version 19.535, build 6. +* `19.535-4` — Version 19.535, build 4. +* `20.0-1` — Version 20.0, build 1. + +**Formatting in title:** +* Always include full version with build number. +* No spaces around hyphen. +* Example: "Installed Collector Version 19.535-6" + +## Dependency upgrade format + +When listing upgraded dependencies: +* Use backticks for package names. +* Use **bold** for version numbers. +* Include full CVE or GHSA reference if applicable. + +**Examples:** +* ✅ `io.netty:netty-codec-http` to version **4.1.129.Final** to address known security vulnerability (CVE-2025-67735) +* ✅ `com.fasterxml.jackson.core` packages to use patched version **2.18.6** (GHSA-72hv-8253-57qq). +* ✅ Collector JRE to **Amazon Corretto Version 17.0.18.8.1**. +* ❌ Upgraded netty-codec-http to 4.1.129.Final (missing backticks and bold). + +## Safety principles + +* **Check existing files** before creating to avoid duplicates. +* **Validate version numbers** follow the correct format. +* **Verify CVE/GHSA references** are accurate. +* **Use consistent formatting** for dependencies and versions. +* **Keep installed releases brief**. Just the facts. +* **Focus OTel releases on benefits** not technical details. + +## Post-completion message + +After successfully creating the release note, tell the user: + +**For Installed Collector:** +``` +✅ Installed Collector release note created successfully! + +File created: +* 📄 blog-collector/{date}-installed.md. + +Summary: +* Version: {version} +* Security fixes: {count} +* Bug fixes: {count} + +Next steps: +1. Review CVE/GHSA references for accuracy +2. Verify version numbers are correct +3. Ensure all fixes are documented +4. Test locally: yarn start +5. Check preview at: http://localhost:3000/release-notes-collector +6. Submit PR: "DOCS-XXX - Installed Collector {version} release notes" + +Checklist: +* [ ] Version number is correct. +* [ ] All security vulnerabilities referenced. +* [ ] Dependencies use backticks and bold versions. +* [ ] Bug fixes are complete. + +The release note will appear on the Collector release notes page in reverse chronological order (newest first). +``` + +**For OpenTelemetry:** +``` +✅ OpenTelemetry Collector release note created successfully! + +File created: +* 📄 blog-collector/{date}-otel.md. + +Summary: +* Feature: {Feature Name} +* Keywords: opentelemetry + +Next steps: +1. Review content for accuracy and clarity +2. Verify documentation link is correct +3. Ensure feature name and description are clear +4. Test locally: yarn start +5. Check preview at: http://localhost:3000/release-notes-collector +6. Submit PR: "DOCS-XXX - OTel Collector: {Feature Name}" + +Checklist: +* [ ] Feature name is clear and concise. +* [ ] Description focuses on user benefits. +* [ ] Documentation link is correct. +* [ ] No placeholder text remaining. + +The release note will appear on the Collector release notes page in reverse chronological order (newest first). + +Would you like me to help refine the description or add additional details? +``` + +## Error handling + +**If file already exists:** +* Show existing file content. +* Ask if user wants to: + * Use different type (installed vs otel). + * Use different date. + * Overwrite (requires confirmation). + +**If version number format is invalid:** +* Show expected format: X.Y.Z-N +* Ask for correction. + +**If CVE/GHSA reference looks incomplete:** +* Warn about format. +* Ask for confirmation. + +**If documentation link looks wrong (OTel):** +* Warn if does not start with `/docs/`. +* Suggest correction. + +## Tips and best practices + +**Installed Collector releases:** +* Be specific about what was fixed or upgraded. +* Include exact version numbers. +* Reference CVEs and GHSAs when applicable. +* Keep descriptions factual and brief. +* Order matters: Security → Bugs → Features + +**OpenTelemetry releases:** +* Lead with user benefit. +* Explain why the change matters. +* Link to comprehensive documentation. +* Use admonitions for breaking changes or important notes. -### Step 4: Validate +**Both types:** +* Use consistent formatting throughout. +* Keep language simple and direct. +* Avoid unnecessary technical jargon. +* Focus on what changed, not how it was implemented. -**Installed Collector:** -- [ ] `blog-collector/YYYY-MM-DD-installed.md` -- [ ] Title: "Installed Collector Version X.Y.Z-N" -- [ ] H4 sections in correct order (Security → Bug → Feature) -- [ ] Versions in **bold**, packages in backticks -- [ ] CVE/GHSA references where applicable +## References -**OpenTelemetry Collector:** -- [ ] `blog-collector/YYYY-MM-DD-otel.md` -- [ ] Starts with "We're excited to..." -- [ ] "Learn more" link with relative path -- [ ] Keywords: `opentelemetry-collector` +* [Collector Release Notes](https://sumologic.com/help/release-notes-collector) +* [Release Notes Index](/docs/release-notes). +* [Style Guide](/docs/contributing/style-guide). diff --git a/.claude/commands/release-note-cse.md b/.claude/commands/release-note-cse.md index bbb7238631..41e36c6c66 100644 --- a/.claude/commands/release-note-cse.md +++ b/.claude/commands/release-note-cse.md @@ -1,60 +1,145 @@ # Create New Cloud SIEM Release Note -Creates a Cloud SIEM (CSE) release note — either a content release (rules, log mappers, parsers) or an application release (features, bug fixes, UI updates). +Automates the creation of Cloud SIEM (CSE) release notes with proper formatting, frontmatter, and structure. + +## What this command does + +When you invoke `release-note-cse`, Claude will guide you through: + +1. **Determine release type**. Content release or Application release +2. **Gather release details**. Date, changes, features, bug fixes +3. **Create markdown file**. Generate file with proper frontmatter and structure +4. **Format content**. Apply correct formatting for rules, mappers, parsers, or features +5. **Validate and preview**. Check structure and provide next steps + +## When to use this command + +* Publishing Cloud SIEM content updates (rules, log mappers, parsers). +* Announcing new Cloud SIEM features or bug fixes. +* Creating regular bi-weekly or monthly CSE release notes. +* Documenting Cloud SIEM application updates. + +## Release types + +### Content Release (`-content.md`) + +For updates to Cloud SIEM detection content: +* **Rules**: New or updated detection rules +* **Log Mappers**: New or updated log mapping configurations +* **Parsers**: Parser updates and enhancements +* **Schema changes**: New fields or tags + +**Typical cadence**: Every 1-2 weeks + +### Application Release (`-application.md`) + +For Cloud SIEM product features and updates: +* **New features**: UI improvements, new capabilities +* **Bug fixes**: Issue resolutions +* **Performance improvements**: Optimizations +* **Breaking changes or deprecations**. + +**Typical cadence**: As needed when features ship ## Workflow -### Step 1: Determine release type +### Step 1: Gather information + +Ask the user for: -Ask the user: **Content release** (rules, log mappers, parsers — typically bi-weekly) or **Application release** (new features, bug fixes, UI improvements)? +**Required:** +* **Release type**: Content or Application +* **Release date**: Date in YYYY-MM-DD format +* **Changes**: List of what's included -### Step 2: Gather information +**For Content Releases:** +* New/updated rules (rule IDs and names). +* New/updated log mappers. +* New/updated parsers. +* Brief summary of changes. -**For content releases:** -- Release date (YYYY-MM-DD) -- New/updated rules (IDs and names) — do not invent rule IDs, ask the user -- New/updated log mappers -- New/updated parsers -- 3–5 high-level summary points -- Keywords (confirm with user; default: rules, log mappers, parsers) +**For Application Releases:** +* Feature name and description. +* Documentation links. +* Screenshots (if applicable). +* Any breaking changes. -**For application releases:** -- Release date (YYYY-MM-DD) -- Features with descriptions and doc links -- Keywords (confirm with user) +**Keywords (for both types):** +* Ask user to confirm or customize keywords +* Suggest defaults based on release type (see frontmatter section below) -### Step 3: Create the file +**Validate:** +* Check that date is not in the future (use today's date if not specified). +* Ensure file does not already exist for this date and type. +* Confirm changes are ready to publish. +* Confirm keywords with user before creating file. -**File**: `blog-cse/YYYY-MM-DD-{type}.md` — type is `-content` or `-application` +### Step 2: Create the markdown file -Always include `import useBaseUrl from '@docusaurus/useBaseUrl';` after frontmatter. +**File naming convention:** +``` +blog-cse/YYYY-MM-DD-{type}.md +``` -If a file already exists for the same date and type, ask the user to use a different date or append. +Examples: +* `blog-cse/2026-03-19-content.md`. +* `blog-cse/2026-03-19-application.md`. ---- +**Important**: Files are created in `/blog-cse/` directory, NOT in `/docs/` -#### Content release +### Step 3: Generate frontmatter -**Frontmatter**: +**For Content Releases:** ```yaml --- -title: {Month} {Day ordinal}, {Year} - Content Release +title: {Month} {Day}th, {Year} - Content Release hide_table_of_contents: true keywords: - - rules - - log mappers - - parsers + * rules + * log mappers + * parsers image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 --- ``` -Title uses ordinal suffix: "March 19th, 2026 - Content Release", "February 3rd, 2026 - Content Release". Full month name, not abbreviated. +**For Application Releases:** +```yaml +--- +title: {Month} {Day}, {Year} - Application Update +image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 +keywords: + * {relevant-keyword} +hide_table_of_contents: true +--- +``` + +**Keywords guidance:** +* **Always ask user to confirm keywords before creating file** +* Suggested defaults: + * Content releases: `rules`, `log mappers`, `parsers` + * 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. + +### Step 4: Add required import + +Always include after frontmatter: +```javascript +import useBaseUrl from '@docusaurus/useBaseUrl'; +``` + +### Step 5: Write content + +#### Content Release Structure -**Content**: ```markdown This content release includes: - - {Summary point 1} - - {Summary point 2} + - {High-level summary point 1} + - {High-level summary point 2} + - {High-level summary point 3} Additional changes are enumerated below. @@ -64,48 +149,271 @@ Additional changes are enumerated below. ### Log Mappers * [New] Vendor - Event Type. +* [Updated] Vendor - Event Type. ### Parsers * [Updated] /Parsers/System/Vendor/Parser Name. ``` -- Summary bullets use 4-space indentation. -- `[New]` or `[Updated]` tag on every item. -- Rule ID formats: `MATCH-SXXXX`, `FIRST-SXXXX`, `THRESHOLD-SXXXX`, `AGGREGATION-SXXXX`, `CHAIN-SXXXX`, `OUTLIER-SXXXX` -- Parser paths use full hierarchy: `/Parsers/System/Vendor/Name` -- Log mapper format: `Vendor - Event Type` -- Sort alphabetically within each section. +**Content Release Guidelines:** +* Start with bulleted summary (3-5 high-level points). +* Use indentation (4 spaces) for bullet points. +* Group changes by type: Rules, Log Mappers, Parsers +* Use `[New]` or `[Updated]` tags. +* Rule IDs use format: `MATCH-SXXXX`, `FIRST-SXXXX`, `THRESHOLD-SXXXX` +* Parser paths use full hierarchy: `/Parsers/System/Vendor/Name` +* Add brief explanations for significant updates. +* Sort items alphabetically within each section. ---- +#### Application Release Structure -#### Application release +```markdown +### {Feature Name} -**Frontmatter**: -```yaml +{Feature description and business value}. [Learn more](/docs/path/to/docs). + +{Optional screenshot or additional details} +``` + +**Application Release Guidelines:** +* Use H3 (`###`) for each feature. +* Start with clear, concise description. +* 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. + +### 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" + +Examples: +* ✅ "March 19th, 2026 - Content Release". +* ✅ "February 3rd, 2026 - Application Update". +* ❌ "Mar 19, 2026 - Content Release" (month abbreviated). +* ❌ "March 19 2026 - Content Release" (missing "th"). + +### Step 7: Validation checklist + +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. +* [ ] `hide_table_of_contents: true` present +* [ ] Keywords appropriate for release type. +* [ ] `import useBaseUrl` statement included. +* [ ] Content follows proper structure (Rules → Log Mappers → Parsers). +* [ ] All `[New]` and `[Updated]` tags present. +* [ ] Parser paths use full `/Parsers/System/Vendor/Name` format. +* [ ] Links use relative paths or `useBaseUrl`. +* [ ] No trailing whitespace or extra blank lines. + +## Example usage + +### Content Release Example + +``` +User: "Create a CSE content release for today with updates to AWS CloudTrail rules and new Okta log mappers" + +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" +5. Adds summary section +6. Creates sections for Rules and Log Mappers +7. Formats with proper [New]/[Updated] tags +8. Provides checklist and next steps +``` + +### Application Release Example + +``` +User: "Create a CSE application release for March 15th about the new bulk insight update feature" + +Claude: +1. Confirms date: 2026-03-15 +2. Confirms type: Application Release +3. Creates: blog-cse/2026-03-15-application.md +4. Generates frontmatter: "March 15, 2026 - Application Update" +5. Adds feature section with H3 heading +6. Includes description and Learn more link +7. Provides checklist +``` + +## Common patterns + +### Rule ID formats + +* `MATCH-SXXXX` — Match rules (most common). +* `FIRST-SXXXX` — First Seen rules. +* `THRESHOLD-SXXXX` — Threshold rules. +* `AGGREGATION-SXXXX` — Aggregation rules. +* `CHAIN-SXXXX` — Chain rules. +* `OUTLIER-SXXXX` — Outlier rules. + +### Parser path structure + +Always use full path: +``` +/Parsers/System/{Vendor}/{Parser Name} +``` + +Examples: +* `/Parsers/System/AWS/AWS CloudTrail`. +* `/Parsers/System/Okta/Okta`. +* `/Parsers/System/Microsoft/Microsoft 365`. +* `/Parsers/System/Cisco/Cisco ASA`. + +### Log Mapper naming + +Format: `{Vendor} - {Event Type}` + +Examples: +* `Okta - Authentication Events`. +* `AWS CloudTrail - Management Events`. +* `Microsoft 365 - Audit Logs`. +* `CrowdStrike Falcon - Detection Events`. + +### Vendor consistency + +Use standard vendor names: +* ✅ "Microsoft 365" (not "Office 365", "O365"). +* ✅ "Google Workspace" (not "G Suite", "GSuite"). +* ✅ "SonicWall Firewall" (not "Dell SonicWall"). +* ✅ "AWS CloudTrail" (not "Amazon CloudTrail"). + +## Archive process + +**When to archive:** +* At year-end, older releases move to archive files. +* Archive files are in `/blog-cse/{YEAR}/12-31.md`. +* Current year + 1-2 prior years remain active. +* Older years are archived. + +**Archive structure:** +```markdown --- -title: {Month} {Day}, {Year} - Application Update +title: {Year} Release Notes Archive - Cloud SIEM +keywords: [rules, signals, schema, log mappers, parsers, cloud siem] image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 -keywords: - - {keyword} -hide_table_of_contents: true +--- + +import useBaseUrl from '@docusaurus/useBaseUrl'; + +This is an archive of {Year} Cloud SIEM release notes. [View the full archive](/release-notes-cse/archive). + + + +--- + +### {Month} {Day}, {Year} - {Type} + +{Content} + --- ``` -**Content**: -```markdown -### {Feature Name} +**Note:** Users typically do not need to manage archives manually. Mention this only if they ask about archiving old releases. + +## Safety principles + +* **Check existing files** before creating to avoid duplicates. +* **Validate dates** are not in the future. +* **Use consistent vendor names** (check existing releases for precedent). +* **Preserve exact rule IDs** when user provides them. +* **Do not invent rule IDs**. Ask user if not provided. +* **Link to docs** when mentioning features. + +## Post-completion message + +After successfully creating the release note, tell the user: + +``` +✅ Cloud SIEM release note created successfully! -{Description and business value}. [Learn more](/docs/path/to/docs). +File created: +* 📄 blog-cse/{date}-{type}.md. + +Summary: +* Type: {Content Release | Application Update} +* Date: {formatted date} +* Changes: {count} rules, {count} log mappers, {count} parsers + +Next steps: +1. Review content for accuracy +2. Add any missing details or descriptions +3. Verify all rule IDs and parser paths are correct +4. Add screenshots for application updates (if applicable) +5. Test locally: yarn start +6. Check preview at: http://localhost:3000/release-notes-cse +7. Submit PR: "DOCS-XXX - CSE {type} release notes for {date}" + +Checklist: +* [ ] All rule IDs verified. +* [ ] Parser paths use full /Parsers/System/ format. +* [ ] Vendor names consistent with existing releases. +* [ ] Links tested and working. +* [ ] No placeholder text remaining. + +The release note will appear on the Cloud SIEM release notes page in reverse chronological order (newest first). + +Would you like me to help fill in any additional details? ``` -H3 for each feature. Add screenshots with `description` for UI changes. +## Error handling + +**If file already exists:** +* Show existing file path and date. +* Ask if user wants to: + * Add to existing release (append content). + * Create with different date. + * Overwrite (requires confirmation). + +**If date is invalid:** +* Show error and ask for correct format (YYYY-MM-DD). +* Suggest today's date as default. + +**If rule IDs do not match pattern:** +* Warn user about non-standard format. +* Ask for confirmation before proceeding. + +**If vendor names are inconsistent:** +* Check recent releases for the vendor. +* Suggest standard name. +* Ask user to confirm. + +## Tips and best practices + +**Content releases:** +* Lead with most significant changes in summary. +* Group related changes together (e.g., all Okta updates). +* Include context for major updates ("Updated detection expression for improved query performance"). +* Keep descriptions concise (one sentence per update). + +**Application releases:** +* Lead with user benefit, not technical details. +* Always link to documentation. +* Use screenshots for UI changes. +* Mention if feature requires admin privileges. + +**General:** +* Be consistent with formatting across releases. +* Use active voice ("Added support for.." not "Support was added.."). +* Spell out acronyms on first use in each release. +* Keep release notes focused on what changed, not why. -### Step 4: Validate +## References -- [ ] `blog-cse/YYYY-MM-DD-{type}.md` -- [ ] Title uses ordinal suffix for content releases -- [ ] `import useBaseUrl` included -- [ ] `hide_table_of_contents: true` -- [ ] Content: `[New]`/`[Updated]` tags on all items; parser paths complete -- [ ] Keywords confirmed with user -- [ ] No trailing whitespace +* [Cloud SIEM Release Notes](https://sumologic.com/help/release-notes-cse) +* [Release Notes Index](/docs/release-notes). +* [Style Guide](/docs/contributing/style-guide). diff --git a/.claude/commands/release-note-csoar.md b/.claude/commands/release-note-csoar.md index 9c0ff2bc39..ebe2508bbd 100644 --- a/.claude/commands/release-note-csoar.md +++ b/.claude/commands/release-note-csoar.md @@ -1,49 +1,137 @@ # Create New Cloud SOAR Release Note -Creates a Cloud SOAR (Automation Service) release note — either a content release (new integrations and playbooks) or an application update (platform features, enhancements, bug fixes). +Automates the creation of Cloud SOAR (Automation Service) release notes for platform updates, integration changes, and bug fixes. + +## What this command does + +When you invoke `release-note-csoar`, Claude will guide you through: + +1. **Determine release type**. Content Release or Application Update +2. **Gather release details**. Date, changes, integrations, playbooks, or platform updates +3. **Create markdown file**. Generate file with proper frontmatter and structure +4. **Format content**. Apply correct formatting for the release type +5. **Validate and preview**. Check structure and provide next steps + +## When to use this command + +* Publishing new integrations and playbooks (Content Release) +* Publishing Cloud SOAR platform updates (Application Update) +* Documenting integration updates or bug fixes +* Announcing new API endpoints or features +* Releasing playbook improvements + +## Release types + +### Content Release (`-content-release.md`) + +For releases focused on new content (integrations and playbooks): +* **New integrations**: Brand new integrations added to App Central +* **Updated integrations**: Improvements to existing integrations +* **New playbooks**: New playbooks with ID numbers and titles +* **Simple format**: Just lists of what's new/updated, minimal descriptions + +**Typical cadence**: Monthly or as content batches are released + +### Application Update (`-application-update.md`) + +For platform features, enhancements, and bug fixes: +* **Platform features**: New capabilities, UX improvements, APIs +* **Integration changes**: With detailed descriptions of what changed +* **Bug fixes**: Issues resolved in integrations, platform, or playbooks +* **Detailed format**: Sections with descriptions and context + +**Typical cadence**: Monthly, published early the following month + +## Release structure (varies by type) + +### Content Release Structure + +Simple format with just lists: + +1. **Intro paragraph** - Brief description of release +2. **Integrations** (H3) - Bulleted list of [New]/[Updated] integrations +3. **Playbooks** (H3) - Bulleted list of [New] playbooks with IDs and titles + +### Application Update Structure + +Detailed format with descriptions and bug fixes: + +1. **Release month header** (H2) - "## {Month} release" +2. **Changes and enhancements** (H3) + - **Integrations** (H4) - New or updated integrations with descriptions + - **Platform** (H4) - Platform features and improvements + - **Playbooks** (H4) - Playbook-related changes (optional) +3. **Bug Fixes** (H3) + - **Integrations** (H4) - Integration bug fixes + - **Platform** (H4) - Platform bug fixes + - **Playbooks** (H4) - Playbook bug fixes ## Workflow ### Step 1: Determine release type -Ask the user: **Content release** (new/updated integrations and playbooks) or **Application update** (platform features, enhancements, bug fixes — published early the following month)? +Ask the user which type of release: + +**Content Release** - For new integrations and playbooks +* Simple list format +* No detailed descriptions +* No bug fixes section +* Use when: Releasing batch of new content + +**Application Update** - For platform features and bug fixes +* Detailed descriptions +* Bug fixes section +* Organized by month +* Use when: Monthly platform updates ### Step 2: Gather information -**For content releases:** -- Publication date (YYYY-MM-DD) -- New/updated integrations (names and doc links) -- New playbooks (ID numbers and titles) -- Keywords (confirm with user; default: automation service, cloud soar, soar) +**For Content Release:** +* **Publication date**: Date in YYYY-MM-DD format +* **New integrations**: List of integrations to add +* **Updated integrations**: List of integrations to update +* **New playbooks**: List with ID numbers and titles (if any) -**For application updates:** -- Publication date (YYYY-MM-DD) — typically early the month following the release month -- Release month (e.g. "February" if published in March) -- Integration changes with descriptions -- Platform changes -- Bug fixes -- Keywords (confirm with user; default: automation service, cloud soar) +**For Application Update:** +* **Release month**: Which month is this release for? (e.g., "February") +* **Publication date**: Date in YYYY-MM-DD format (typically early next month) +* **Integration changes**: New or updated integrations with descriptions +* **Platform changes**: Platform features and improvements +* **Bug fixes**: List of bugs fixed -### Step 3: Create the file +**Keywords (for both types):** +* Ask user to confirm or customize keywords +* Suggested defaults (see frontmatter section below) -**File**: -- Content release: `blog-csoar/YYYY-MM-DD-content-release.md` -- Application update: `blog-csoar/YYYY-MM-DD-application-update.md` +**Validate:** +* Check that date is not in the future +* For Application Update: Ensure release month aligns with publication date +* Verify integration links are valid +* Confirm keywords with user before creating file -Always include `import useBaseUrl from '@docusaurus/useBaseUrl';` after frontmatter. +### Step 3: Create the markdown file -**Date format in title**: "Month DD, YYYY" — full month name, zero-padded day, no ordinal. -- ✅ "March 06, 2026" | ❌ "March 6, 2026" | ❌ "March 6th, 2026" +**File naming convention:** -**Integration doc path**: `/docs/platform-services/automation-service/app-central/integrations/{slug}/` +For Content Release: +``` +blog-csoar/YYYY-MM-DD-content-release.md +``` -If a file already exists, ask the user to use a different date or append. +For Application Update: +``` +blog-csoar/YYYY-MM-DD-application-update.md +``` ---- +Examples: +* `blog-csoar/2024-06-05-content-release.md` +* `blog-csoar/2026-03-06-application-update.md` + +**Important**: Files are created in `/blog-csoar/` directory (root level) -#### Content release +### Step 4: Generate frontmatter -**Frontmatter**: +**For Content Release:** ```yaml --- title: {Month DD, YYYY} - Content Release @@ -56,43 +144,87 @@ keywords: --- ``` -**Content**: -```markdown -This release introduces {what's new}. +**For Application Update:** +```yaml +--- +title: {Month DD, 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: + - automation service + - cloud soar +--- +``` -### Integrations +**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" -* [New] [Integration Name](/docs/platform-services/automation-service/app-central/integrations/{slug}/) -* [Updated] [Integration Name](/docs/platform-services/automation-service/app-central/integrations/{slug}/) +**Date formatting:** +* Use full month name (January, February, March, etc.) +* Use zero-padded day (01, 05, 06, 08, not 1, 5, 6, 8) -### Playbooks +**Keywords:** +* **Always ask user to confirm keywords before creating file** +* Suggested defaults: + * Content Release: `automation service`, `cloud soar`, `soar` (three keywords) + * Application Update: `automation service`, `cloud soar` (two keywords) +* User may want to add additional keywords based on specific content (e.g., `integrations`, `playbooks`, `api`, `platform`) + +**Image:** +* Both types use the same standard Sumo Logic preview image: + * `https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082` -* [New] {ID} - {Playbook Title} +### Step 5: Add required import + +**For both types**, add the useBaseUrl import after frontmatter: +```javascript +import useBaseUrl from '@docusaurus/useBaseUrl'; ``` -Integration entries are link-only — no descriptions. Playbooks section is optional. +### Step 6: Write content structure +**Content Release template:** +```markdown +--- +title: June 05, 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: + - automation service + - cloud soar + - soar --- -#### Application update +import useBaseUrl from '@docusaurus/useBaseUrl'; -Application Updates cover the previous month's changes. Filename and title use the publication date; the H2 header and intro use the release month. +This release introduces new integrations, new playbooks, and several updates. -**Frontmatter**: -```yaml +### Integrations + +* [New] [AWS WAF](/docs/platform-services/automation-service/app-central/integrations/aws-waf) +* [Updated] [Okta](/docs/platform-services/automation-service/app-central/integrations/okta) + +### Playbooks + +* [New] 541 - Management of AWS EKS Insights +* [New] 542 - Resolution of AWS EKS Insights +``` + +**Application Update template:** +```markdown --- -title: {Month DD, YYYY} - Application Update +title: March 06, 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: - automation service - cloud soar --- -``` -**Content**: -```markdown -## {Release month} release +import useBaseUrl from '@docusaurus/useBaseUrl'; + +## {Month} release Following are the updates made in {Month} {YYYY}. @@ -100,32 +232,374 @@ Following are the updates made in {Month} {YYYY}. #### Integrations -* [Added] [Integration Name](/docs/path/) - Description of what was added. -* [Updated] [Integration Name](/docs/path/) - Description of what was updated. +* [Added] [Integration Name](/docs/path/to/integration/) - Description of what was added. +* [Updated] [Integration Name](/docs/path/to/integration/) - Description of what was updated. + +#### Platform + +* Description of platform enhancement or feature. +* Description of another platform change. + +### Bug Fixes + +#### Integrations + +* In the [Integration Name](/docs/path/to/integration/) integration, description of bug fix. #### Platform -* Platform enhancement description. +Fixed an issue where [description of bug and fix]. +``` + +### Step 7: Content formatting guidelines + +## Content Release Formatting + +#### Intro Paragraph + +* Simple one-sentence description +* Format: "This release introduces {what's new}." +* Examples: + * "This release introduces new integrations, new playbooks, and several updates." + * "This release introduces new integrations and updates to existing integrations." + +#### Integrations Section (H3) + +* Simple bulleted list with [New] or [Updated] tags +* Format: `* [Tag] [Integration Name](link)` +* NO descriptions needed - just link to integration doc +* Links use full path: `/docs/platform-services/automation-service/app-central/integrations/{slug}` + +**Example:** +```markdown +### Integrations + +* [New] [AWS WAF](/docs/platform-services/automation-service/app-central/integrations/aws-waf) +* [New] [Cyberint](/docs/platform-services/automation-service/app-central/integrations/cyberint) +* [Updated] [Okta](/docs/platform-services/automation-service/app-central/integrations/okta) +* [Updated] [ServiceNow V2](/docs/platform-services/automation-service/app-central/integrations/servicenow-v2) +``` + +#### Playbooks Section (H3) + +* Optional - only if new playbooks released +* Format: `* [New] {ID} - {Playbook Title}` +* ID is a number (e.g., 541, 542, 543) +* Use "- " between ID and title + +**Example:** +```markdown +### Playbooks + +* [New] 541 - Management of AWS EKS Insights +* [New] 542 - Resolution of AWS EKS Insights +* [New] 543 - Alert and Vulnerability detection with Sysdig Secure +``` + +## Application Update Formatting + +#### Release Month Header (H2) + +* Always use H2 (`##`) for the month +* Format: "## {Month} release" +* Examples: "## February release", "## March release" +* Followed by: "Following are the updates made in {Month} {YYYY}." + +#### Changes and Enhancements Section + +**Integrations subsection:** +* Use tags: `[Added]` for new integrations, `[Updated]` for existing ones +* Format: `[Tag] [Integration Name](link) - Description.` +* Link to integration documentation in `/docs/platform-services/automation-service/app-central/integrations/` +* Be specific about what action or feature was added/updated +* Can mention specific actions: "Added 'Count Occurrence Of Value' action" + +**Example:** +```markdown +#### Integrations + +* [Added] [Sumo Logic Automation Tools](/docs/platform-services/automation-service/app-central/integrations/sumo-logic-automation-tools/) - Added "Count Occurrence Of Value" action to count the occurrence of a specified value in texts. +* [Updated] [ThreatConnect V3](/docs/platform-services/automation-service/app-central/integrations/threatconnect-v3/) - Added observations parameter to the Update Intelligence action to enable recording observation counts for indicators. +``` + +**Platform subsection:** +* List platform-wide changes or features +* Focus on user-facing improvements +* Can include UX enhancements, new APIs, or system improvements +* Use clear, simple language + +**Example:** +```markdown +#### Platform + +* Improved the sorting UX experience on all tables in Cloud SOAR and the Automation Service to align with other Sumo Logic modules. +* Deleted records will no longer be fetched during table searches unless the `Deleted` filter is applied. +* Added new public APIs: + * [Add playbooks to an incident](https://api.sumologic.com/docs/csoar/#operation/incidents_runbook_create). + * [Retrieve all playbooks attached to a specific incident](https://api.sumologic.com/docs/csoar/#operation/incidents_runbook_retrieve). +``` + +**Playbooks subsection (optional):** +* Only include if there are playbook-specific changes +* Format similar to platform changes +#### Bug Fixes Section + +* Group by subsection: Integrations, Platform, Playbooks +* For integrations: Start with "In the [Integration Name](link) integration, ..." +* For platform/playbooks: Use "Fixed an issue where..." or direct description +* Be specific about what was fixed + +**Example:** +```markdown ### Bug Fixes #### Integrations -* In the [Integration Name](/docs/path/) integration, description of fix. +* In the [Microsoft EWS (Graph)](/docs/platform-services/automation-service/app-central/integrations/microsoft-ews-graph/) integration, removed the default values for the `has_attachments` and `un_read` fields in the Search Emails Extended action. The change allows users to search for emails without being forced to filter by attachment status or read/unread status. #### Platform -Fixed an issue where {description}. +Fixed an issue where query filters were being applied incorrectly during search. + +#### Playbooks + +Fixed issues while selecting variables containing the period character in textarea fields and test node input. +``` + +### Step 8: Validation checklist + +**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") +* [ ] Image URL: Standard Sumo Logic preview image +* [ ] Keywords: automation service, cloud soar, soar (three keywords) +* [ ] `hide_table_of_contents: true` is present +* [ ] Import statement included +* [ ] Simple intro paragraph present +* [ ] Integrations section uses [New]/[Updated] tags +* [ ] Integration links have NO descriptions (just links) +* [ ] Playbooks section uses [New] with ID numbers (if included) +* [ ] No trailing whitespace + +**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") +* [ ] Image URL: Standard Sumo Logic preview image +* [ ] Keywords: automation service, cloud soar (two keywords) +* [ ] `hide_table_of_contents: true` is present +* [ ] Import statement included +* [ ] H2 header: "## {Month} release" +* [ ] Intro: "Following are the updates made in {Month} {YYYY}." +* [ ] Integration changes use [Added]/[Updated] WITH descriptions +* [ ] Integration links point to correct paths +* [ ] All sections properly formatted (H3 for main, H4 for subsections) +* [ ] No trailing whitespace + +## Example usage + +### Content Release Example + +``` +User: "Create a Cloud SOAR content release for June 5, 2024, with new AWS integrations and playbooks" + +Claude: +1. Confirms type: Content Release +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" + - image: Standard Sumo Logic preview image + - keywords: automation service, cloud soar, soar +5. Writes content with: + - Simple intro: "This release introduces new integrations, new playbooks, and several updates." + - Integrations section with [New]/[Updated] tags (no descriptions) + - Playbooks section with ID numbers +6. Provides checklist +``` + +### Application Update Example + ``` +User: "Create a Cloud SOAR release note for February 2026, published March 6, with integration updates and bug fixes" + +Claude: +1. Confirms type: Application Update +2. Confirms publication date: March 6, 2026 +3. Confirms release month: February +4. Creates: blog-csoar/2026-03-06-application-update.md +5. Generates frontmatter: + - title: "March 06, 2026 - Application Update" + - keywords: automation service, cloud soar +6. Writes content with: + - H2: "## February release" + - Intro: "Following are the updates made in February 2026." + - Changes and enhancements section (with descriptions) + - Bug fixes section +7. Provides checklist +``` + +## Integration documentation paths + +Integration docs are located at: +``` +/docs/platform-services/automation-service/app-central/integrations/{integration-slug}/ +``` + +**Common integrations:** +* Microsoft EWS (Graph): `/docs/platform-services/automation-service/app-central/integrations/microsoft-ews-graph/` +* ThreatConnect V3: `/docs/platform-services/automation-service/app-central/integrations/threatconnect-v3/` +* Atlassian Opsgenie: `/docs/platform-services/automation-service/app-central/integrations/atlassian-opsgenie/` +* Sumo Logic Automation Tools: `/docs/platform-services/automation-service/app-central/integrations/sumo-logic-automation-tools/` -Integration changes use `[Added]` for new integrations, `[Updated]` for existing — always include descriptions (unlike content releases). +**Tip**: Integration slugs are lowercase with hyphens. If unsure, use Grep to find the integration doc. -### Step 4: Validate +## API documentation links + +Cloud SOAR API docs: +* API reference: `https://api.sumologic.com/docs/csoar/` +* Cloud SOAR automation docs: `/docs/cloud-soar/automation/` + +## 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) + +**Examples:** +* ✅ March 06, 2026 +* ✅ January 08, 2026 +* ✅ December 31, 2025 +* ✅ June 05, 2024 +* ❌ March 6, 2026 (not zero-padded) +* ❌ March 6th, 2026 (has ordinal) +* ❌ Mar 06, 2026 (abbreviated month) +* ❌ 2026-03-06 (wrong format) + +## Release timing + +**Important**: Cloud SOAR release notes are typically published early the following month for the previous month's changes. + +**Pattern:** +* February changes → Published early March (e.g., March 6) +* January changes → Published early February +* December changes → Published early January + +**In the file:** +* Filename uses publication date: `2026-03-06-application-update.md` +* Title uses publication date: "March 6, 2026 - Application Update" +* H2 uses release month: "## February release" +* Intro uses release month: "Following are the updates made in February 2026." + +## Safety principles + +* **Check for existing files** before creating to avoid duplicates +* **Validate release month alignment** with publication date +* **Verify integration links** exist before including them +* **Use consistent formatting** for all integration changes +* **Include both keywords**. Automation service and cloud soar +* **Group bug fixes by category** for clarity +* **Keep descriptions concise** but informative + +## Post-completion message + +After successfully creating the release note, tell the user: + +``` +✅ Cloud SOAR release note created successfully! + +File created: +* 📄 blog-csoar/{YYYY-MM-DD}-application-update.md + +Summary: +* 📅 Publication: {Month Day, YYYY} +* 📆 Release month: {Month} +* 🔧 Integration updates: {count} +* 🐛 Bug fixes: {count} + +Next steps: +1. Review all integration links are correct +2. Verify bug fix descriptions are accurate +3. Ensure release month matches publication date +4. Test locally: yarn start +5. Check preview at: http://localhost:3000/release-notes-csoar +6. Submit PR: "DOCS-XXX - Cloud SOAR {Month} release notes" + +Checklist: +* [ ] Filename is {date}-application-update.md +* [ ] Title follows "Month Day, YYYY - Application Update" format +* [ ] H2 header is "## {Month} release" +* [ ] Integration changes use [Added]/[Updated] tags +* [ ] All integration links are valid +* [ ] Keywords include automation service and cloud soar +* [ ] Bug fixes grouped by category + +The release note will appear on the Cloud SOAR release notes page in reverse chronological order (newest first). + +Would you like me to help refine any sections or add additional details? +``` -- [ ] Filename uses full suffix (`-content-release.md` or `-application-update.md`) -- [ ] Title: "Month DD, YYYY" format (zero-padded, no ordinal) -- [ ] `import useBaseUrl` included -- [ ] `hide_table_of_contents: true` -- [ ] Keywords confirmed with user -- [ ] Application update: H2 header uses release month, not publication month -- [ ] No trailing whitespace +## Error handling + +**If file already exists:** +* Show existing file path and date +* Ask if user wants to: + * Update existing file (add more content) + * Use different date + * Create anyway (overwrite - requires confirmation) + +**If release month doesn't match date:** +* Warn user about mismatch +* Example: "March 6 publication should be for February release, not March" +* Ask for confirmation or correction + +**If integration link looks invalid:** +* Warn if doesn't follow standard path pattern +* Suggest searching for correct integration doc +* Proceed with user confirmation + +**If date is in the future:** +* Warn user and ask for confirmation +* Suggest using current date + +## Tips and best practices + +**For integration changes:** +* Be specific about what actions were added or updated +* Include the purpose or benefit of the change +* Always link to integration documentation +* Use [Added] for completely new integrations +* Use [Updated] for changes to existing integrations + +**For platform changes:** +* Focus on user-facing improvements +* Explain the benefit or impact +* Group related changes together +* Include API links when relevant + +**For bug fixes:** +* Clearly describe what was fixed +* Explain the previous behavior and new behavior +* Group by category for organization + +**All sections:** +* Keep language clear and concise +* Focus on what changed and why it matters +* Use bullet points for easy scanning +* Maintain consistent formatting + +## References + +* [Cloud SOAR Release Notes](https://sumologic.com/help/release-notes-csoar) +* [Cloud SOAR Documentation](/docs/cloud-soar) +* [Automation Service](/docs/platform-services/automation-service) +* [App Central Integrations](/docs/platform-services/automation-service/app-central/integrations) +* [Style Guide](/docs/contributing/style-guide) diff --git a/.claude/commands/release-note-developer.md b/.claude/commands/release-note-developer.md index 50913bc53f..8b11cce1d0 100644 --- a/.claude/commands/release-note-developer.md +++ b/.claude/commands/release-note-developer.md @@ -1,31 +1,84 @@ # Create New Developer Release Note -Creates a Developer release note for API changes, SDK updates, deprecations, CLI updates, or other developer-facing platform changes. +Automates the creation of Developer release notes for APIs, SDKs, integrations, and platform changes relevant to developers. + +## What this command does + +When you invoke `release-note-developer`, Claude will guide you through: + +1. **Gather release details**. Category, date, title, and content +2. **Create markdown file**. Generate file with proper frontmatter and structure +3. **Format content**. Apply correct formatting for the release type +4. **Validate and preview**. Check structure and provide next steps + +## When to use this command + +* Announcing new API endpoints or features +* Documenting API changes, deprecations, or breaking changes +* Publishing SDK updates or new SDK versions +* Releasing developer tools or CLI updates +* Announcing platform changes affecting developers +* Documenting authentication or integration changes +* Publishing deprecation notices + +## Release categories + +Developer release notes typically cover: + +* **APIs**. New endpoints, changes, deprecations +* **SDKs**. New SDKs, version updates, improvements +* **CLI**. Command-line tool updates +* **Integrations**. New integrations or integration changes +* **Platform**. Platform changes affecting developers +* **Security**. Authentication, authorization changes +* **Deprecations**. End-of-life announcements ## Workflow ### Step 1: Gather information Ask the user for: -- **Title/topic**: brief description (e.g. "New Field Extraction Rules API", "Deprecation of India Data Center") -- **Release date**: YYYY-MM-DD format -- **Content**: what changed, why it matters, impact on existing users -- **Doc links**: relative paths to relevant docs -- **Keywords**: optional; ask the user — suggest based on content type: - - API changes: `api`, `endpoints` - - SDK updates: `sdk`, `python`, `java`, etc. - - Deprecations: `deprecation`, `end-of-life` - - Breaking changes: `breaking-change` -### Step 2: Create the file +**Required:** +* **Title/Topic**: Brief description of what this release is about +* **Release date**: Date in YYYY-MM-DD format +* **Content**: The release note content (what changed, why it matters) -**File**: `blog-developer/YYYY-MM-DD-{slug}.md` +**Optional:** +* **Impact level**: Breaking change, deprecation, new feature, minor change +* **Documentation links**: Related doc pages +* **Slug**: Custom slug for filename (auto-generated from title if not provided) +* **Keywords**: Custom keywords for frontmatter (suggest defaults based on content) -Slug: lowercase, hyphens, 3–5 words. Examples: `api-endpoints`, `india-datacenter-deprecation`, `python-sdk-v2`. +**Validate:** +* Check that date is not in the future +* Ensure content is clear and concise +* Verify any doc links are valid relative paths +* Ask user to confirm keywords before creating file -If a file already exists, ask the user to use a different date or a more specific slug. +### Step 2: Create the markdown file -**Frontmatter**: +**File naming convention:** +``` +blog-developer/YYYY-MM-DD-{slug}.md +``` + +**Slug generation:** +* Lowercase the title +* Replace spaces with hyphens +* Remove special characters +* Keep concise (3-5 words max) + +Examples: +* `blog-developer/2026-03-23-api-endpoints.md` +* `blog-developer/2026-04-09-india-datacenter-deprecation.md` +* `blog-developer/2026-05-15-python-sdk-v2.md` + +**Important**: Files are created in `/blog-developer/` directory (root level, no subdirectories) + +### Step 3: Generate frontmatter + +**Standard frontmatter:** ```yaml --- title: {Month Day, YYYY} - {Topic} @@ -34,30 +87,418 @@ hide_table_of_contents: true --- ``` -**Title format**: "Month Day, YYYY - Topic" — full month name, no ordinal. -- ✅ "April 9, 2025" | ❌ "April 9th, 2025" | ❌ "Apr 9, 2025" +**Title formatting:** +* Start with full date: "Month Day, YYYY" (e.g., "April 9, 2025") +* Follow with " - " separator +* Add topic in Title Case (e.g., "Deprecation of Sumo Logic India Data Center") +* Keep topic concise but descriptive -Add `keywords` to frontmatter only if the user wants them. +**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" -**Content**: +**Image:** +* Always use the standard Sumo Logic preview image +* URL: `https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082` + +**Keywords (optional but recommended):** +* **Always ask user if they want to include keywords** +* Suggest keywords based on content type: + * API changes: `api`, `endpoints`, `rest-api` + * SDK updates: `sdk`, `python`, `java`, etc. + * Deprecations: `deprecation`, `end-of-life` + * Breaking changes: `breaking-change` + * Platform updates: `platform`, `datacenter` +* Format: + ```yaml + keywords: + - api + - deprecation + ``` +* User can choose to omit keywords or customize the list + +### Step 4: Add optional import + +For release notes that use links or useBaseUrl: +```javascript +import useBaseUrl from '@docusaurus/useBaseUrl'; +``` + +**Note**: Only add if content uses it. For simple text-only releases, omit. + +**Title guidelines:** +* Keep concise (2-5 words) +* Use title case +* Common patterns: "APIs", "SDKs", "CLI Tools", "Platform Updates" +* Can be more specific: "Python SDK", "REST API", "Management APIs" + +### Step 5: Write content + +Content goes directly after frontmatter (and optional import). No H3 heading needed — the title is in frontmatter. + +**Basic structure:** ```markdown -{Main paragraph — what changed, why it matters} +--- +title: March 23, 2026 - New Field Extraction Rules API +image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 +hide_table_of_contents: true +--- -#### {Subsection if needed} +{Main content paragraph(s)} -* {Item} +{Optional: H4 sections for subsections} + +{Optional: code blocks, lists, links} + +{Optional: admonitions for important notes} ``` -- H4 (`####`) for subsections (new endpoints, breaking changes, migration steps, etc.). -- Use `:::warning` admonitions for breaking changes. -- Doc links always use relative paths (`/docs/...`). -- Only add `import useBaseUrl` if content uses images. +### Step 6: Content formatting guidelines + +#### API Changes + +For API announcements, include: +* What changed (new endpoints, parameters, behavior) +* Impact on existing integrations +* Links to API documentation +* Migration guidance if breaking change + +**Example:** +```markdown +--- +title: March 23, 2026 - New Field Extraction Rules API +image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 +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 endpoints + +* **Field Extraction Rules API**: Create and manage Field Extraction Rules programmatically. See [Field Extraction Rules API](/docs/api/field-extraction-rules). +* **Webhook Connections API**: Create and manage webhook connections via API. See [Connections API](/docs/api/connections). + +#### Breaking changes + +**Monitors API**: The `notificationGroupFields` parameter is now required when creating monitors. Update your integrations before June 1, 2026. See the [Monitors API documentation](/docs/api/monitors) for details. +``` + +#### SDK Updates + +For SDK releases: +* Version number +* What's new or changed +* Installation instructions +* Link to SDK docs or GitHub + +**Example:** +```markdown +--- +title: March 23, 2026 - Python SDK Version 2.0 +image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 +hide_table_of_contents: true +keywords: + - sdk + - python +--- + +We've released version 2.0 of the Sumo Logic Python SDK with support for the latest APIs and improved error handling. + +#### What's new + +* Support for Field Extraction Rules API +* Async client support for better performance +* Improved error messages and debugging + +#### Installation + +```python +pip install sumologic-sdk==2.0.0 +``` + +Learn more in the [Python SDK documentation](/docs/api/python-client). +``` + +#### Deprecations + +For deprecation notices: +* What's being deprecated +* Why it's being deprecated (optional, if relevant) +* When it will be removed (end-of-life date) +* Migration path or alternatives +* Impact on existing users + +**Example (matches your template):** +```markdown +--- +title: April 9, 2025 - Deprecation of Sumo Logic India Data Center +image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 +hide_table_of_contents: true +keywords: + - deprecation + - datacenter +--- + +As previously communicated to impacted customers, effective as of April 30, 2025, customers will no longer be able to ingest data into the Sumo Logic Mumbai data center (`https://api.in.sumologic.com/`). Customers will retain access to historical data and basic search functionality until April 30, 2026, at which point all access will be terminated. + +Historical data will not be migrated to other deployments. + +**Reminder**: If you're still referencing the India endpoint, please update your integrations. For supported alternatives, see the [endpoint guide](/docs/api/about-apis/getting-started/#sumo-logic-endpoints-by-deployment-and-firewall-security). + +For help, contact [Support](https://support.sumologic.com/). +``` + +**Example (API deprecation):** +```markdown +--- +title: March 23, 2026 - Legacy Metrics API Deprecation +image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 +hide_table_of_contents: true +keywords: + - api + - deprecation +--- + +Effective **September 30, 2026**, the following legacy metrics API endpoints will be retired: +* `/v1/metrics/query` (use `/v2/metrics/query` instead) +* `/v1/metrics/catalog` (use `/v2/metrics/catalog` instead) + +**Migration**: Update your integrations to use the v2 endpoints. See the [Metrics API migration guide](/docs/api/metrics-migration) for details. + +**Impact**: After September 30, 2026, requests to legacy endpoints will return HTTP 410 (Gone). + +For help, contact [Support](https://support.sumologic.com/). +``` + +#### Minor Changes + +For small updates or enhancements: +* Brief description of the change +* Link to relevant docs +* Optional impact note + +**Example:** +```markdown +--- +title: March 23, 2026 - API Enhancements +image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 +hide_table_of_contents: true +--- + +We've made the following improvements to our APIs: + +* **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. +``` + +### Step 7: Validation checklist + +Before finishing, verify: +* [ ] File created in `/blog-developer/` directory (root level) +* [ ] Filename follows pattern: `YYYY-MM-DD-{slug}.md` +* [ ] Frontmatter complete with all required fields +* [ ] Title starts with "Month Day, YYYY - " format +* [ ] Date format uses full month name, no ordinal (e.g., "April 9" not "April 9th") +* [ ] `hide_table_of_contents: true` is present +* [ ] Standard image URL is used +* [ ] Content is clear and includes relevant links +* [ ] Breaking changes are clearly marked (use bold or H4 sections) +* [ ] Documentation links use relative paths (start with `/docs/`) +* [ ] Keywords added if applicable (deprecation, api, sdk, etc.) +* [ ] No trailing whitespace + +## Example usage + +### API Feature Example + +``` +User: "Create a developer release note for new Field Extraction Rules API endpoints, dated March 23, 2026" + +Claude: +1. Confirms date: March 23, 2026 +2. Generates slug: "field-extraction-rules-api" +3. Creates: blog-developer/2026-03-23-field-extraction-rules-api.md +4. Generates frontmatter: + - title: "March 23, 2026 - New Field Extraction Rules API" + - image: Standard Sumo Logic image + - hide_table_of_contents: true +5. Writes content with: + - Description of new endpoints + - Link to API documentation + - Impact notes +6. Provides checklist +``` + +### Deprecation Example + +``` +User: "Create a deprecation notice for Sumo Logic India Data Center, dated April 9, 2025" + +Claude: +1. Confirms date: April 9, 2025 +2. Generates slug: "india-datacenter-deprecation" +3. Creates: blog-developer/2025-04-09-india-datacenter-deprecation.md +4. Generates frontmatter: + - title: "April 9, 2025 - Deprecation of Sumo Logic India Data Center" + - keywords: deprecation, datacenter +5. Writes content with: + - What's being deprecated + - Timeline and dates + - Migration guidance + - Support contact +6. Provides checklist +``` + +## 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) + +**Examples:** +* ✅ March 23, 2026 +* ✅ January 1, 2026 +* ✅ December 31, 2025 +* ❌ March 23rd, 2026 (no ordinal) +* ❌ Mar 23, 2026 (abbreviated month) +* ❌ 2026-03-23 (wrong format) + +## Content formatting guidelines + +**Use formatting for clarity:** +* Use **bold** for important terms or breaking changes +* Use H4 sections (`####`) for subsections when needed +* Use bullet lists for multiple related items +* Use admonitions (`:::note`, `:::warning`) for important callouts + +**Example:** +```markdown +#### Breaking changes + +**Monitors API**: The `notificationGroupFields` parameter is now required when creating monitors. Update your integrations before June 1, 2026. + +:::warning +This is a breaking change. Existing integrations must be updated by June 1, 2026. +::: + +**Links:** +* Always use relative paths starting with `/docs/` +* Use descriptive link text (not "click here") +* Example: `[Metrics API documentation](/docs/api/metrics)` + +**Code blocks:** +* Use appropriate language tags (```python, ```bash, ```json) +* Keep examples concise and relevant +* Show before/after for migration guides + +## Safety principles + +* **Check for existing files** before creating to avoid duplicates +* **Use clear, descriptive slugs** that indicate content +* **Validate dates**. Ensure date is not in future +* **Include documentation links**. Help users find more info +* **Mark breaking changes clearly**. Use bold text or H4 sections +* **Use standard frontmatter**. Consistent image URL and structure +* **Keep content focused**. One topic per release note + +## Post-completion message + +After successfully creating the release note, tell the user: + +``` +✅ Developer release note created successfully! + +File created: +* 📄 blog-developer/{YYYY-MM-DD-slug}.md + +Summary: +* 📅 Title: {Month Day, YYYY} - {Topic} +* 📝 {Brief summary of content} +* 🏷️ Keywords: {keywords if added} + +Next steps: +1. Review content for accuracy and clarity +2. Verify documentation links are correct +3. Ensure breaking changes are clearly marked +4. Test locally: yarn start +5. Check preview at: http://localhost:3000/release-notes-developer +6. Submit PR: "DOCS-XXX - Developer release note: {Topic}" + +Checklist: +* [ ] Title format is correct (Month Day, YYYY - Topic) +* [ ] Date uses full month name, no ordinal +* [ ] Standard image URL is used +* [ ] hide_table_of_contents: true is present +* [ ] Documentation links use relative paths +* [ ] Breaking changes clearly marked +* [ ] Content is clear and concise + +The release note will appear on the Developer release notes page in reverse chronological order (newest first). + +Would you like me to help refine the content or add additional details? +``` + +## Error handling + +**If file already exists:** +* Show existing file path and creation date +* Ask if user wants to: + * Use different slug (e.g., add `-v2` or more specific topic) + * Use different date + * Overwrite (requires explicit confirmation) + +**If date is in the future:** +* Warn user and ask for confirmation +* Suggest using current date + +**If slug is too generic:** +* Warn if slug is too short or vague (e.g., "api", "update") +* Suggest more descriptive slug (e.g., "field-extraction-rules-api") + +**If documentation link looks invalid:** +* Warn if doesn't start with `/docs/` +* Suggest correction +* Proceed with user confirmation + +**If content is too long:** +* Suggest breaking into subsections (H4) +* Recommend creating separate doc page and linking to it from release note + +## Tips and best practices + +**For API changes:** +* Be specific about what endpoints changed +* Include examples of new request/response formats +* Provide migration timeline for breaking changes +* Link to comprehensive API documentation + +**For deprecations:** +* Give ample notice (3-6 months minimum) +* Clearly state end-of-life date +* Provide migration path with examples +* Offer support contact for questions + +**For SDK releases:** +* Include version number prominently +* Show installation/upgrade commands +* Highlight breaking changes separately +* Link to changelog or GitHub release + +**All release notes:** +* Write for developers (assume technical knowledge) +* Focus on impact and action items +* Use clear, direct language +* Provide links for more information +* Keep entries concise but complete -### Step 3: Validate +## References -- [ ] `blog-developer/YYYY-MM-DD-{slug}.md` -- [ ] Title: "Month Day, YYYY - Topic" (no ordinal) -- [ ] `hide_table_of_contents: true` -- [ ] Breaking changes clearly marked -- [ ] Doc links use relative paths -- [ ] No trailing whitespace +* [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) diff --git a/.claude/commands/release-note-service.md b/.claude/commands/release-note-service.md index 09ca45aff9..4126e3a28b 100644 --- a/.claude/commands/release-note-service.md +++ b/.claude/commands/release-note-service.md @@ -1,57 +1,474 @@ # Create New Service Release Note -Creates a Service release note for a new feature, update, or improvement across Sumo Logic platform categories. +Automates the creation of Service release notes for new features, updates, and improvements across Sumo Logic platform categories. + +## What this command does + +When you invoke `release-note-service`, Claude will guide you through: + +1. **Determine category**. Apps, Manage, Collection, Search, or UI +2. **Gather release details**. Feature name, description, and changes +3. **Create markdown file**. Generate file with proper frontmatter and structure +4. **Format content**. Apply correct formatting for the feature announcement +5. **Validate and preview**. Check structure and provide next steps + +## When to use this command + +* Announcing new platform features or capabilities +* Documenting updates to existing features +* Publishing UI improvements and enhancements +* Releasing new collection methods or integrations +* Announcing management and admin features +* Publishing app-related updates + +## Categories + +Service release notes are organized by platform area: + +* **Apps**. App-related features and updates +* **Collection**. Data collection features, sources, authentication +* **Manage**. Management and administration features +* **Search**. Search features, queries, analytics +* **UI**. User interface updates and improvements (often labeled "New UI") ## Workflow ### Step 1: Gather information Ask the user for: -- **Category**: apps, collection, manage, search, or ui -- **Feature name**: brief, descriptive name -- **Release date**: YYYY-MM-DD format -- **Description**: 2–3 sentences — what the feature is and why it matters -- **Doc link**: relative path (optional) -- **"What's new" bullets**: optional, for multiple specific changes -- **Keywords**: confirm with user before creating file -### Step 2: Create the file +**Required:** +* **Category**: Which platform area (apps, collection, manage, search, ui) +* **Feature name**: Brief, descriptive name of the feature or update +* **Release date**: Date in YYYY-MM-DD format +* **Description**: What the feature does and why it matters (2-3 sentences) + +**Optional:** +* **Documentation link**: Relative path to the doc (e.g., `/docs/manage/...`) +* **"What's new" details**: Bulleted list of specific changes or capabilities +* **Keywords**: Custom keywords for frontmatter (suggest defaults based on content) -**File**: `blog-service/YYYY-MM-DD-{category}.md` +**Validate:** +* Check that date is not in the future +* Ensure category is valid (apps, collection, manage, search, ui) +* Verify documentation link is valid relative path if provided +* Ask user to confirm keywords before creating file -If a file already exists for the same date and category, ask the user to use a different date, append to the existing file, or add a more specific suffix. +### Step 2: Create the markdown file -**Frontmatter**: +**File naming convention:** +``` +blog-service/YYYY-MM-DD-{category}.md +``` + +Examples: +* `blog-service/2026-03-20-collection.md` +* `blog-service/2026-03-18-apps.md` +* `blog-service/2026-02-12-ui.md` + +**Important**: Files are created in `/blog-service/` directory + +**Note on file conflicts**: If a file already exists for the same date and category, ask the user: +* Use a different date +* Append to existing file (if related features) +* Use more specific category suffix (e.g., `-collection-m365` if needed) + +### Step 3: Generate frontmatter + +**Standard frontmatter:** ```yaml --- -title: {Feature Description} ({Category Label}) +title: {Feature Description} ({Category}) image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 keywords: - {keyword1} + - {keyword2} hide_table_of_contents: true --- ``` -**Title**: Feature description in Title Case + category label in parentheses. No date in title. -- apps → (Apps) | collection → (Collection) | manage → (Manage) | search → (Search) | ui → (New UI) +**Title formatting:** +* Feature description in Title Case +* Category in parentheses: (Apps), (Collection), (Manage), (Search), (New UI) +* NO date in title (unlike other release note types) +* Keep concise but descriptive +* Examples: + * "App Registration Authentication for Microsoft 365 Audit Source (Collection)" + * "Data Volume for MSSP (Apps)" + * "Content Item Actions Available Directly From Navigation Menus (New UI)" + +**Category labels in titles:** +* apps → (Apps) +* collection → (Collection) +* manage → (Manage) +* search → (Search) +* ui → (New UI) + +**Image:** +* Always use the standard Sumo Logic preview image +* URL: `https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082` + +**Keywords:** +* **Always ask user to confirm keywords before creating file** +* Suggest keywords based on content: + * Feature-specific terms (e.g., "Microsoft 365 Audit", "authentication") + * Category keywords (e.g., "apps", "ui", "collection") + * Product names or technologies mentioned +* Format: + ```yaml + keywords: + - keyword1 + - keyword2 + ``` +* User can customize the list + +### Step 4: Add optional import + +For release notes that use links or useBaseUrl: +```javascript +import useBaseUrl from '@docusaurus/useBaseUrl'; +``` + +**Note**: Only add if content uses it. For simple text-only releases, omit. + +### Step 5: Write content -**Content**: +Content goes directly after frontmatter (and optional import). No H3 heading needed — the title is in frontmatter. + +**Basic structure:** ```markdown -{Description — what the feature is and why it matters} +--- +title: Feature Name (Category) +image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 +keywords: + - keyword1 + - keyword2 +hide_table_of_contents: true +--- + +{Description paragraph explaining the feature and its benefits} + +{Optional: What's new section with bulleted list} + +{Optional: Documentation links} +``` + +#### Simple Feature Announcement + +For straightforward feature updates: +```markdown +--- +title: App Registration Authentication for Microsoft 365 Audit Source (Collection) +image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 +keywords: + - Microsoft 365 Audit + - authentication +hide_table_of_contents: true +--- + +The Microsoft 365 Audit Source now supports the App Registration authentication method. This enhancement allows organizations to authenticate using Azure Active Directory App Registrations, providing a more secure and flexible authentication option for collecting Microsoft 365 audit logs. + +[Learn more](/docs/send-data/hosted-collectors/cloud-to-cloud-integration-framework/microsoft-365-audit-source/). +``` + +#### Feature with "What's new" Section + +For features with multiple specific changes: +```markdown +--- +title: Content Item Actions Available Directly From Navigation Menus (New UI) +image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 +keywords: + - ui +hide_table_of_contents: true +--- + +You can now perform common actions on content items directly from the navigation menus in the left-hand sidebar, making it faster and easier to manage your content without opening each item. **What's new:** -* {Specific capability} +* Right-click on any content item in the sidebar to access a context menu +* Available actions: Open, Open in New Tab, Copy, Move, Delete, Share, Schedule Report +* Works for dashboards, searches, folders, and other content items +* Same functionality as the Actions menu in the Content Library -[Learn more](/docs/path/to/doc). +This enhancement streamlines your workflow by providing quick access to frequently used actions. [Learn more](/docs/get-started/library/). ``` -"What's new:" is optional — use for multiple specific changes, omit for single-point announcements. Only add `import useBaseUrl` if the content uses it. +### Step 6: Content formatting guidelines + +**Write for clarity:** +* Start with a clear statement of what the feature is +* 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 + +**Use formatting for readability:** +* Use **bold** for section labels like "What's new:" +* Use bullet lists for multiple related items +* Use admonitions (`:::note`, `:::warning`) for important callouts if needed +* Keep paragraphs concise (2-4 sentences max) + +**Links:** +* Always use relative paths starting with `/docs/` +* Use descriptive link text (typically "Learn more") +* Example: `[Learn more](/docs/send-data/...)` + +**Examples by category:** + +**Apps:** +```markdown +--- +title: Data Volume for MSSP (Apps) +image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 +keywords: + - data-volume-for-mssp + - apps +hide_table_of_contents: true +--- + +The Data Volume for MSSP app is now available, providing managed security service providers with visibility into data usage across multiple customer accounts. This app helps MSSPs track, analyze, and optimize data ingestion to improve cost management and capacity planning. + +[Learn more](/docs/integrations/sumo-apps/data-volume-for-mssp). +``` + +**Collection:** +```markdown +--- +title: Enhanced Authentication Options for Cloud Sources (Collection) +image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 +keywords: + - authentication + - cloud-to-cloud + - collection +hide_table_of_contents: true +--- + +Cloud-to-Cloud sources now support additional authentication methods including OAuth 2.0 client credentials flow and service account authentication. These new options provide more flexibility for enterprise customers to integrate with cloud services using their preferred authentication standards. + +**What's new:** +* OAuth 2.0 client credentials flow for machine-to-machine authentication +* Service account support for Google Cloud and AWS integrations +* Enhanced security with token rotation and expiration handling +* Backward compatible with existing authentication methods + +[Learn more](/docs/send-data/hosted-collectors/cloud-to-cloud-integration-framework/). +``` + +**UI:** +```markdown +--- +title: Improved Dashboard Loading Performance (New UI) +image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 +keywords: + - ui + - dashboards + - performance +hide_table_of_contents: true +--- + +Dashboards now load up to 50% faster in the new UI through optimized query execution and progressive rendering. Large dashboards with many panels will see the most significant improvements, reducing wait times and improving the overall user experience. +``` + +### Step 7: Validation checklist + +Before finishing, verify: +* [ ] File created in `/blog-service/` directory +* [ ] Filename follows pattern: `YYYY-MM-DD-{category}.md` +* [ ] Frontmatter complete with all required fields +* [ ] Title includes feature description and category in parentheses +* [ ] Title does NOT include date +* [ ] `hide_table_of_contents: true` is present +* [ ] Standard image URL is used +* [ ] Keywords confirmed with user +* [ ] Category label uses correct format: (Apps), (Collection), (Manage), (Search), (New UI) +* [ ] Content is clear and focused on user benefits +* [ ] Documentation link uses relative path (starts with `/docs/`) +* [ ] No trailing whitespace + +## Example usage + +### Collection Feature Example + +``` +User: "Create a Service release note for Microsoft 365 Audit Source App Registration authentication, collection category, dated March 20, 2026" + +Claude: +1. Confirms category: Collection +2. Confirms date: 2026-03-20 +3. Asks for keywords (suggests: "Microsoft 365 Audit", "authentication") +4. Creates: blog-service/2026-03-20-collection.md +5. Generates frontmatter: + - title: "App Registration Authentication for Microsoft 365 Audit Source (Collection)" + - keywords: Microsoft 365 Audit, authentication +6. Writes content with: + - Description of new authentication method + - Business value + - Link to documentation +7. Provides checklist +``` + +### UI Feature Example + +``` +User: "Create a Service release note for new context menu actions in the sidebar, UI category, dated February 12, 2026" + +Claude: +1. Confirms category: UI +2. Confirms date: 2026-02-12 +3. Asks for keywords (suggests: "ui", "navigation") +4. Creates: blog-service/2026-02-12-ui.md +5. Generates frontmatter: + - title: "Content Item Actions Available Directly From Navigation Menus (New UI)" + - keywords: ui +6. Writes content with: + - Feature description + - "What's new" section with bullets + - Link to documentation +7. Provides checklist +``` + +## Category guidelines + +**Apps**. Use for: +* New apps or app updates +* App integrations +* App-specific features +* MSSP or multi-tenant features + +**Collection**. Use for: +* New sources or source types +* Collection authentication changes +* Collector features +* Data ingestion enhancements + +**Manage**. Use for: +* Account management features +* User and role management +* Security and compliance features +* Settings and configuration updates + +**Search**. Use for: +* Search language enhancements +* Query performance improvements +* Analytics features +* Data parsing updates + +**UI**. Use for: +* User interface changes +* Navigation improvements +* Visual design updates +* Workflow enhancements +* Label as "(New UI)" in title + +## Safety principles + +* **Check for existing files** before creating (same date + category = conflict) +* **Validate category** is one of: apps, collection, manage, search, ui +* **Use clear, descriptive titles** that explain the feature +* **Include documentation links**. Help users find more info +* **Use standard frontmatter**. Consistent image URL and structure +* **Keep content focused**. One feature per release note +* **Always ask user to confirm keywords** before creating file + +## Post-completion message + +After successfully creating the release note, tell the user: + +``` +✅ Service release note created successfully! + +File created: +* 📄 blog-service/{YYYY-MM-DD-category}.md + +Summary: +* 📋 Category: {Category} +* 📝 Title: {Feature Description} ({Category}) +* 🏷️ Keywords: {keywords} + +Next steps: +1. Review content for accuracy and clarity +2. Verify documentation link is correct +3. Ensure keywords are appropriate +4. Test locally: yarn start +5. Check preview at: http://localhost:3000/release-notes-service +6. Submit PR: "DOCS-XXX - Service release note: {Feature Description}" + +Checklist: +* [ ] Title format is correct (Feature Description (Category)) +* [ ] Title does NOT include date +* [ ] Category label uses correct format +* [ ] Standard image URL is used +* [ ] hide_table_of_contents: true is present +* [ ] Documentation link uses relative path +* [ ] Content is clear and concise +* [ ] Keywords confirmed with user + +The release note will appear on the Service release notes page in reverse chronological order (newest first). + +Would you like me to help refine the content or add additional details? +``` + +## Error handling + +**If file already exists:** +* Show existing file path and creation date +* Ask if user wants to: + * Use different date + * Append to existing file (if related features) + * Use more specific category suffix (e.g., `-collection-m365`) + * Overwrite (requires explicit confirmation) + +**If date is in the future:** +* Warn user and ask for confirmation +* Suggest using current date + +**If category is invalid:** +* Show error: "Category must be one of: apps, collection, manage, search, ui" +* Ask user to select valid category + +**If documentation link looks invalid:** +* Warn if doesn't start with `/docs/` +* Suggest correction +* Proceed with user confirmation + +**If title is too long:** +* Warn if title exceeds 100 characters +* Suggest shorter, more concise wording +* Category label must stay in title + +**If keywords not confirmed:** +* Do not create file until user confirms keywords +* Show suggested keywords and wait for approval/modification + +## Tips and best practices + +**For all Service releases:** +* 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 + +**Title guidelines:** +* Be specific about the feature (not "New Collection Feature") +* Use active language ("Enhanced...", "New...", "Improved...") +* Include category in parentheses at end +* No date in title (unlike other release types) +* Keep under 100 characters including category + +**Content structure:** +* First paragraph: What is it and why does it matter? +* Optional "What's new" section: Specific capabilities or changes +* Final element: "Learn more" link to docs + +**Keywords:** +* Include feature-specific terms +* Add category keyword (apps, ui, collection, etc.) +* Mention product names or technologies +* Keep list focused (2-5 keywords) -### Step 3: Validate +## References -- [ ] `blog-service/YYYY-MM-DD-{category}.md` -- [ ] Title: feature description + category label in parens, no date -- [ ] `hide_table_of_contents: true` -- [ ] Keywords confirmed with user -- [ ] Doc link uses `/docs/...` relative path -- [ ] No trailing whitespace +* [Service Release Notes](https://sumologic.com/help/release-notes-service) +* [Release Notes Index](/docs/release-notes) +* [Style Guide](/docs/contributing/style-guide) From 606c6b6bfe6d37ef6e8937c81778c85847aed853 Mon Sep 17 00:00:00 2001 From: Kim Pohas Date: Fri, 5 Jun 2026 00:54:32 -0700 Subject: [PATCH 06/22] revert --- .claude/commands/audit-doc.md | 21 ++++++ .claude/commands/doc-from-jira.md | 18 +++++ .claude/commands/doc.md | 22 +++++- .claude/commands/geo-optimize.md | 18 +++++ .claude/commands/remove-doc.md | 63 ++++++++++++++++ .claude/commands/review.md | 115 ------------------------------ .claude/commands/seo-audit.md | 17 +---- CLAUDE.md | 1 - 8 files changed, 143 insertions(+), 132 deletions(-) delete mode 100644 .claude/commands/review.md diff --git a/.claude/commands/audit-doc.md b/.claude/commands/audit-doc.md index 46312d92e4..b17f5dd32c 100644 --- a/.claude/commands/audit-doc.md +++ b/.claude/commands/audit-doc.md @@ -2,6 +2,27 @@ Performs comprehensive quality checks on documentation files to ensure adherence to Sumo Logic style guidelines, proper structure, and completeness. +## What this command does + +When you invoke `/audit-doc`, Claude will: + +1. **Read and analyze the specified doc file** +2. **Check frontmatter**. Validate required fields and format +3. **Review content structure**. Check headings, sections, and organization +4. **Validate links and images**. Check paths, alt text, and references +5. **Check style adherence**. Apply Sumo Logic style guide rules +6. **Report findings**. Provide detailed feedback with specific line numbers +7. **Suggest fixes**. Offer actionable recommendations + +## When to use this command + +* Before submitting a PR to check doc quality +* After creating a new doc to validate structure +* When updating existing docs to ensure consistency +* To identify broken links or missing images +* To verify adherence to Sumo Logic style guidelines +* When reviewing community contributions + ## Workflow ### Step 1: Identify the doc to audit diff --git a/.claude/commands/doc-from-jira.md b/.claude/commands/doc-from-jira.md index 3873aeb2bd..3e06303350 100644 --- a/.claude/commands/doc-from-jira.md +++ b/.claude/commands/doc-from-jira.md @@ -2,6 +2,24 @@ Pulls a Jira ticket from the DOCS project, extracts the content requirements, and scaffolds a fully structured documentation file ready for writing. Eliminates the blank-page problem and keeps the doc aligned with the ticket spec from the start. +## What this command does + +When you invoke `/doc-from-jira`, Claude will: + +1. **Fetch the Jira ticket**. Pull title, description, acceptance criteria, and linked resources +2. **Determine doc type**. Feature, how-to, concept, reference, or troubleshooting +3. **Infer the file path**. Based on the technical area and content type +4. **Scaffold the doc**. Generate a file with correct frontmatter, structure, and placeholder sections pre-populated from the ticket +5. **Update sidebars.ts**. Add the new doc to navigation (with user approval) +6. **Link back to Jira**. Set the Jira ticket to In Progress if not already + +## When to use this command + +* Starting a new doc for a DOCS ticket +* When a ticket has a detailed description or acceptance criteria worth preserving +* For tickets with linked specs, PRDs, or engineering docs to pull context from +* When you want to ensure the doc structure is aligned with what was requested + ## When NOT to use this command * **App integrations** — use `/app-doc` instead diff --git a/.claude/commands/doc.md b/.claude/commands/doc.md index aa72e99dc2..e5f3fb9bbc 100644 --- a/.claude/commands/doc.md +++ b/.claude/commands/doc.md @@ -2,11 +2,31 @@ Automates the creation of general Sumo Logic documentation for features, how-tos, concepts, reference pages, and troubleshooting guides. +## What this command does + +When you invoke `doc`, Claude will guide you through: + +1. **Determine doc type**. Feature, how-to, concept, reference, or troubleshooting. +2. **Gather information**. Title, description, file path, and keywords. +3. **Create markdown file**. Generate file with proper frontmatter and basic structure. +4. **Add to navigation**. Guide on adding to sidebars.ts. +5. **Add to hub page**. Suggest adding card to parent index page. +6. **Create CID mapping**. Add permanent URL if needed for UI links. +7. **Validate and preview**. Check structure and provide next steps. + +## When to use this command + +* Creating feature documentation. +* Writing how-to guides and tutorials. +* Documenting concepts and reference material. +* Creating troubleshooting guides. +* Adding general content that does not fit specialized templates (apps, sources, release notes). + ## When NOT to use this command * **App integrations**. Use `app-doc` instead. * **Cloud-to-Cloud sources**. Use `c2c-source-doc` instead. -* **Release notes**. Use `release-note` instead. +* **Release notes**. Use `release-note-cse` or `release-note-collector` instead. ## Doc types diff --git a/.claude/commands/geo-optimize.md b/.claude/commands/geo-optimize.md index 0df544be63..6710532404 100644 --- a/.claude/commands/geo-optimize.md +++ b/.claude/commands/geo-optimize.md @@ -2,6 +2,24 @@ Rewrites and restructures documentation to improve discoverability in AI-powered search tools (ChatGPT, Perplexity, Gemini, Claude, and similar) and to surface content as direct answers in traditional search results. Covers both **AEO** (Answer Engine Optimization — featured snippets, "People also ask") and **GEO** (Generative Engine Optimization — LLM citation and extraction). +## What this command does + +When you invoke `/geo-optimize`, Claude will: + +1. **Read the doc** +2. **Diagnose the current state**. Identify AEO and GEO gaps before making changes +3. **Propose specific improvements**. Show the user what will change and why +4. **Apply approved changes**. Rewrite only the sections the user approves +5. **Validate the result**. Confirm the doc is more answer- and citation-ready without breaking accuracy + +## When to use this command + +* New docs for features that are frequently searched in AI tools or voice search +* High-traffic docs that rarely appear in AI-generated answers or featured snippets +* Concept and reference docs where accuracy and citability matter most +* After `/seo-audit` flags AEO or GEO suggestions +* Before a product launch to maximize early visibility + ## What this command does NOT change * Technical accuracy — never alter facts, steps, code, or configuration values diff --git a/.claude/commands/remove-doc.md b/.claude/commands/remove-doc.md index 1755ba360f..6a2821a8fe 100644 --- a/.claude/commands/remove-doc.md +++ b/.claude/commands/remove-doc.md @@ -2,6 +2,24 @@ Automates the complete workflow for removing or moving a Sumo Logic doc while preventing broken links and maintaining SEO health. +## What this command does + +When you invoke `/remove-doc`, Claude will guide you through: + +1. **Create 301 redirect**. Add redirect mapping to `cid-redirects.json`. +2. **Update internal links**. Find and replace all references to the old URL. +3. **Remove from hub pages**. Delete card from parent `index.md` and Product List. +4. **Delete the doc file**. Remove the actual markdown file. +5. **Remove from navigation**. Delete entry from `sidebars.ts`. +6. **Optional steps**. Add deprecation notes, hide from search engines. + +## When to use this command + +* Deprecating legacy docs in favor of new versions. +* Consolidating duplicate content. +* Removing outdated documentation. +* Moving docs to new locations. + ## Workflow ### Step 1: Gather information @@ -84,6 +102,24 @@ Before finishing, verify: * [ ] JSON files valid (no syntax errors). * [ ] Build test passes (optional: `yarn build`). +## Example usage + +``` +User: "Remove the nginx-legacy.md doc and redirect to nginx.md" + +Claude: +1. Confirms old path: docs/integrations/web-servers/nginx-legacy.md +2. Confirms new path: docs/integrations/web-servers/nginx.md +3. Adds redirect: "/docs/integrations/web-servers/nginx-legacy": "/docs/integrations/web-servers/nginx" +4. Searches for all references to nginx-legacy +5. Updates links in 3 files +6. Removes from web-servers index.md hub page +7. Deletes nginx-legacy.md +8. Removes from sidebars.ts +9. Asks about deprecation note +10. Provides verification checklist +``` + ## Safety principles * **Always create the redirect first** before deleting anything. @@ -133,3 +169,30 @@ Create: Multiple redirects, all pointing to unified-doc.md * Revert the change. * Fix and retry. +## Post-completion message + +After successfully removing a doc, tell the user: + +``` +✅ Doc removal complete! + +Summary: +* Added 301 redirect: /old-path → /new-path +* Updated X internal links across Y files +* Removed from hub page and sidebar +* Deleted old doc file + +Next steps: +1. Test locally: yarn start +2. Verify redirect works +3. Submit PR with description: "DOCS-XXX - Remove deprecated [doc name]" +4. Note: Google may take weeks to update search results + +Would you like me to run a build test or create a commit? +``` + +## References + +* [Contributing guide: Move or Remove a Doc](/docs/contributing/remove-doc). +* [CID redirects documentation](/docs/contributing/create-edit-doc#step-6-create-cid-url). +* [Sidebar configuration patterns](.claude/skills/docusaurus/). diff --git a/.claude/commands/review.md b/.claude/commands/review.md deleted file mode 100644 index 4dff1db6f4..0000000000 --- a/.claude/commands/review.md +++ /dev/null @@ -1,115 +0,0 @@ -# Review Pull Request — Documentation Quality Review - -Reviews all changed `.md` files in a pull request using the same checks as `/audit-doc`, then produces a single consolidated PR review comment. - -## Workflow - -### Step 1: Get the PR - -If a PR number or URL is provided, use it. Otherwise run `gh pr list` and ask the user which PR to review. - -Extract the PR number from URLs (e.g., `https://github.com/.../pull/6707` → `6707`). - -### Step 2: Fetch PR details and diff - -Run in parallel: -- `gh pr view --json title,body,author,headRefName,baseRefName,changedFiles` -- `gh pr diff ` - -### Step 3: Identify changed doc files - -From the diff, collect all files with a `.md` extension that were added or modified (ignore deletions). Skip non-doc files (`.ts`, `.json`, `.js`, `.yml`, etc.). - -If no `.md` files changed, report: "No documentation files changed in this PR." - -### Step 4: Determine doc type for each file - -Use the file path to infer the doc type: - -| Path pattern | Doc type | -|---|---| -| `blog-service/`, `blog-collector/`, `blog-cse/`, `blog-csoar/`, `blog-developer/` | Release note | -| `docs/integrations/` or `docs/platform-services/automation-service/app-central/` | App doc | -| `docs/send-data/hosted-collectors/cloud-to-cloud-integration-framework/` | C2C source doc | -| Everything else under `docs/` | Feature / how-to / concept / reference | - -If the type is ambiguous, read the file's frontmatter `tags` field or intro paragraph to confirm. - -### Step 5: Read each changed file - -Use the Read tool to fetch the full current content of each changed `.md` file (not just the diff lines — the full file is needed to check structure, frontmatter, and links in context). - -### Step 6: Apply audit-doc checks to each file - -Apply all checks from `/audit-doc` — frontmatter, structure, links, images, style guide, doc-type-specific requirements — using the same severity levels: - -- **Critical**: must fix before merging -- **Warning**: should fix -- **Suggestion**: nice to have - -See `/audit-doc` for the full checklist. Key things to flag in a PR review: - -- Missing or invalid frontmatter fields (`id`, `title`, `description`) -- Branding violations ("Sumo" instead of "Sumo Logic", wrong app/source opener) -- Wrong heading case (sentence case required — only first word and proper nouns capitalized) -- Missing required sections for the doc type -- Negative contractions (can't, won't, don't → cannot, will not, do not) -- "the user" or "users" instead of "you" -- Bare URLs, missing alt text, missing code block language tags -- Release note format violations (date format, `[New]`/`[Updated]` tags, rule ID patterns) - -Focus on issues introduced by this PR. If the file has pre-existing issues that weren't touched by the diff, note them briefly but do not block the PR over them. - -### Step 7: Produce the review - -Output a single consolidated review covering all changed files. Format: - -``` -## PR review: {PR title} - -{N} doc file(s) changed: {list of filenames} - ---- - -### {filename} -**Type**: {doc type} - -**Critical issues** (must fix): -- {issue with line reference if possible} - -**Warnings** (should fix): -- {issue} - -**Suggestions**: -- {issue} - -✅ No issues / ⚠️ {N} warnings / ❌ {N} critical - ---- - -### {next filename} -... - ---- - -## Overall - -{Pass | Pass with warnings | Needs work} - -{1-2 sentence summary of the most important things to address} -``` - -If a file has no issues: `✅ {filename} — looks good.` - -### Step 8: Offer next steps - -After the review, offer: -- "Run `/audit-doc {file}` to get a detailed report with line numbers and fix options" -- "Run `/seo-audit {file}` to check discoverability signals" - -## Constraints - -- **Read-only**. Do not edit any files. The purpose is to surface issues, not fix them. -- **Diff-aware**. Prioritize issues in lines added or modified by the PR. Flag pre-existing issues separately as "pre-existing" if needed. -- **Concise**. This is a PR review, not a full audit report. One line per issue where possible. -- **No duplication**. The checks live in `/audit-doc`. Do not re-list every rule here — apply them, don't describe them. diff --git a/.claude/commands/seo-audit.md b/.claude/commands/seo-audit.md index 472e1e94fb..99b145871b 100644 --- a/.claude/commands/seo-audit.md +++ b/.claude/commands/seo-audit.md @@ -28,10 +28,8 @@ Use the Read tool to read the complete file content including frontmatter. **Frontmatter** -* [ ] `title` present -* [ ] `title` is under 60 characters — **Critical** if missing or over 60 +* [ ] `title` is under 60 characters — **Critical** if over 60 * [ ] `title` includes the primary keyword or product/feature name -* [ ] `description` present — **Critical** if missing * [ ] `description` is 140–160 characters — **Warning** if shorter than 100 or longer than 160 * [ ] `description` leads with an action verb or product name (not "This page" or "This doc") * [ ] `keywords` field present with 3–5 relevant terms — **Suggestion** if missing @@ -39,8 +37,6 @@ Use the Read tool to read the complete file content including frontmatter. **Headings** -* [ ] No H1 in body — title frontmatter generates H1; a second H1 breaks SEO — **Critical** if present -* [ ] H2 used for main sections; no skipped heading levels (H2 → H4 without H3) — **Warning** if skipped * [ ] At least 2 H2 headings for pages over 500 words — **Suggestion** if none * [ ] No duplicate headings at the same level — **Warning** if duplicated * [ ] Headings are under 60 characters — **Suggestion** if over @@ -49,12 +45,9 @@ Use the Read tool to read the complete file content including frontmatter. * [ ] First paragraph (after frontmatter) is substantive — tells the reader what the doc covers, why it matters, and who it is for — **Warning** if it is thin (under 50 words) or just restates the title * [ ] Page has at least one internal link to a related doc — **Warning** if none -* [ ] Internal link anchor text is descriptive (not "click here" or "here") — **Warning** if bare -* [ ] No bare external URLs — wrap in markdown link syntax — **Warning** if present **Images** -* [ ] All images have non-empty `alt` text — **Critical** if missing * [ ] Alt text describes the image content, not just "screenshot" or the filename — **Warning** if generic ### Step 4: Run AEO checks @@ -136,11 +129,8 @@ Do not modify files without explicit user approval. | Issue | Why it matters | |-------|---------------| -| Missing `description` | Search engines cannot generate a preview snippet; AI tools have no summary to cite | -| Missing `title` | Page cannot be indexed or linked properly | | `title` over 60 chars | Truncated in search results; first 60 chars carry the most weight | -| H1 in body | Duplicate H1 confuses search engines and breaks page structure | -| Missing image alt text | Accessibility failure; images are invisible to search crawlers | +| `slug` on regular page | Overrides URL derived from file path; breaks sidebar linking | ### Warnings @@ -182,10 +172,8 @@ Then ask if the user wants to drill into any specific file. ## Tips -* Run this before `/audit-doc` to prioritize discoverability fixes first * Run this after `/geo-optimize` to verify improvements were applied * For batch fixes on description length, `/seo-audit` + `/geo-optimize` together cover most GEO gaps -* Pair with `/tone-check` for comprehensive pre-PR review --- @@ -195,4 +183,3 @@ Then ask if the user wants to drill into any specific file. * **`/audit-doc`** — structure, required sections, broken links, frontmatter completeness, style guide * **`/geo-optimize`** — apply GEO improvements after this audit identifies gaps -* **`/tone-check`** — voice and tone check (standalone; not covered here) diff --git a/CLAUDE.md b/CLAUDE.md index 52d6c2d086..00ceead4e3 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -85,7 +85,6 @@ When a user asks "what can I do", "what commands are available", or similar, sha | `/audit-doc` | Full quality audit: structure, style, links, frontmatter, completeness | | `/seo-audit` | Discoverability audit: SEO, AEO, and GEO signals — run this before a PR | | `/geo-optimize` | Rewrite a doc to improve AI citation and generative engine visibility | -| `/review` | Review a pull request — applies audit-doc checks to all changed `.md` files | **Jira** From 29aebb6dcda4b14ef3a7dca9203634939d232ff9 Mon Sep 17 00:00:00 2001 From: Kim Pohas <56411016+kimsauce@users.noreply.github.com> Date: Fri, 5 Jun 2026 00:58:43 -0700 Subject: [PATCH 07/22] DOCS-1526 - Add Bulk Changes guardrails to CLAUDE.md (#6720) * DOCS-1634 - Fix MCP server and OAuth docs (#6710) * DOCS-1634 - Fix MCP server and OAuth docs - Remove VS Code and ChatGPT sections from MCP server doc; scope prereqs to any OAuth 2.0 Authorization Code-compatible client - Fix claude mcp add command syntax for --client-secret flag - Expand OAuth client setup steps inline for Claude Code CLI - Soften prerequisite language in both docs - Rewrite Auth Code flow Step 2 to be actionable - Replace hardcoded deployment URLs with and placeholders in Client Credentials Step 3 - Add deployment token endpoint table to FAQ - Fix /oauth/token typo to /oauth2/token throughout Co-Authored-By: Claude Sonnet 4.6 * DOCS-1634: Add Known limitations section to MCP server doc Documents that Cursor (cursor:// redirect URLs unsupported) and recent VS Code releases (auth code flow broken with explicit client credentials) are not currently supported. Includes a note to contact support. Co-Authored-By: Claude Sonnet 4.6 --------- Co-authored-by: Claude Sonnet 4.6 * Bump webpack-dev-server from 5.2.2 to 5.2.4 (#6718) Bumps [webpack-dev-server](https://github.com/webpack/webpack-dev-server) from 5.2.2 to 5.2.4. - [Release notes](https://github.com/webpack/webpack-dev-server/releases) - [Changelog](https://github.com/webpack/webpack-dev-server/blob/main/CHANGELOG.md) - [Commits](https://github.com/webpack/webpack-dev-server/compare/v5.2.2...v5.2.4) --- updated-dependencies: - dependency-name: webpack-dev-server dependency-version: 5.2.4 dependency-type: indirect ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * DOCS-1526 - Add Bulk Changes guardrails to CLAUDE.md Distill the DOCS-63 post-mortem lessons into a short CLAUDE.md section instead of a full bulk-doc-change skill. Newer models handle most of the workflow naturally; only the non-obvious institutional rules (no revert from memory, atomic commits per directory, no committed helper scripts) need to persist as durable guidance. Co-Authored-By: Claude Sonnet 4.6 --------- Signed-off-by: dependabot[bot] Co-authored-by: Claude Sonnet 4.6 Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- CLAUDE.md | 10 ++ docs/api/mcp-server.md | 127 ++++------------ docs/manage/security/oauth.md | 166 +++++++++----------- yarn.lock | 275 ++++++++++++++++++++++++++++------ 4 files changed, 335 insertions(+), 243 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 00ceead4e3..b7641b60b2 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -15,6 +15,16 @@ Docs live in /docs, written in Markdown. Contributions follow the Sumo Logic sty - .claude/skills/docusaurus/SKILL.md — Docusaurus 3 syntax, frontmatter templates, and sidebar config patterns. - .claude/skills/pr-template-guide/SKILL.md — PR template structure, formatting examples, and best practices. +## Bulk Changes +For any change touching 50+ files (terminology migrations, frontmatter audits, link updates, admonition format changes), follow these rules — lessons distilled from the DOCS-63 post-mortem: + +1. **Define scope first, get sign-off.** State the exact pattern, included paths, excluded paths, and known edge cases before touching files. +2. **Dry-run before writing.** Report total file count, per-directory breakdown, and ~10 before/after samples. Wait for confirmation. +3. **Apply in batches by directory**, not all at once. Show `git diff --stat` and a few spot-checks after each batch. +4. **One commit per batch/category** — never bundle multiple directories into one commit. Atomic commits stay revertable. +5. **Never revert from memory.** If reverting, validate against actual file content — do not trust "the original had X." +6. **Never commit helper/detection scripts** to the repo. Run them ephemerally. + ## Pull Requests **CRITICAL REQUIREMENT**: ALL pull requests MUST use the official template from `.github/PULL_REQUEST_TEMPLATE.md`. No exceptions. diff --git a/docs/api/mcp-server.md b/docs/api/mcp-server.md index 7a3eb71149..a8b1dddeb8 100644 --- a/docs/api/mcp-server.md +++ b/docs/api/mcp-server.md @@ -1,7 +1,7 @@ --- id: mcp-server title: Sumo Logic MCP Server -description: Connect your AI tools to Sumo Logic via MCP to query logs, manage insights, and investigate security incidents from VS Code, ChatGPT, and Claude Code CLI. +description: Connect your AI tools to Sumo Logic via MCP to query logs, manage insights, and investigate security incidents using Claude Code CLI. --- import useBaseUrl from '@docusaurus/useBaseUrl'; @@ -24,8 +24,8 @@ The Sumo Logic MCP server lets MCP clients (external AI models) securely query l ## Prerequisites -* **Sumo Logic Administrator role**. Required to create OAuth clients. If you're unsure whether you are an administrator, you can find your role in your [Preferences](/docs/get-started/onboarding-checklists/). -* **Sumo Logic OAuth credentials**. You'll create these during the setup process for your chosen client below ([learn more](/docs/manage/security/oauth)). +* **Sumo Logic Administrator role**. You'll need this to create OAuth clients. If you're unsure whether you have this role, check your [Preferences](/docs/get-started/onboarding-checklists/). +* **Sumo Logic OAuth client credentials**. The MCP client uses [OAuth client credentials](/docs/manage/security/oauth) to authenticate with Sumo Logic. For Claude Code CLI, you'll create them during the setup steps below. * **MCP server URL for your deployment**. OAuth tokens are deployment-bound, so you must use the correct URL for your Sumo Logic deployment: | Deployment | MCP Server URL | | :--- | :--- | @@ -39,41 +39,17 @@ The Sumo Logic MCP server lets MCP clients (external AI models) securely query l | US East (N. Virginia) | `https://mcp.sumologic.com/mcp` | | US East (N. Virginia) - FedRAMP | `https://mcp.fed.sumologic.com/mcp` | | US West (Oregon) | `https://mcp.us2.sumologic.com/mcp` | -* **An MCP-compatible client**. Currently, we support the following clients: - * **[ChatGPT](https://chatgpt.com/)**. - * **[Claude Code CLI](https://code.claude.com/docs/en/quickstart)**. You'll need a paid Claude subscription or Anthropic Console account. - * **[VS Code](https://code.visualstudio.com/docs/copilot/chat/copilot-chat)**. You'll need a GitHub account with GitHub Copilot access. A free GitHub Copilot plan is available with limited monthly requests. +* **An MCP-compatible client that supports OAuth 2.0 Authorization Code flow**. Any MCP client that supports OAuth 2.0 Authorization Code flow with a client ID and secret will work. + * We've documented setup below for [Claude Code CLI](https://code.claude.com/docs/en/quickstart) (requires a paid Claude subscription or Anthropic Console account). -## Configure in ChatGPT +## Known limitations -### Authentication - -ChatGPT uses OAuth 2.0 Authorization Code flow for authentication. You'll create an OAuth client in Sumo Logic during the setup process. - -### Setup +* **Cursor**. Cursor requires redirect URLs starting with `cursor://`, which is not yet supported by the Sumo Logic authorization server. +* **VS Code**. Recent VS Code releases do not work with the authorization code flow when an explicit client ID and secret are provided. -1. In ChatGPT, go to **Settings** > **Advanced Settings**. -1. Enable **Developer Mode**. -1. Go to **Settings** > **Advanced Settings** > **Create App**. -1. Copy the **Redirect URL** shown in the dialog. You'll use this when [creating your OAuth client in Sumo Logic](/docs/manage/security/oauth#authorization-code-flow). -1. In Sumo Logic, [create an OAuth client using the Authorization Code flow](/docs/manage/security/oauth#authorization-code-flow) with the redirect URL from ChatGPT. -1. Return to ChatGPT's Create App dialog and enter: - * **MCP Server URL**. Your deployment's MCP server URL from the [Prerequisites table](#prerequisites) above. - * **OAuth Client ID**. Your Client ID from Sumo Logic. - * **OAuth Client Secret**. Your Client Secret from Sumo Logic. -1. Check **I understand and want to Continue**. -1. Click **Create**. -1. ChatGPT will open a browser window to authenticate with Sumo Logic. Log in to complete the OAuth flow. -1. Once connected, you can start using Sumo Logic MCP tools in your ChatGPT conversations. - -### Using MCP tools in ChatGPT - -To use Sumo Logic MCP tools in ChatGPT: -1. Start a new chat. -1. Ask ChatGPT to use your Sumo Logic MCP server (for example, "List my available Sumo Logic MCP tools" or "Search my logs for errors in the last hour"). -1. ChatGPT will automatically invoke the appropriate MCP tools to fulfill your request. - -See [Available MCP Tools](#available-mcp-tools) for a full list of capabilities. +:::note +If you have questions about client compatibility, [contact Sumo Logic Support](https://support.sumologic.com/support/s). +::: ## Configure in Claude Code CLI @@ -83,24 +59,31 @@ Claude Code CLI uses OAuth 2.0 Authorization Code flow for authentication. Brows ### Setup -1. In Sumo Logic, [create an OAuth client using the Authorization Code flow](/docs/manage/security/oauth#authorization-code-flow) with redirect URI: `http://localhost:8888/callback`. -1. In a Terminal window (not in Claude Code), register the MCP server. Replace `` and `` with your values from Sumo Logic, and replace `` with your deployment's MCP server URL from the [Prerequisites table](#prerequisites) above. Choose a scope: +1. In Sumo Logic, create an OAuth client for Claude Code: + 1. Go to **Administration** > **Security** > **OAuth Clients**. + 1. Click **+ Add Client**. + 1. For **Type**, select **Authorization Code**. + 1. Enter a **Name** and optional **Description**. + 1. For **Redirect URI**, enter: + ``` + http://localhost:8888/callback + ``` + 1. Click **Save**. + 1. Copy the **Client ID** and **Client Secret**. You'll use these in the next step. + For more details about OAuth clients, see [OAuth Client Setup](/docs/manage/security/oauth#authorization-code-flow). +1. In a Terminal window, not in Claude Code, register the MCP server. Replace `` with your value from Sumo Logic, and replace `` with your deployment's MCP server URL from the [Prerequisites table](#prerequisites) above. When you run the command, Claude Code prompts you to enter the client secret securely. Choose a scope: * **User scope** (available in all directories, recommended). ```bash claude mcp add --transport http \ --scope user \ - --client-id "" \ - --callback-port 8888 \ - --client-secret \ + --client-id "" --client-secret --callback-port 8888 \ sumo-logic "" ``` * **Project scope** (available only in the current directory, writes to `.mcp.json`). ```bash claude mcp add --transport http \ --scope project \ - --client-id "" \ - --callback-port 8888 \ - --client-secret \ + --client-id "" --client-secret --callback-port 8888 \ sumo-logic "" ``` 1. Launch Claude Code. With **user scope**, run `claude` from any directory. With **project scope**, run it from the directory where you registered the server. @@ -113,64 +96,6 @@ Claude Code CLI uses OAuth 2.0 Authorization Code flow for authentication. Brows 1. Verify the connection with `/mcp` to confirm the server is connected.
Claude Code CLI showing Sumo Logic MCP server connected 1. Prompt Claude Code to `List my available MCP tools` to see what you can do. You can also refer to [Available MCP Tools](#available-mcp-tools). -## Configure in VS Code - -### Authentication - -VS Code with GitHub Copilot Chat uses OAuth 2.0 Client Credentials flow for authentication. - -Before you begin, [create an OAuth client using Client Credentials flow](/docs/manage/security/oauth#client-credentials-flow) and [generate an access token](/docs/manage/security/oauth#generate-an-access-token). You'll need your access token for the setup below. - -### Setup - -1. Open VS Code and install the GitHub Copilot Chat extension, if you don't have it. -1. Click in the VS Code command palette and run a search for **> MCP: Open User Configuration**.
VS Code command palette search with MCP: Open User Configuration highlighted -1. Add the following configuration to the **mcp.json** file. Replace `` with your deployment's MCP server URL from the [Prerequisites table](#prerequisites) above. - ```json title="mcp.json" - { - "servers": { - "Sumo Logic MCP server": { - "type": "http", - "url": "", - "headers": { - "Authorization": "Bearer ${input:oauthToken}" - }, - "gallery": "https://sanyaku.github.io/sumologic-mcp-gateway", - "version": "Original" - } - }, - "inputs": [ - { - "id": "oauthToken", - "type": "promptString", - "description": "Enter your OAuth access token for Sumo Logic MCP server", - "password": true - } - ] - } - ``` - If you've previously configured other MCP servers here, this should be an additive process (that is, do not delete existing ones you still intend to use). -1. In the **mcp.json** file, click the **Start** button just above `"Sumo Logic MCP server": {`.
VS Code Start button in mcp.json configuration file -1. You'll be prompted in the command palette for an OAuth access token. Enter your [access token from Sumo Logic](/docs/manage/security/oauth#generate-an-access-token) there.
prompt in command palette for OAuth access token -1. Confirm that the server shows as **Running**.
prompt in command palette for OAuth access token -1. Open GitHub Copilot Chat and ensure it's set to **Agent** mode. -1. You should now be connected to the Sumo Logic MCP server. Verify by asking `List my available MCP tools` to see what you can do. You can also refer to [Available MCP Tools](#available-mcp-tools). - -### Reconnecting - -Access tokens expire after 12 hours and may also expire after quitting and restarting VS Code. When this occurs: - -:::note -If you see a `403` error with message `insufficient_scope - The request requires higher privileges than provided by the access token`, the cause may be a **deployment mismatch**. This happens when the OAuth token was generated for one deployment but the MCP server URL in **mcp.json** points to a different one. Verify that both use the same deployment. -::: - -1. You'll see a **Dynamic Client Registration not supported** popup asking for an OAuth client ID. Do NOT provide this. Click **Cancel**.
Dynamic Client Registration not supported popup asking for an OAuth client ID with Cancel button highlighted -1. You'll be prompted again for an OAuth client ID in your command palette. Tap **Escape** on your keyboard.
VS Code command palette search with MCP: Open User Configuration highlighted -1. [Generate a new access token in Sumo Logic](/docs/manage/security/oauth#generate-an-access-token). -1. Reopen your **mcp.json** file. -1. Hover your mouse over the redacted access token until the **Edit | Clear | Clear All** options appear, then click **Edit**.
edit VS Code OAuth access token -1. Enter your new access token in the command palette and then restart the Sumo Logic MCP server. - ## Available MCP tools Our MCP server provides access to Sumo Logic through these tool categories: diff --git a/docs/manage/security/oauth.md b/docs/manage/security/oauth.md index 4bfcc5bdfb..844e6f30a6 100644 --- a/docs/manage/security/oauth.md +++ b/docs/manage/security/oauth.md @@ -30,7 +30,7 @@ Sumo Logic supports two OAuth 2.0 authentication flows: ## Prerequisites -* **Sumo Logic Administrator role**. Required to create OAuth clients and service accounts. +* **Sumo Logic Administrator role**. You'll need this to create OAuth clients and service accounts. If you're unsure whether you have this role, check your [Preferences](/docs/get-started/onboarding-checklists/). ## How permissions work @@ -59,15 +59,7 @@ This flow uses interactive browser-based authentication. Users authorize an exte ### Step 2: Complete the OAuth flow -Sumo Logic's Authorization Code flow follows the [OAuth 2.1 specification](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1). Your OAuth library or client handles the authorization, token exchange, and token refresh steps automatically by following the standard protocol. - -To discover the authorization and token endpoints for your deployment, query the Authorization Server Metadata. Replace `[deployment-endpoint]` with your [deployment endpoint](/docs/api/about-apis/getting-started/#sumo-logic-endpoints-by-deployment-and-firewall-security) (for example, `service.sumologic.com`, `service.us2.sumologic.com`, `service.eu.sumologic.com`): - -```bash -curl https://[deployment-endpoint]/.well-known/oauth-authorization-server -``` - -The response includes `authorization_endpoint`, `token_endpoint`, and other supported OAuth parameters. +Configure your OAuth library or client with the client ID, secret, and redirect URI from Step 1. Sumo Logic follows the [OAuth 2.1 specification](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1), so any compliant library handles authorization, token exchange, and token refresh automatically. ## Client Credentials flow @@ -82,55 +74,46 @@ Create a Sumo Logic service account to represent your application or service. Yo 1. Get the service account ID. You'll use this ID in the next step. * **Via UI**. Go to **Administration** > **Security** > **Service Accounts**, click on your service account, and copy the ID from the browser URL (appears as `selectedId=00000000076D28F9`). * **Via API**. Alternatively, [get a list of all service accounts](https://api.sumologic.com/docs/#operation/listServiceAccounts) and find the `id` field in the response. - -
-Example API request for listing service accounts - - - - - -Replace `` and `` with your personal access key credentials. Replace `service.sumologic.com` with your [deployment endpoint](/docs/api/about-apis/getting-started/#sumo-logic-endpoints-by-deployment-and-firewall-security) if different. - -```bash -curl -u ":" \ - https://service.sumologic.com/api/v1/serviceAccounts -``` - - - - -```json title="Example response highlighting service account ID" {14} -{ - "data": [ - { - "name": "My Service Account", - "email": "service@example.com", - "roleIds": [ - "00000000000001DF", - "00000000000002D2" - ], - "createdAt": "2025-10-16T09:10:00.000Z", - "createdBy": "0000000006743FDD", - "modifiedAt": "2025-10-16T09:10:00.000Z", - "modifiedBy": "0000000006743FE8", - "id": "0000000000C4661B", - "isActive": true - } - ] -} -``` - - - - -
+
+ Example API request for listing service accounts + + + Replace `` and `` with your personal access key credentials. Replace `service.sumologic.com` with your [deployment endpoint](/docs/api/about-apis/getting-started/#sumo-logic-endpoints-by-deployment-and-firewall-security) if different. + ```bash + curl -u ":" \ + https://service.sumologic.com/api/v1/serviceAccounts + ``` + + + ```json title="Example response highlighting service account ID" {14} + { + "data": [ + { + "name": "My Service Account", + "email": "service@example.com", + "roleIds": [ + "00000000000001DF", + "00000000000002D2" + ], + "createdAt": "2025-10-16T09:10:00.000Z", + "createdBy": "0000000006743FDD", + "modifiedAt": "2025-10-16T09:10:00.000Z", + "modifiedBy": "0000000006743FE8", + "id": "0000000000C4661B", + "isActive": true + } + ] + } + ``` + + +
### Step 2: Create an OAuth client @@ -224,20 +207,16 @@ Copy the `clientId` and `clientSecret` from the response. These are your OAuth c -### Step 3: Generate an access token {#generate-an-access-token} +### Step 3: Generate an access token -Request an OAuth access token from the token endpoint using your client credentials. - -:::note Deployment endpoints -The examples below use `service.sumologic.com`. If your Sumo Logic instance uses a different deployment, replace this with your [deployment endpoint](/docs/api/about-apis/getting-started/#sumo-logic-endpoints-by-deployment-and-firewall-security) (for example, `service.us2.sumologic.com`, `service.eu.sumologic.com`). -::: +Request an OAuth access token from the token endpoint using your client credentials. Replace `` with your deployment's token endpoint — see [How do I find the authorization or token endpoint?](#how-do-i-find-the-authorization-or-token-endpoint-for-my-deployment). **Option A: Request all available permissions** Omit the `scope` parameter to assign all of the OAuth client's effective scopes to the access token. ```bash -curl -X POST https://service.sumologic.com/oauth2/token \ +curl -X POST \ -H "Content-Type: application/x-www-form-urlencoded" \ -u ":" \ -d "grant_type=client_credentials" @@ -248,7 +227,7 @@ curl -X POST https://service.sumologic.com/oauth2/token \ Use the `scope` parameter to request specific scopes. Separate multiple scopes with spaces, not commas. ```bash -curl -X POST https://service.sumologic.com/oauth2/token \ +curl -X POST \ -H "Content-Type: application/x-www-form-urlencoded" \ -u ":" \ -d "grant_type=client_credentials" \ @@ -266,30 +245,16 @@ The response includes an access token: } ``` -Use this access token as a Bearer token in the `Authorization` header when making API requests: +Use this access token as a Bearer token in the `Authorization` header when making API requests. Replace `` with your [deployment-specific API endpoint](/docs/api/about-apis/getting-started/#sumo-logic-endpoints-by-deployment-and-firewall-security) (for example, `api.sumologic.com` for US1, `api.us2.sumologic.com` for US2): ```bash -curl https://api.sumologic.com/api/v1/search/jobs \ +curl /api/v1/search/jobs \ -H "Authorization: Bearer eyJhbGc..." ``` -:::note Deployment endpoints -`api.sumologic.com` defaults to the us1 deployment. Replace with your [deployment-specific endpoint](/docs/api/about-apis/getting-started/#sumo-logic-endpoints-by-deployment-and-firewall-security) if your org is on a different deployment (for example, `api.us2.sumologic.com`, `api.eu.sumologic.com`). -::: - ### Token expiration -Access tokens generated with Client Credentials flow expire after 12 hours. When a token expires, generate a new one by repeating the token request. Unlike Authorization Code flow, Client Credentials flow does not provide refresh tokens. - -:::note Discovering endpoints programmatically -The token endpoint URL varies by deployment. To discover it programmatically (for example, in automation scripts), query the Authorization Server Metadata. Replace `[deployment-endpoint]` with your [deployment endpoint](/docs/api/about-apis/getting-started/#sumo-logic-endpoints-by-deployment-and-firewall-security) (for example, `service.sumologic.com`, `service.us2.sumologic.com`): - -```bash -curl https://[deployment-endpoint]/.well-known/oauth-authorization-server -``` - -The response includes the `token_endpoint` and other supported OAuth parameters. -::: +Access tokens generated with Client Credentials flow expire after 12 hours. When a token expires, generate a new one by repeating the [token request](#step-3-generate-an-access-token). Unlike Authorization Code flow, Client Credentials flow does not provide refresh tokens. ## Security best practices @@ -343,31 +308,36 @@ For Client Credentials flow, [effective permissions are the intersection of the For Authorization Code flow, [effective permissions are the intersection of the user's roles, the OAuth client's scopes, and the requested scopes](#how-permissions-work). If a user's roles are restricted, their effective OAuth permissions are reduced at the next token refresh. If roles are expanded, the new permissions become available at the next token refresh. -### How do I find the token endpoint for my deployment? +### How do I find the authorization or token endpoint for my deployment? -The token endpoint URL varies by [deployment](/docs/api/about-apis/getting-started/#sumo-logic-endpoints-by-deployment-and-firewall-security). Replace `[deployment-endpoint]` with your deployment's service endpoint. The pattern is: +Token endpoint URLs vary by deployment: -``` -https://[deployment-endpoint]/oauth/token -``` +| Deployment | Token endpoint | +| :--- | :--- | +| Asia Pacific (Seoul) | `https://service.kr.sumologic.com/oauth2/token` | +| Asia Pacific (Sydney) | `https://service.au.sumologic.com/oauth2/token` | +| Asia Pacific (Tokyo) | `https://service.jp.sumologic.com/oauth2/token` | +| Canada (Central) | `https://service.ca.sumologic.com/oauth2/token` | +| Europe (Frankfurt) | `https://service.de.sumologic.com/oauth2/token` | +| Europe (Ireland) | `https://service.eu.sumologic.com/oauth2/token` | +| Europe (Zurich) | `https://service.ch.sumologic.com/oauth2/token` | +| US East (N. Virginia) | `https://service.sumologic.com/oauth2/token` | +| US East (N. Virginia) - FedRAMP | `https://service.fed.sumologic.com/oauth2/token` | +| US West (Oregon) | `https://service.us2.sumologic.com/oauth2/token` | -For example: -* US1: `https://service.sumologic.com/oauth/token` -* US2: `https://service.us2.sumologic.com/oauth/token` -* EU: `https://service.eu.sumologic.com/oauth/token` +To find the `authorization_endpoint` for your deployment (used in [Authorization Code flow](#authorization-code-flow)), query the Authorization Server Metadata: -To discover the endpoint programmatically, replace `[deployment-endpoint]` with your service endpoint (e.g., `service.sumologic.com`) and query: ```bash curl https://[deployment-endpoint]/.well-known/oauth-authorization-server ``` +The response includes `authorization_endpoint`, `token_endpoint`, and other supported OAuth parameters. + ### Can I use OAuth with the Sumo Logic APIs? -Yes. OAuth access tokens work with all Sumo Logic APIs. Include the access token in the `Authorization` header as a Bearer token: +Yes. OAuth access tokens work with all Sumo Logic APIs. Include the access token in the `Authorization` header as a Bearer token. Replace `` with your [deployment-specific API endpoint](/docs/api/about-apis/getting-started/#sumo-logic-endpoints-by-deployment-and-firewall-security) (for example, `api.sumologic.com` for US1, `api.us2.sumologic.com` for US2): ```bash -curl https://api.sumologic.com/api/v1/users \ +curl /api/v1/users \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" ``` - -Replace `api.sumologic.com` with your [deployment-specific endpoint](/docs/api/about-apis/getting-started/#sumo-logic-endpoints-by-deployment-and-firewall-security) if your org is on a different deployment. diff --git a/yarn.lock b/yarn.lock index 27d2e088f5..218024174d 100644 --- a/yarn.lock +++ b/yarn.lock @@ -3105,6 +3105,11 @@ "@emnapi/runtime" "^1.5.0" "@tybys/wasm-util" "^0.10.1" +"@noble/hashes@1.4.0": + version "1.4.0" + resolved "https://registry.yarnpkg.com/@noble/hashes/-/hashes-1.4.0.tgz#45814aa329f30e4fe0ba49426f49dfccdd066426" + integrity sha512-V1JJ1WTRUqHHrOSh597hURcMqVKVGL/ea3kv0gSnEdsEZ0/+VyPghM1lMNGc00z7CIQorSvbKpuJkxvuHbvdbg== + "@nodelib/fs.scandir@2.1.5": version "2.1.5" resolved "https://registry.yarnpkg.com/@nodelib/fs.scandir/-/fs.scandir-2.1.5.tgz#7619c2eb21b25483f6d167548b4cfd5a7488c3d5" @@ -3131,6 +3136,136 @@ resolved "https://registry.yarnpkg.com/@opentelemetry/api/-/api-1.9.0.tgz#d03eba68273dc0f7509e2a3d5cba21eae10379fe" integrity sha512-3giAOQvZiH5F9bMlMiv8+GSPMeqg0dbaeo58/0SlA9sxSqZhnUtxzX9/2FzyhS9sWQf5S0GJE0AKBrFqjpeYcg== +"@peculiar/asn1-cms@^2.6.0", "@peculiar/asn1-cms@^2.7.0": + version "2.7.0" + resolved "https://registry.yarnpkg.com/@peculiar/asn1-cms/-/asn1-cms-2.7.0.tgz#8e0eb656f4fc85f7c621dd442fa2d298faa84984" + integrity sha512-hew63shtzzvBcSHbhm+cyAmKe6AIfinT9hzEqSPjDC6opTTMKmTkQ0gHuN2KsWlvqiKw1S/fS94fhag/FJkioQ== + dependencies: + "@peculiar/asn1-schema" "^2.7.0" + "@peculiar/asn1-x509" "^2.7.0" + "@peculiar/asn1-x509-attr" "^2.7.0" + asn1js "^3.0.6" + tslib "^2.8.1" + +"@peculiar/asn1-csr@^2.6.0": + version "2.7.0" + resolved "https://registry.yarnpkg.com/@peculiar/asn1-csr/-/asn1-csr-2.7.0.tgz#1a03ac03f7571ea981f5d8377c6f4510c5d43411" + integrity sha512-VVsAyGqErT9D1SY4aEqozThXMVI+ssVRiv2DDeYuvpBKLIgZ3hYs3Ay3u/VSoKq6ESFi9cf6rf3IOOzfwh7oMA== + dependencies: + "@peculiar/asn1-schema" "^2.7.0" + "@peculiar/asn1-x509" "^2.7.0" + asn1js "^3.0.6" + tslib "^2.8.1" + +"@peculiar/asn1-ecc@^2.6.0": + version "2.7.0" + resolved "https://registry.yarnpkg.com/@peculiar/asn1-ecc/-/asn1-ecc-2.7.0.tgz#c35b57859812ecd0c2ae7b2144855e8208c2cfee" + integrity sha512-n7KEs/Q/wrB415cxy4fHOBhegp4NdJ15fkJPwcB/3/8iNBQC2L/N7SChJPKDJPZGYH0jD4Tg4/0vnHmwghnbKw== + dependencies: + "@peculiar/asn1-schema" "^2.7.0" + "@peculiar/asn1-x509" "^2.7.0" + asn1js "^3.0.6" + tslib "^2.8.1" + +"@peculiar/asn1-pfx@^2.7.0": + version "2.7.0" + resolved "https://registry.yarnpkg.com/@peculiar/asn1-pfx/-/asn1-pfx-2.7.0.tgz#d00766b13ff49785684a604248e6aadd184b291f" + integrity sha512-V/nrlQVmhg7lYAsM7E13UDL5erAwFv6kCIVFqNaMIHSVi7dngcT839JkRTkQBqznMG98l2XjxYk74ZztAohZzA== + dependencies: + "@peculiar/asn1-cms" "^2.7.0" + "@peculiar/asn1-pkcs8" "^2.7.0" + "@peculiar/asn1-rsa" "^2.7.0" + "@peculiar/asn1-schema" "^2.7.0" + asn1js "^3.0.6" + tslib "^2.8.1" + +"@peculiar/asn1-pkcs8@^2.7.0": + version "2.7.0" + resolved "https://registry.yarnpkg.com/@peculiar/asn1-pkcs8/-/asn1-pkcs8-2.7.0.tgz#5ee602d8a9a3e0a3f09f7b008ff644a657378692" + integrity sha512-9GTl1nE8Mx1kTZ+7QyYatDyKsm34QcWRBFkY1iPvWC3X4Dona5s/tlLiQsx5WzVdZqiMBZNYT0buyw4/vbhnjw== + dependencies: + "@peculiar/asn1-schema" "^2.7.0" + "@peculiar/asn1-x509" "^2.7.0" + asn1js "^3.0.6" + tslib "^2.8.1" + +"@peculiar/asn1-pkcs9@^2.6.0": + version "2.7.0" + resolved "https://registry.yarnpkg.com/@peculiar/asn1-pkcs9/-/asn1-pkcs9-2.7.0.tgz#23b4eae41c2feb8df258aa69c502a70092026b0a" + integrity sha512-Bh7m+OuIaSEllPQcSd9OSp93F4ROWH7sbITWV8MI+8dwsjE5111/87VxiWVvYFKyww3vp39geLv9ENqhwWHcew== + dependencies: + "@peculiar/asn1-cms" "^2.7.0" + "@peculiar/asn1-pfx" "^2.7.0" + "@peculiar/asn1-pkcs8" "^2.7.0" + "@peculiar/asn1-schema" "^2.7.0" + "@peculiar/asn1-x509" "^2.7.0" + "@peculiar/asn1-x509-attr" "^2.7.0" + asn1js "^3.0.6" + tslib "^2.8.1" + +"@peculiar/asn1-rsa@^2.6.0", "@peculiar/asn1-rsa@^2.7.0": + version "2.7.0" + resolved "https://registry.yarnpkg.com/@peculiar/asn1-rsa/-/asn1-rsa-2.7.0.tgz#6dc5c78c643264dd5a251a66f1dd9a38fcbba385" + integrity sha512-/qvENQrXyTZURjMqSeofHul0JJt2sNSzSwk36pl2olkHbaioMQgrASDZAlHXl0xUlnVbHj0uGgOrBMTb5x2aJQ== + dependencies: + "@peculiar/asn1-schema" "^2.7.0" + "@peculiar/asn1-x509" "^2.7.0" + asn1js "^3.0.6" + tslib "^2.8.1" + +"@peculiar/asn1-schema@^2.6.0", "@peculiar/asn1-schema@^2.7.0": + version "2.7.0" + resolved "https://registry.yarnpkg.com/@peculiar/asn1-schema/-/asn1-schema-2.7.0.tgz#f2dcb25995ce7cac8687ba1039f043e5eff43820" + integrity sha512-W8ZfWzLmQnrcky+eh3tni4IozMdqBDiHWU0N+vve/UGjMaUs8c0L7A2oEdkBXS8rTpWDpK/aoI3DG/L/hxmxPg== + dependencies: + "@peculiar/utils" "^2.0.2" + asn1js "^3.0.6" + tslib "^2.8.1" + +"@peculiar/asn1-x509-attr@^2.7.0": + version "2.7.0" + resolved "https://registry.yarnpkg.com/@peculiar/asn1-x509-attr/-/asn1-x509-attr-2.7.0.tgz#5ef2a10d3a78d4763b848a2cb56db4bb6b1e082a" + integrity sha512-NS8e7SOgXipkzUPLF/sce7ukpMpWjhxYsH0n6Y+bHYo4TTxOb95Zv7hqwSuL212mj5YxovjdOKQOgH1As3E94w== + dependencies: + "@peculiar/asn1-schema" "^2.7.0" + "@peculiar/asn1-x509" "^2.7.0" + asn1js "^3.0.6" + tslib "^2.8.1" + +"@peculiar/asn1-x509@^2.6.0", "@peculiar/asn1-x509@^2.7.0": + version "2.7.0" + resolved "https://registry.yarnpkg.com/@peculiar/asn1-x509/-/asn1-x509-2.7.0.tgz#84793efb7819dbc9526fd6b0a4ccd86f90464b96" + integrity sha512-mUn9RRrkGDnG4ALfunDmzyRW5dg+sWCj/pfnCCqEHYbkGxEpvUt6iVJv8Yw1cyp6SWZ26ZE5oSmI5SqEaen15g== + dependencies: + "@peculiar/asn1-schema" "^2.7.0" + "@peculiar/utils" "^2.0.2" + asn1js "^3.0.6" + tslib "^2.8.1" + +"@peculiar/utils@^2.0.2": + version "2.0.3" + resolved "https://registry.yarnpkg.com/@peculiar/utils/-/utils-2.0.3.tgz#a27ca4c4b73652e110f19a7d16d664f458a5528e" + integrity sha512-+oL3HPFRIZ1St2K50lWCXiioIgSoxzz7R1J3uF6neO2yl1sgmpgY6XXJH4BdpoDkMWznQTeYF6oWNDZLCdQ4eQ== + dependencies: + tslib "^2.8.1" + +"@peculiar/x509@^1.14.2": + version "1.14.3" + resolved "https://registry.yarnpkg.com/@peculiar/x509/-/x509-1.14.3.tgz#2c44c2b89474346afec38a0c2803ec4fb8ce959e" + integrity sha512-C2Xj8FZ0uHWeCXXqX5B4/gVFQmtSkiuOolzAgutjTfseNOHT3pUjljDZsTSxXFGgio54bCzVFqmEOUrIVk8RDA== + dependencies: + "@peculiar/asn1-cms" "^2.6.0" + "@peculiar/asn1-csr" "^2.6.0" + "@peculiar/asn1-ecc" "^2.6.0" + "@peculiar/asn1-pkcs9" "^2.6.0" + "@peculiar/asn1-rsa" "^2.6.0" + "@peculiar/asn1-schema" "^2.6.0" + "@peculiar/asn1-x509" "^2.6.0" + pvtsutils "^1.3.6" + reflect-metadata "^0.2.2" + tslib "^2.8.1" + tsyringe "^4.10.0" + "@pkgjs/parseargs@^0.11.0": version "0.11.0" resolved "https://registry.yarnpkg.com/@pkgjs/parseargs/-/parseargs-0.11.0.tgz#a77ea742fab25775145434eb1d2328cf5013ac33" @@ -4097,15 +4232,15 @@ "@types/express-serve-static-core" "^5.0.0" "@types/serve-static" "*" -"@types/express@^4.17.21": - version "4.17.23" - resolved "https://registry.yarnpkg.com/@types/express/-/express-4.17.23.tgz#35af3193c640bfd4d7fe77191cd0ed411a433bef" - integrity sha512-Crp6WY9aTYP3qPi2wGDo9iUe/rceX01UMhnF1jmwDcKCFM6cx7YhGP/Mpr3y9AASpfHixIG0E6azCcL5OcDHsQ== +"@types/express@^4.17.25": + version "4.17.25" + resolved "https://registry.yarnpkg.com/@types/express/-/express-4.17.25.tgz#070c8c73a6fee6936d65c195dbbfb7da5026649b" + integrity sha512-dVd04UKsfpINUnK0yBoYHDF3xu7xVH4BuDotC/xGuycx4CgbP48X/KF/586bcObxT0HENHXEU8Nqtu6NR+eKhw== dependencies: "@types/body-parser" "*" "@types/express-serve-static-core" "^4.17.33" "@types/qs" "*" - "@types/serve-static" "*" + "@types/serve-static" "^1" "@types/geojson@*": version "7946.0.16" @@ -4218,13 +4353,6 @@ resolved "https://registry.yarnpkg.com/@types/ms/-/ms-2.1.0.tgz#052aa67a48eccc4309d7f0191b7e41434b90bb78" integrity sha512-GsCCIZDE/p3i96vtEqx+7dBUGXrc7zeSK3wwPHIaRThS+9OhWIXRqzs4d6k1SVU8g91DrNRWxWUGhp5KXQb2VA== -"@types/node-forge@^1.3.0": - version "1.3.14" - resolved "https://registry.yarnpkg.com/@types/node-forge/-/node-forge-1.3.14.tgz#006c2616ccd65550560c2757d8472eb6d3ecea0b" - integrity sha512-mhVF2BnD4BO+jtOp7z1CdzaK4mbuK0LLQYAvdOLqHTavxFNq4zA1EmYkpnFjP8HOUzedfQkRnp0E2ulSAYSzAw== - dependencies: - "@types/node" "*" - "@types/node@*": version "24.7.0" resolved "https://registry.yarnpkg.com/@types/node/-/node-24.7.0.tgz#a34c9f0d3401db396782e440317dd5d8373c286f" @@ -4364,6 +4492,15 @@ "@types/node" "*" "@types/send" "<1" +"@types/serve-static@^1": + version "1.15.10" + resolved "https://registry.yarnpkg.com/@types/serve-static/-/serve-static-1.15.10.tgz#768169145a778f8f5dfcb6360aead414a3994fee" + integrity sha512-tRs1dB+g8Itk72rlSI2ZrW6vZg0YrLI81iQSTkMmOqnqCaNr/8Ek4VwWcN5vZgCYWbg/JJSGBlUaYGAOP73qBw== + dependencies: + "@types/http-errors" "*" + "@types/node" "*" + "@types/send" "<1" + "@types/sockjs@^0.3.36": version "0.3.36" resolved "https://registry.yarnpkg.com/@types/sockjs/-/sockjs-0.3.36.tgz#ce322cf07bcc119d4cbf7f88954f3a3bd0f67535" @@ -4974,6 +5111,15 @@ arraybuffer.prototype.slice@^1.0.3: is-array-buffer "^3.0.4" is-shared-array-buffer "^1.0.2" +asn1js@^3.0.6: + version "3.0.10" + resolved "https://registry.yarnpkg.com/asn1js/-/asn1js-3.0.10.tgz#df26c874c8a8b41ca605efea47b2ad07551013dd" + integrity sha512-S2s3aOytiKdFRdulw2qPE51MzjzVOisppcVv7jVFR+Kw0kxwvFrDcYA0h7Ndqbmj0HkMIXYWaoj7fli8kgx1eg== + dependencies: + pvtsutils "^1.3.6" + pvutils "^1.1.5" + tslib "^2.8.1" + ast-types@^0.13.4: version "0.13.4" resolved "https://registry.yarnpkg.com/ast-types/-/ast-types-0.13.4.tgz#ee0d77b343263965ecc3fb62da16e7222b2b6782" @@ -5156,10 +5302,10 @@ binary-extensions@^2.0.0: resolved "https://registry.yarnpkg.com/binary-extensions/-/binary-extensions-2.3.0.tgz#f6e14a97858d327252200242d4ccfe522c445522" integrity sha512-Ceh+7ox5qe7LJuLHoY0feh3pHuUDHAcRUeyL2VYghZwfpkNIy/+8Ocg0a3UuSoYzavmylwuLWQOf3hl0jjMMIw== -body-parser@~1.20.3: - version "1.20.4" - resolved "https://registry.yarnpkg.com/body-parser/-/body-parser-1.20.4.tgz#f8e20f4d06ca8a50a71ed329c15dccad1cdc547f" - integrity sha512-ZTgYYLMOXY9qKU/57FAo8F+HA2dGX7bqGc71txDRC1rS4frdFI5R7NhluHxH6M0YItAP0sHB4uqAOcYKxO6uGA== +body-parser@~1.20.5: + version "1.20.5" + resolved "https://registry.yarnpkg.com/body-parser/-/body-parser-1.20.5.tgz#303c8c34423d1d6fa799bc764e93c1e4dc6ebf64" + integrity sha512-3grm+/2tUOvu2cjJkvsIxrv/wVpfXQW4PsQHYm7yk4vfpu7Ekl6nEsYBoJUL6qDwZUx8wUhQ8tR2qz+ad9c9OA== dependencies: bytes "~3.1.2" content-type "~1.0.5" @@ -5169,7 +5315,7 @@ body-parser@~1.20.3: http-errors "~2.0.1" iconv-lite "~0.4.24" on-finished "~2.4.1" - qs "~6.14.0" + qs "~6.15.1" raw-body "~2.5.3" type-is "~1.6.18" unpipe "~1.0.0" @@ -5283,6 +5429,11 @@ bytes@3.1.2, bytes@~3.1.2: resolved "https://registry.yarnpkg.com/bytes/-/bytes-3.1.2.tgz#8b0beeb98605adf1b128fa4386403c009e0221a5" integrity sha512-/Nf7TyzTx6S3yRJObOAV7956r8cr2+Oj8AC5dt8wSP3BQAoeX58NoHyCU8P8zGkNXStjTSi6fzO6F0pBdcYbEg== +bytestreamjs@^2.0.1: + version "2.0.1" + resolved "https://registry.yarnpkg.com/bytestreamjs/-/bytestreamjs-2.0.1.tgz#a32947c7ce389a6fa11a09a9a563d0a45889535e" + integrity sha512-U1Z/ob71V/bXfVABvNr/Kumf5VyeQRBEm6Txb0PQ6S7V5GpBM3w4Cbqz/xPDicR5tN0uvDifng8C+5qECeGwyQ== + cacheable-lookup@^5.0.3: version "5.0.4" resolved "https://registry.yarnpkg.com/cacheable-lookup/-/cacheable-lookup-5.0.4.tgz#5a6b865b2c44357be3d5ebc2a467b032719a7005" @@ -5694,7 +5845,7 @@ compressible@~2.0.18: dependencies: mime-db ">= 1.43.0 < 2" -compression@^1.7.4: +compression@^1.8.1: version "1.8.1" resolved "https://registry.yarnpkg.com/compression/-/compression-1.8.1.tgz#4a45d909ac16509195a9a28bd91094889c180d79" integrity sha512-9mAqGPHLakhCLeNyxPkK4xVo746zQ/czLH1Ky+vkitMnWfWZps8r0qXuwhwizagCRttsL4lfG4pIOvaWLpAP0w== @@ -7407,14 +7558,14 @@ executable@^4.1.0: dependencies: pify "^2.2.0" -express@^4.21.2: - version "4.22.1" - resolved "https://registry.yarnpkg.com/express/-/express-4.22.1.tgz#1de23a09745a4fffdb39247b344bb5eaff382069" - integrity sha512-F2X8g9P1X7uCPZMA3MVf9wcTqlyNp7IhH5qPCI0izhaOIYXaW9L535tGA3qmjRzpH+bZczqq7hVKxTR4NWnu+g== +express@^4.22.1: + version "4.22.2" + resolved "https://registry.yarnpkg.com/express/-/express-4.22.2.tgz#c17ae0981e5efc24b22272f0e041c4662503b700" + integrity sha512-IuL+Elrou2ZvCFHs18/CIzy2Nzvo25nZ1/D2eIZlz7c+QUayAcYoiM2BthCjs+EBHVpjYjcuLDAiCWgeIX3X1Q== dependencies: accepts "~1.3.8" array-flatten "1.1.1" - body-parser "~1.20.3" + body-parser "~1.20.5" content-disposition "~0.5.4" content-type "~1.0.4" cookie "~0.7.1" @@ -7433,7 +7584,7 @@ express@^4.21.2: parseurl "~1.3.3" path-to-regexp "~0.1.12" proxy-addr "~2.0.7" - qs "~6.14.0" + qs "~6.15.1" range-parser "~1.2.1" safe-buffer "5.2.1" send "~0.19.0" @@ -10893,7 +11044,7 @@ node-fetch@^2.6.7: dependencies: whatwg-url "^5.0.0" -node-forge@^1, node-forge@^1.4.0: +node-forge@^1.4.0: version "1.4.0" resolved "https://registry.yarnpkg.com/node-forge/-/node-forge-1.4.0.tgz#1c7b7d8bdc2d078739f58287d589d903a11b2fc2" integrity sha512-LarFH0+6VfriEhqMMcLX2F7SwSXeWwnEAJEsYm5QKWchiVYVvJyV9v7UDvUv+w5HO23ZpQTXDv/GxdDdMyOuoQ== @@ -11428,6 +11579,18 @@ pkg-dir@^7.0.0: dependencies: find-up "^6.3.0" +pkijs@^3.3.3: + version "3.4.0" + resolved "https://registry.yarnpkg.com/pkijs/-/pkijs-3.4.0.tgz#d9164def30ff6d97be2d88966d5e36192499ca9c" + integrity sha512-emEcLuomt2j03vxD54giVB4SxTjnsqkU692xZOZXHDVoYyypEm+b3jpiTcc+Cf+myooc+/Ly0z01jqeNHVgJGw== + dependencies: + "@noble/hashes" "1.4.0" + asn1js "^3.0.6" + bytestreamjs "^2.0.1" + pvtsutils "^1.3.6" + pvutils "^1.1.3" + tslib "^2.8.1" + points-on-curve@0.2.0, points-on-curve@^0.2.0: version "0.2.0" resolved "https://registry.yarnpkg.com/points-on-curve/-/points-on-curve-0.2.0.tgz#7dbb98c43791859434284761330fa893cb81b4d1" @@ -12165,10 +12328,22 @@ puppeteer@^22.15.0: devtools-protocol "0.0.1312386" puppeteer-core "22.15.0" -qs@~6.14.0: - version "6.14.2" - resolved "https://registry.yarnpkg.com/qs/-/qs-6.14.2.tgz#b5634cf9d9ad9898e31fba3504e866e8efb6798c" - integrity sha512-V/yCWTTF7VJ9hIh18Ugr2zhJMP01MY7c5kh4J870L7imm6/DIzBsNLTXzMwUA3yZ5b/KBqLx8Kp3uRvd7xSe3Q== +pvtsutils@^1.3.6: + version "1.3.6" + resolved "https://registry.yarnpkg.com/pvtsutils/-/pvtsutils-1.3.6.tgz#ec46e34db7422b9e4fdc5490578c1883657d6001" + integrity sha512-PLgQXQ6H2FWCaeRak8vvk1GW462lMxB5s3Jm673N82zI4vqtVUPuZdffdZbPDFRoU8kAhItWFtPCWiPpp4/EDg== + dependencies: + tslib "^2.8.1" + +pvutils@^1.1.3, pvutils@^1.1.5: + version "1.1.5" + resolved "https://registry.yarnpkg.com/pvutils/-/pvutils-1.1.5.tgz#84b0dea4a5d670249aa9800511804ee0b7c2809c" + integrity sha512-KTqnxsgGiQ6ZAzZCVlJH5eOjSnvlyEgx1m8bkRJfOhmGRqfo5KLvmAlACQkrjEtOQ4B7wF9TdSLIs9O90MX9xA== + +qs@~6.15.1: + version "6.15.2" + resolved "https://registry.yarnpkg.com/qs/-/qs-6.15.2.tgz#fd55426d710403ddccc45e0f9eab16db7727ece9" + integrity sha512-Rzq0KEyX/w/tEybncDgdkZrJgVUsUMk3xjh3t5bv3S1HTAtg+uOYt72+ZfwiQwKdysThkTBdL/rTi6HDmX9Ddw== dependencies: side-channel "^1.1.0" @@ -12425,6 +12600,11 @@ recma-stringify@^1.0.0: unified "^11.0.0" vfile "^6.0.0" +reflect-metadata@^0.2.2: + version "0.2.2" + resolved "https://registry.yarnpkg.com/reflect-metadata/-/reflect-metadata-0.2.2.tgz#400c845b6cba87a21f2c65c4aeb158f4fa4d9c5b" + integrity sha512-urBwgfrvVP/eAyXx4hluJivBKzuEbSQs9rKWCrCkbSxNv8mxPcUZKeuoF3Uy4mJl3Lwprp6yy5/39VWigZ4K6Q== + reflect.getprototypeof@^1.0.4: version "1.0.6" resolved "https://registry.yarnpkg.com/reflect.getprototypeof/-/reflect.getprototypeof-1.0.6.tgz#3ab04c32a8390b770712b7a8633972702d278859" @@ -12908,13 +13088,13 @@ select-hose@^2.0.0: resolved "https://registry.yarnpkg.com/select-hose/-/select-hose-2.0.0.tgz#625d8658f865af43ec962bfc376a37359a4994ca" integrity sha512-mEugaLK+YfkijB4fx0e6kImuJdCIt2LxCRcbEYPqRGCs4F2ogyfZU5IAZRdjCP8JPq2AtdNoC/Dux63d9Kiryg== -selfsigned@^2.4.1: - version "2.4.1" - resolved "https://registry.yarnpkg.com/selfsigned/-/selfsigned-2.4.1.tgz#560d90565442a3ed35b674034cec4e95dceb4ae0" - integrity sha512-th5B4L2U+eGLq1TVh7zNRGBapioSORUeymIydxgFpwww9d2qyKvtuPU2jJuHvYAwwqi2Y596QBL3eEqcPEYL8Q== +selfsigned@^5.5.0: + version "5.5.0" + resolved "https://registry.yarnpkg.com/selfsigned/-/selfsigned-5.5.0.tgz#4c9ab7c7c9f35f18fb6a9882c253eb0e6bd6557b" + integrity sha512-ftnu3TW4+3eBfLRFnDEkzGxSF/10BJBkaLJuBHZX0kiPS7bRdlpZGu6YGt4KngMkdTwJE6MbjavFpqHvqVt+Ew== dependencies: - "@types/node-forge" "^1.3.0" - node-forge "^1" + "@peculiar/x509" "^1.14.2" + pkijs "^3.3.3" semver-diff@^4.0.0: version "4.0.0" @@ -13950,12 +14130,12 @@ ts-interface-checker@^0.1.9: resolved "https://registry.yarnpkg.com/ts-interface-checker/-/ts-interface-checker-0.1.13.tgz#784fd3d679722bc103b1b4b8030bcddb5db2a699" integrity sha512-Y/arvbn+rrz3JCKl9C4kVNfTfSm2/mEp5FSz5EsZSANGPSlQrpRI5M4PKF+mJnE52jOO90PnPSc3Ur3bTQw0gA== -tslib@^1.8.1: +tslib@^1.8.1, tslib@^1.9.3: version "1.14.1" resolved "https://registry.yarnpkg.com/tslib/-/tslib-1.14.1.tgz#cf2d38bdc34a134bcaf1091c41f6619e2f672d00" integrity sha512-Xni35NKzjgMrwevysHTCArtLDpPvye8zV/0E4EyYn43P7/7qvQwPh9BGkHewbMulVntbigmcT7rdX3BNo9wRJg== -tslib@^2.0.0, tslib@^2.0.1, tslib@^2.0.3, tslib@^2.4.0, tslib@^2.6.0: +tslib@^2.0.0, tslib@^2.0.1, tslib@^2.0.3, tslib@^2.4.0, tslib@^2.6.0, tslib@^2.8.1: version "2.8.1" resolved "https://registry.yarnpkg.com/tslib/-/tslib-2.8.1.tgz#612efe4ed235d567e8aba5f2a5fab70280ade83f" integrity sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w== @@ -13967,6 +14147,13 @@ tsutils@^3.21.0: dependencies: tslib "^1.8.1" +tsyringe@^4.10.0: + version "4.10.0" + resolved "https://registry.yarnpkg.com/tsyringe/-/tsyringe-4.10.0.tgz#d0c95815d584464214060285eaaadd94aa03299c" + integrity sha512-axr3IdNuVIxnaK5XGEUFTu3YmAQ6lllgrvqfEoR16g/HGnYY/6We4oWENtAnzK6/LpJ2ur9PAb80RBt7/U4ugw== + dependencies: + tslib "^1.9.3" + type-check@^0.4.0, type-check@~0.4.0: version "0.4.0" resolved "https://registry.yarnpkg.com/type-check/-/type-check-0.4.0.tgz#07b8203bfa7056c0657050e3ccd2c37730bab8f1" @@ -14504,13 +14691,13 @@ webpack-dev-middleware@^7.4.2: schema-utils "^4.0.0" webpack-dev-server@^5.2.2: - version "5.2.2" - resolved "https://registry.yarnpkg.com/webpack-dev-server/-/webpack-dev-server-5.2.2.tgz#96a143d50c58fef0c79107e61df911728d7ceb39" - integrity sha512-QcQ72gh8a+7JO63TAx/6XZf/CWhgMzu5m0QirvPfGvptOusAxG12w2+aua1Jkjr7hzaWDnJ2n6JFeexMHI+Zjg== + version "5.2.4" + resolved "https://registry.yarnpkg.com/webpack-dev-server/-/webpack-dev-server-5.2.4.tgz#6e6306ce59848ed322c235e48b326632b1eed6d6" + integrity sha512-GqDPGZN9bRqKBTkp4aWkobDDHMsrXKoGSdOH56smIri8qR0JG8gfL8/v/f/OZR3/OKXjG8uwJbFVhKm/FNU/UA== dependencies: "@types/bonjour" "^3.5.13" "@types/connect-history-api-fallback" "^1.5.4" - "@types/express" "^4.17.21" + "@types/express" "^4.17.25" "@types/express-serve-static-core" "^4.17.21" "@types/serve-index" "^1.9.4" "@types/serve-static" "^1.15.5" @@ -14520,9 +14707,9 @@ webpack-dev-server@^5.2.2: bonjour-service "^1.2.1" chokidar "^3.6.0" colorette "^2.0.10" - compression "^1.7.4" + compression "^1.8.1" connect-history-api-fallback "^2.0.0" - express "^4.21.2" + express "^4.22.1" graceful-fs "^4.2.6" http-proxy-middleware "^2.0.9" ipaddr.js "^2.1.0" @@ -14530,7 +14717,7 @@ webpack-dev-server@^5.2.2: open "^10.0.3" p-retry "^6.2.0" schema-utils "^4.2.0" - selfsigned "^2.4.1" + selfsigned "^5.5.0" serve-index "^1.9.1" sockjs "^0.3.24" spdy "^4.0.2" From 98cd023e7e77a44ee99685733f4f9224256fc9ba Mon Sep 17 00:00:00 2001 From: Kim Pohas Date: Mon, 8 Jun 2026 07:20:22 -0700 Subject: [PATCH 08/22] DOCS-1640 - Improve Claude command files per agentskills.io guidance MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - audit-doc, doc, seo-audit: replace generic "What this command does" steps with imperative descriptions and a Gotchas section - audit-doc: fix heading case rule (H1 Title Case, H2–H4 sentence case); restore redundant when-to-use bullet - seo-audit: restore dropped checks (anchor text, bare URLs, missing alt, Critical table rows) - CLAUDE.md: add plan mode requirement for bulk changes; clarify bulk change examples with e.g.; remove opaque DOCS-63 reference Co-Authored-By: Claude Sonnet 4.6 --- .claude/commands/audit-doc.md | 19 ++++++------------- .claude/commands/doc.md | 14 +------------- .claude/commands/seo-audit.md | 9 ++++++++- CLAUDE.md | 4 +++- 4 files changed, 18 insertions(+), 28 deletions(-) diff --git a/.claude/commands/audit-doc.md b/.claude/commands/audit-doc.md index b17f5dd32c..ec84e788ba 100644 --- a/.claude/commands/audit-doc.md +++ b/.claude/commands/audit-doc.md @@ -1,18 +1,12 @@ # Audit Doc — Documentation Quality Check -Performs comprehensive quality checks on documentation files to ensure adherence to Sumo Logic style guidelines, proper structure, and completeness. +Use this command to audit a doc for style, structure, links, and frontmatter compliance — run it before submitting any PR, after creating a new doc, or when reviewing community contributions. -## What this command does +## Gotchas -When you invoke `/audit-doc`, Claude will: - -1. **Read and analyze the specified doc file** -2. **Check frontmatter**. Validate required fields and format -3. **Review content structure**. Check headings, sections, and organization -4. **Validate links and images**. Check paths, alt text, and references -5. **Check style adherence**. Apply Sumo Logic style guide rules -6. **Report findings**. Provide detailed feedback with specific line numbers -7. **Suggest fixes**. Offer actionable recommendations +- H1 headings and the `title` frontmatter field use **Title Case**. H2, H3, H4 use **sentence case** (only first word and proper nouns capitalized). +- Skip warnings for legacy docs with an established style, docs tagged `noindex` (temporary drafts), or third-party content not meant to be modified. +- `/audit-doc` does not check SEO/AEO/GEO signals — run `/seo-audit` separately for discoverability. ## When to use this command @@ -20,7 +14,6 @@ When you invoke `/audit-doc`, Claude will: * After creating a new doc to validate structure * When updating existing docs to ensure consistency * To identify broken links or missing images -* To verify adherence to Sumo Logic style guidelines * When reviewing community contributions ## Workflow @@ -67,7 +60,7 @@ Check for required fields and proper formatting: * [ ] Only one H1 heading (the title in frontmatter) * [ ] H2 sections used for main sections * [ ] No skipped heading levels (H2 → H4 without H3) -* [ ] Headings use sentence case (only first word and proper nouns capitalized) +* [ ] H1 uses Title Case; H2, H3, H4 use sentence case (only first word and proper nouns capitalized) **Required sections (by doc type):** diff --git a/.claude/commands/doc.md b/.claude/commands/doc.md index e5f3fb9bbc..17b08c3e31 100644 --- a/.claude/commands/doc.md +++ b/.claude/commands/doc.md @@ -1,18 +1,6 @@ # Create New Doc -Automates the creation of general Sumo Logic documentation for features, how-tos, concepts, reference pages, and troubleshooting guides. - -## What this command does - -When you invoke `doc`, Claude will guide you through: - -1. **Determine doc type**. Feature, how-to, concept, reference, or troubleshooting. -2. **Gather information**. Title, description, file path, and keywords. -3. **Create markdown file**. Generate file with proper frontmatter and basic structure. -4. **Add to navigation**. Guide on adding to sidebars.ts. -5. **Add to hub page**. Suggest adding card to parent index page. -6. **Create CID mapping**. Add permanent URL if needed for UI links. -7. **Validate and preview**. Check structure and provide next steps. +Use this command to create a new feature doc, how-to, concept, reference, or troubleshooting guide — it scaffolds the file, frontmatter, structure, and sidebar entry. ## When to use this command diff --git a/.claude/commands/seo-audit.md b/.claude/commands/seo-audit.md index 99b145871b..2583017dfb 100644 --- a/.claude/commands/seo-audit.md +++ b/.claude/commands/seo-audit.md @@ -1,6 +1,6 @@ # SEO/AEO/GEO Audit — Search and AI Discoverability Check -Audits documentation for search engine optimization (SEO), answer engine optimization (AEO), and generative engine optimization (GEO) signals. Produces a prioritized report and offers to apply fixes. +Use this command to audit a doc for SEO, AEO, and GEO signals — run it before any PR on new or updated content, even if you're not focused on search optimization. ## Signal definitions @@ -45,9 +45,12 @@ Use the Read tool to read the complete file content including frontmatter. * [ ] First paragraph (after frontmatter) is substantive — tells the reader what the doc covers, why it matters, and who it is for — **Warning** if it is thin (under 50 words) or just restates the title * [ ] Page has at least one internal link to a related doc — **Warning** if none +* [ ] Internal link anchor text is descriptive (not "click here" or "here") — **Warning** if bare +* [ ] No bare external URLs — wrap in markdown link syntax — **Warning** if present **Images** +* [ ] All images have non-empty `alt` text — **Critical** if missing * [ ] Alt text describes the image content, not just "screenshot" or the filename — **Warning** if generic ### Step 4: Run AEO checks @@ -129,7 +132,11 @@ Do not modify files without explicit user approval. | Issue | Why it matters | |-------|---------------| +| Missing `description` | Search engines cannot generate a preview snippet; AI tools have no summary to cite | +| Missing `title` | Page cannot be indexed or linked properly | | `title` over 60 chars | Truncated in search results; first 60 chars carry the most weight | +| H1 in body | Duplicate H1 confuses search engines and breaks page structure | +| Missing image alt text | Accessibility failure; images are invisible to search crawlers | | `slug` on regular page | Overrides URL derived from file path; breaks sidebar linking | ### Warnings diff --git a/CLAUDE.md b/CLAUDE.md index b7641b60b2..7a00cedfc7 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -16,7 +16,9 @@ Docs live in /docs, written in Markdown. Contributions follow the Sumo Logic sty - .claude/skills/pr-template-guide/SKILL.md — PR template structure, formatting examples, and best practices. ## Bulk Changes -For any change touching 50+ files (terminology migrations, frontmatter audits, link updates, admonition format changes), follow these rules — lessons distilled from the DOCS-63 post-mortem: +For any change touching 50+ files (e.g. terminology migrations, frontmatter audits, link updates, admonition format changes), follow these rules: + +**Enter plan mode** (`/plan`) at the start of any bulk change. Present scope, file count, directory breakdown, and before/after samples — then wait for explicit approval before touching any files. 1. **Define scope first, get sign-off.** State the exact pattern, included paths, excluded paths, and known edge cases before touching files. 2. **Dry-run before writing.** Report total file count, per-directory breakdown, and ~10 before/after samples. Wait for confirmation. From 153dad1314de6478bace173716d18b9089e22516 Mon Sep 17 00:00:00 2001 From: Kim Pohas <56411016+kimsauce@users.noreply.github.com> Date: Wed, 10 Jun 2026 15:34:35 -0700 Subject: [PATCH 09/22] Update CLAUDE.md with branch naming rules Added guidelines for branch naming and commit approval process. --- CLAUDE.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 7a00cedfc7..8ee651cce1 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -43,6 +43,8 @@ For detailed examples and implementation guidance, see `.claude/skills/pr-templa ## Git Rules **CRITICAL**: Never commit, merge, or push changes without explicit user approval — even if "accept edits" is enabled. Always ask first. +**Branch naming**: Branch names must always be the Jira ticket number only (e.g., `DOCS-1697`). No additional description. + Before merging any PR, provide the user with the commit description and wait for explicit approval. Before pushing any commit that changes docs content: From 6d56b1dd084c7ad955f096b2f2b3409e63a1969b Mon Sep 17 00:00:00 2001 From: Kim Pohas Date: Wed, 20 May 2026 00:39:21 -0700 Subject: [PATCH 10/22] DOCS-1640: Trim dead weight from Claude commands and consolidate release notes - Consolidate 5 release-note-* commands into a single release-note.md - Remove "What this command does", "When to use", "Post-completion message", "Tips", "After the X", "Example usage", and generic error-handling sections from audit-doc, doc, doc-from-jira, geo-optimize, remove-doc, rewrite-intro, seo-audit, simplify, and tone-check commands - Update CLAUDE.md slash command table to reference /release-note Co-Authored-By: Claude Sonnet 4.6 --- .claude/commands/audit-doc.md | 120 ---- .claude/commands/doc-from-jira.md | 18 - .claude/commands/doc.md | 173 +----- .claude/commands/geo-optimize.md | 18 - .claude/commands/release-note-collector.md | 404 -------------- .claude/commands/release-note-cse.md | 419 -------------- .claude/commands/release-note-csoar.md | 605 --------------------- .claude/commands/release-note-developer.md | 504 ----------------- .claude/commands/release-note-service.md | 474 ---------------- .claude/commands/release-note.md | 369 +++++++++++++ .claude/commands/remove-doc.md | 63 --- .claude/commands/rewrite-intro.md | 36 -- .claude/commands/seo-audit.md | 20 - .claude/commands/simplify.md | 37 -- .claude/commands/tone-check.md | 37 -- CLAUDE.md | 56 +- 16 files changed, 423 insertions(+), 2930 deletions(-) delete mode 100644 .claude/commands/release-note-collector.md delete mode 100644 .claude/commands/release-note-cse.md delete mode 100644 .claude/commands/release-note-csoar.md delete mode 100644 .claude/commands/release-note-developer.md delete mode 100644 .claude/commands/release-note-service.md create mode 100644 .claude/commands/release-note.md diff --git a/.claude/commands/audit-doc.md b/.claude/commands/audit-doc.md index cdaf1d4051..94848f5cba 100644 --- a/.claude/commands/audit-doc.md +++ b/.claude/commands/audit-doc.md @@ -2,27 +2,6 @@ Performs comprehensive quality checks on documentation files to ensure adherence to Sumo Logic style guidelines, proper structure, and completeness. -## What this command does - -When you invoke `/audit-doc`, Claude will: - -1. **Read and analyze the specified doc file** -2. **Check frontmatter**. Validate required fields and format -3. **Review content structure**. Check headings, sections, and organization -4. **Validate links and images**. Check paths, alt text, and references -5. **Check style adherence**. Apply Sumo Logic style guide rules -6. **Report findings**. Provide detailed feedback with specific line numbers -7. **Suggest fixes**. Offer actionable recommendations - -## When to use this command - -* Before submitting a PR to check doc quality -* After creating a new doc to validate structure -* When updating existing docs to ensure consistency -* To identify broken links or missing images -* To verify adherence to Sumo Logic style guidelines -* When reviewing community contributions - ## Workflow ### Step 1: Identify the doc to audit @@ -301,53 +280,6 @@ After presenting the audit report, ask the user if they would like Claude to: * Unclear instructions * Not linked from parent page -## Example usage - -### Basic audit - -``` -User: "/audit-doc docs/integrations/databases/postgresql.md" - -Claude: -1. Reads the file -2. Checks frontmatter (id, title, description, tags) -3. Validates structure (headings, sections) -4. Checks links and images -5. Applies style guide rules -6. Generates report with: - - 2 critical issues (missing image, broken link) - - 3 warnings (description too long, inconsistent formatting) - - 5 suggestions (add example, improve heading) -7. Asks if user wants fixes applied -``` - -### Audit with doc type - -``` -User: "/audit-doc docs/send-data/hosted-collectors/cloud-to-cloud-integration-framework/okta-source.md --type c2c-source" - -Claude: -1. Reads the file -2. Applies C2C source-specific checks -3. Validates vendor configuration section -4. Checks authentication setup steps -5. Verifies required sections present -6. Reports findings specific to C2C sources -``` - -### Audit directory - -``` -User: "/audit-doc docs/integrations/security-threat-detection/" - -Claude: -1. Finds all .md files in directory -2. Runs audit on each file -3. Generates summary report for all files -4. Highlights files needing attention -5. Provides batch fix option -``` - ## Audit checklist summary Use this checklist template for the report: @@ -420,58 +352,6 @@ Track common issues across multiple audits to identify systemic problems. * Validate CID URL mapping * Confirm cross-references -## Tips and best practices - -**For effective audits:** -* Run audit before requesting PR review -* Fix critical issues first, then warnings -* Use audit reports in PR descriptions -* Re-run audit after making fixes -* Consider doc type context (release notes vs feature docs) - -**Common quick fixes:** -* Add missing frontmatter fields -* Update relative link paths -* Add language tags to code blocks -* Fix heading capitalization -* Remove trailing whitespace - -**When to skip warnings:** -* Legacy docs with established style -* Marketing pages with intentional tone -* Third-party content that shouldn't be modified -* Temporary draft content (with noindex tag) - -## Error handling - -**If file not found:** -* Show error message -* Suggest using Tab completion for path -* Check if file was recently moved or renamed - -**If file is not markdown:** -* Show error: "Audit only works with .md files" -* Suggest appropriate file type - -**If doc type cannot be determined:** -* Ask user to specify doc type -* Provide list of supported types -* Offer generic audit without type-specific checks - -**If many issues found (>20):** -* Suggest focusing on critical issues first -* Offer to generate summary instead of full report -* Recommend gradual fixes in multiple PRs - -## References - -* [Sumo Logic Style Guide](/docs/contributing/style-guide) -* [Contributing Guide](/docs/contributing) -* [Doc Templates](/docs/contributing/templates) -* [Docusaurus Documentation](https://docusaurus.io/docs) - ---- - ## Related commands `/audit-doc` covers structure, style, links, frontmatter, and required sections. It does not diff --git a/.claude/commands/doc-from-jira.md b/.claude/commands/doc-from-jira.md index 3e06303350..3873aeb2bd 100644 --- a/.claude/commands/doc-from-jira.md +++ b/.claude/commands/doc-from-jira.md @@ -2,24 +2,6 @@ Pulls a Jira ticket from the DOCS project, extracts the content requirements, and scaffolds a fully structured documentation file ready for writing. Eliminates the blank-page problem and keeps the doc aligned with the ticket spec from the start. -## What this command does - -When you invoke `/doc-from-jira`, Claude will: - -1. **Fetch the Jira ticket**. Pull title, description, acceptance criteria, and linked resources -2. **Determine doc type**. Feature, how-to, concept, reference, or troubleshooting -3. **Infer the file path**. Based on the technical area and content type -4. **Scaffold the doc**. Generate a file with correct frontmatter, structure, and placeholder sections pre-populated from the ticket -5. **Update sidebars.ts**. Add the new doc to navigation (with user approval) -6. **Link back to Jira**. Set the Jira ticket to In Progress if not already - -## When to use this command - -* Starting a new doc for a DOCS ticket -* When a ticket has a detailed description or acceptance criteria worth preserving -* For tickets with linked specs, PRDs, or engineering docs to pull context from -* When you want to ensure the doc structure is aligned with what was requested - ## When NOT to use this command * **App integrations** — use `/app-doc` instead diff --git a/.claude/commands/doc.md b/.claude/commands/doc.md index 13fbc78697..aa72e99dc2 100644 --- a/.claude/commands/doc.md +++ b/.claude/commands/doc.md @@ -2,31 +2,11 @@ Automates the creation of general Sumo Logic documentation for features, how-tos, concepts, reference pages, and troubleshooting guides. -## What this command does - -When you invoke `doc`, Claude will guide you through: - -1. **Determine doc type**. Feature, how-to, concept, reference, or troubleshooting. -2. **Gather information**. Title, description, file path, and keywords. -3. **Create markdown file**. Generate file with proper frontmatter and basic structure. -4. **Add to navigation**. Guide on adding to sidebars.ts. -5. **Add to hub page**. Suggest adding card to parent index page. -6. **Create CID mapping**. Add permanent URL if needed for UI links. -7. **Validate and preview**. Check structure and provide next steps. - -## When to use this command - -* Creating feature documentation. -* Writing how-to guides and tutorials. -* Documenting concepts and reference material. -* Creating troubleshooting guides. -* Adding general content that does not fit specialized templates (apps, sources, release notes). - ## When NOT to use this command * **App integrations**. Use `app-doc` instead. * **Cloud-to-Cloud sources**. Use `c2c-source-doc` instead. -* **Release notes**. Use `release-note-cse` or `release-note-collector` instead. +* **Release notes**. Use `release-note` instead. ## Doc types @@ -386,40 +366,6 @@ Before finishing, verify: * [ ] No negative contractions (use "cannot", "will not", "do not"). * [ ] No trailing whitespace. -## Example usage - -### Feature Doc Example - -``` -User: "Create a doc for the new access keys feature" - -Claude: -1. Confirms type: Feature Documentation -2. Gathers info: title, path, description, keywords -3. Creates: docs/manage/security/access-keys.md -4. Generates frontmatter with proper fields -5. Scaffolds feature doc structure -6. Guides on adding to sidebars.ts under Manage category -7. Suggests adding card to docs/manage/security/index.md -8. Asks if CID mapping needed -9. Provides validation checklist -``` - -### How-to Guide Example - -``` -User: "Create a how-to guide for installing the OpenTelemetry Collector on Windows" - -Claude: -1. Confirms type: How-to Guide -2. Gathers info: title, path, description -3. Creates: docs/send-data/opentelemetry-collector/install-collector/windows.md -4. Generates frontmatter -5. Scaffolds how-to structure with prerequisites and steps -6. Guides on sidebar placement -7. Provides checklist -``` - ## Common patterns ### File path conventions @@ -472,120 +418,3 @@ keywords: - reports ``` -## Safety principles - -* **Check existing files** before creating to avoid duplicates. -* **Follow existing path conventions** in the category. -* **Use descriptive filenames** that indicate content. -* **Keep titles concise** but clear. -* **Validate frontmatter** has all required fields. -* **Use appropriate structure** for the doc type. - -## Post-completion message - -After successfully creating the doc, tell the user: - -``` -✅ Documentation file created successfully! - -File created: -* 📄 {file-path} - -Summary: -* Type: {doc-type} -* Title: {title} -* Category: {category} - -Next steps: -1. Add content to the doc sections -2. Add doc to sidebars.ts: - * Open sidebars.ts - * Find the {category} category - * Add '{doc-id}' to the items array -3. Optional: Add card to hub page at {parent-index-path} -4. Optional: Create CID mapping in cid-redirects.json -5. Preview locally: yarn start -6. Check preview at: http://localhost:3000/docs/{doc-path} -7. Submit PR: "DOCS-XXX - Add {doc-title}" - -Checklist: -* [ ] Content complete and follows structure. -* [ ] Added to sidebars.ts. -* [ ] Added to hub page (if applicable). -* [ ] CID mapping created (if needed). -* [ ] All links work. -* [ ] Style guide compliant. - -The doc will appear in the navigation menu after you add it to sidebars.ts. - -Would you like me to help add content to any specific section? -``` - -## Error handling - -**If file already exists:** -* Show existing file path and title. -* Ask if user wants to: - * Edit existing file instead. - * Use different filename. - * Overwrite (requires confirmation). - -**If title is too long:** -* Show character count. -* Suggest shorter alternative. -* Recommend using `sidebar_label` for long titles. - -**If path does not follow conventions:** -* Suggest correct path based on category. -* Explain repo conventions. - -**If no description provided:** -* Explain importance for SEO. -* Suggest generating description from title. - -## Tips and best practices - -**General:** -* Start with a clear introduction that sets expectations. -* Use second person ("you") to address readers. -* Keep paragraphs short (2-4 sentences). -* Use active voice. -* Include concrete examples. - -**Structure:** -* Use headings to organize content logically. -* Put most important information first. -* Group related information together. -* End with related topics or next steps. - -**Links:** -* Link to related docs for additional context. -* Use descriptive link text. -* Prefer relative paths for internal links. -* Test all links work. - -**Images:** -* Use images to illustrate UI steps or concepts. -* Always include descriptive alt text. -* Store images in `/static/img/` directory. -* Optimize image file sizes. - -**Code:** -* Specify language for syntax highlighting. -* Keep code examples concise and relevant. -* Include comments for complex code. -* Show realistic examples, not placeholders. - -## References - -* [Style Guide](/docs/contributing/style-guide). -* [Create or Edit a Doc](/docs/contributing/create-edit-doc). -* [Sumo Logic Word List](/docs/contributing/word-list). - ---- - -**Note:** This command is for general documentation. For specialized content types, use the appropriate command: - -* **App integrations**. Use `/app-doc` for creating app documentation with standardized templates and structure. -* **Cloud-to-Cloud sources**. Use `/c2c-source-doc` for Cloud-to-Cloud source integration documentation. -* **Release notes**. Use `/release-note-cse`, `/release-note-collector`, `/release-note-csoar`, `/release-note-developer`, or `/release-note-service` for product release notes. diff --git a/.claude/commands/geo-optimize.md b/.claude/commands/geo-optimize.md index 6710532404..0df544be63 100644 --- a/.claude/commands/geo-optimize.md +++ b/.claude/commands/geo-optimize.md @@ -2,24 +2,6 @@ Rewrites and restructures documentation to improve discoverability in AI-powered search tools (ChatGPT, Perplexity, Gemini, Claude, and similar) and to surface content as direct answers in traditional search results. Covers both **AEO** (Answer Engine Optimization — featured snippets, "People also ask") and **GEO** (Generative Engine Optimization — LLM citation and extraction). -## What this command does - -When you invoke `/geo-optimize`, Claude will: - -1. **Read the doc** -2. **Diagnose the current state**. Identify AEO and GEO gaps before making changes -3. **Propose specific improvements**. Show the user what will change and why -4. **Apply approved changes**. Rewrite only the sections the user approves -5. **Validate the result**. Confirm the doc is more answer- and citation-ready without breaking accuracy - -## When to use this command - -* New docs for features that are frequently searched in AI tools or voice search -* High-traffic docs that rarely appear in AI-generated answers or featured snippets -* Concept and reference docs where accuracy and citability matter most -* After `/seo-audit` flags AEO or GEO suggestions -* Before a product launch to maximize early visibility - ## What this command does NOT change * Technical accuracy — never alter facts, steps, code, or configuration values diff --git a/.claude/commands/release-note-collector.md b/.claude/commands/release-note-collector.md deleted file mode 100644 index faef82018f..0000000000 --- a/.claude/commands/release-note-collector.md +++ /dev/null @@ -1,404 +0,0 @@ -# Create New Collector Release Note - -Automates the creation of Collector release notes for Installed Collector versions and OpenTelemetry features. - -## What this command does - -When you invoke `release-note-collector`, Claude will guide you through: - -1. **Determine release type**. Installed Collector version or OpenTelemetry feature -2. **Gather release details**. Version number, changes, features, or fixes -3. **Create markdown file**. Generate file with proper frontmatter and structure -4. **Format content**. Apply correct formatting for version releases or features -5. **Validate and preview**. Check structure and provide next steps - -## When to use this command - -* Publishing new Installed Collector versions with bug or security fixes. -* Announcing OpenTelemetry collector features and improvements. -* Documenting collector version updates. -* Releasing new OpenTelemetry integrations or capabilities. - -## Release types - -### Installed Collector Release (`-installed.md`) - -For Installed Collector version releases: -* **Version numbers**: Format X.Y.Z-N (e.g., 19.535-6). -* **Security fixes**: CVE patches, dependency upgrades. -* **Bug fixes**: Issue resolutions and stability improvements. -* **Minor features**: Small enhancements in collector behavior. - -**Typical cadence**: As needed when versions ship - -### OpenTelemetry Release (`-otel.md`) - -For OpenTelemetry collector features: -* **New features**: Installation methods, integrations, capabilities. -* **Improvements**: Performance enhancements, reliability updates. -* **Announcements**: CDN changes, configuration updates. - -**Typical cadence**: As features are released - -## Workflow - -### Step 1: Gather information - -Ask the user for: - -**For Installed Collector releases:** -* **Version number**: Full version (e.g., 19.535-6). -* **Release date**: Date in YYYY-MM-DD format. -* **Changes**: List of security fixes, bug fixes, or features. - -**For OpenTelemetry releases:** -* **Feature name**: Name of the feature or update. -* **Release date**: Date in YYYY-MM-DD format. -* **Description**: What it does and why it matters (2-3 sentences). -* **Documentation link**: Relative path to the doc. - -**Validate:** -* Check that date is not in the future. -* For installed releases, validate version number format. -* For OTel releases, ensure documentation link exists. - -### Step 2: Create the markdown file - -**File naming convention:** -``` -blog-collector/YYYY-MM-DD-{type}.md -``` - -Examples: -* `blog-collector/2026-03-19-installed.md`. -* `blog-collector/2026-03-19-otel.md`. - -**Important**: Files are created in `/blog-collector/` directory - -### Step 3: Generate frontmatter - -**For Installed Collector releases:** -```yaml ---- -title: Installed Collector Version {X.Y.Z-N} -image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 -hide_table_of_contents: true -keywords: - - installed-collector ---- -``` - -**For OpenTelemetry releases:** -```yaml ---- -title: {Feature Name} -image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 -hide_table_of_contents: true -keywords: - - opentelemetry-collector ---- -``` - -**Title formatting:** -* Installed: "Installed Collector Version X.Y.Z-N" -* OTel: Feature name in Title Case (no category suffix) - -**Keywords:** -* Installed Collector: Always use `installed-collector` -* OpenTelemetry: Always use `opentelemetry-collector` -* These keywords are standard and do not need user confirmation - -### Step 4: Add required import - -For OpenTelemetry releases that use links or useBaseUrl: -```javascript -import useBaseUrl from '@docusaurus/useBaseUrl'; -``` - -**Note**: Only add if content uses it. For simple version releases, omit. - -### Step 5: Write content - -#### Installed Collector Release Structure - -```markdown -In this release, we've enhanced the security and stability of the Collector with added support for security patches. - -#### Security fix - -* {Security fix description with version numbers and CVE references}. -* {Additional security fixes}. - -#### Bug fix - -* {Bug fix description}. -* {Additional bug fixes}. -``` - -**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}." -* Use H4 (`####`) for section headings: Security fix, Bug fix, Feature -* 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 - -**Example:** -```markdown -In this release, we've enhanced the security and stability of the Collector with added support for security patches. - -#### Security fix - -* Upgraded `io.netty:netty-codec-http` to version **4.1.129.Final** to address known security vulnerability (CVE-2025-67735). -* Upgraded `com.fasterxml.jackson.core` packages to use patched version **2.18.6** to address known security vulnerability (GHSA-72hv-8253-57qq). - -#### Bug fix - -* Fixed an issue with forwarded Windows event collection that occurred on systems running with latest Windows version. -``` - -#### OpenTelemetry Release Structure - -```markdown -We're excited to {announce/introduce} {feature description}. {What it does and benefits}. [Learn more](/docs/path/to/doc). - -{Optional: Additional paragraphs with more details} - -{Optional: Related documentation list} - -{Optional: Important notes in admonition} -``` - -**OpenTelemetry Guidelines:** -* Start with "We're excited to announce..." or "We're excited to introduce...". -* Write 2-3 sentences in first paragraph. -* Focus on user benefits and business value. -* End first paragraph with "Learn more" link. -* 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):** -```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/). -``` - -**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. - -Refer to the following documentation to view the updated URLs in the UI. -* [Ansible](/docs/send-data/opentelemetry-collector/install-collector/ansible/). -* [Chef](/docs/send-data/opentelemetry-collector/install-collector/chef/). -* [Puppet](/docs/send-data/opentelemetry-collector/install-collector/puppet/). - -:::note -* Existing OpenTelemetry binaries and other packages remain in their current locations. -* This change does not affect the UI itself. The download process looks the same, but the underlying URL now uses a CDN to improve reliability and speed. -::: -``` - -### Step 6: Validation checklist - -Before finishing, verify: -* [ ] File created in `/blog-collector/` directory. -* [ ] Filename follows pattern: `YYYY-MM-DD-{type}.md` -* [ ] Frontmatter complete with all required fields. -* [ ] Title format correct (version number or feature name). -* [ ] `hide_table_of_contents: true` present -* [ ] Keywords correct for type (installed-collector or opentelemetry). -* [ ] 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: "Learn more" link included with relative path -* [ ] No trailing whitespace. - -## Example usage - -### Installed Collector Example - -``` -User: "Create a Collector release note for version 19.535-8 with a security fix for Netty and a bug fix for Windows events" - -Claude: -1. Confirms type: Installed Collector -2. Confirms date: 2026-03-19 -3. Creates: blog-collector/2026-03-19-installed.md -4. Generates frontmatter: "Installed Collector Version 19.535-8" -5. Adds standard intro paragraph -6. Creates Security fix section with Netty upgrade -7. Creates Bug fix section with Windows events fix -8. Provides checklist -``` - -### OpenTelemetry Example - -``` -User: "Create an OTel Collector release note about new Kubernetes monitoring support" - -Claude: -1. Confirms type: OpenTelemetry -2. Confirms date: 2026-03-19 -3. Asks for description and doc link -4. Creates: blog-collector/2026-03-19-otel.md -5. Generates frontmatter: "Kubernetes Monitoring Support" -6. Writes announcement with feature benefits -7. Adds "Learn more" link -8. Provides checklist -``` - -## Version number format - -Installed Collector versions follow this pattern: -``` -Major.Minor.Patch-Build -``` - -Examples: -* `19.535-6` — Version 19.535, build 6. -* `19.535-4` — Version 19.535, build 4. -* `20.0-1` — Version 20.0, build 1. - -**Formatting in title:** -* Always include full version with build number. -* No spaces around hyphen. -* Example: "Installed Collector Version 19.535-6" - -## Dependency upgrade format - -When listing upgraded dependencies: -* Use backticks for package names. -* Use **bold** for version numbers. -* Include full CVE or GHSA reference if applicable. - -**Examples:** -* ✅ `io.netty:netty-codec-http` to version **4.1.129.Final** to address known security vulnerability (CVE-2025-67735) -* ✅ `com.fasterxml.jackson.core` packages to use patched version **2.18.6** (GHSA-72hv-8253-57qq). -* ✅ Collector JRE to **Amazon Corretto Version 17.0.18.8.1**. -* ❌ Upgraded netty-codec-http to 4.1.129.Final (missing backticks and bold). - -## Safety principles - -* **Check existing files** before creating to avoid duplicates. -* **Validate version numbers** follow the correct format. -* **Verify CVE/GHSA references** are accurate. -* **Use consistent formatting** for dependencies and versions. -* **Keep installed releases brief**. Just the facts. -* **Focus OTel releases on benefits** not technical details. - -## Post-completion message - -After successfully creating the release note, tell the user: - -**For Installed Collector:** -``` -✅ Installed Collector release note created successfully! - -File created: -* 📄 blog-collector/{date}-installed.md. - -Summary: -* Version: {version} -* Security fixes: {count} -* Bug fixes: {count} - -Next steps: -1. Review CVE/GHSA references for accuracy -2. Verify version numbers are correct -3. Ensure all fixes are documented -4. Test locally: yarn start -5. Check preview at: http://localhost:3000/release-notes-collector -6. Submit PR: "DOCS-XXX - Installed Collector {version} release notes" - -Checklist: -* [ ] Version number is correct. -* [ ] All security vulnerabilities referenced. -* [ ] Dependencies use backticks and bold versions. -* [ ] Bug fixes are complete. - -The release note will appear on the Collector release notes page in reverse chronological order (newest first). -``` - -**For OpenTelemetry:** -``` -✅ OpenTelemetry Collector release note created successfully! - -File created: -* 📄 blog-collector/{date}-otel.md. - -Summary: -* Feature: {Feature Name} -* Keywords: opentelemetry - -Next steps: -1. Review content for accuracy and clarity -2. Verify documentation link is correct -3. Ensure feature name and description are clear -4. Test locally: yarn start -5. Check preview at: http://localhost:3000/release-notes-collector -6. Submit PR: "DOCS-XXX - OTel Collector: {Feature Name}" - -Checklist: -* [ ] Feature name is clear and concise. -* [ ] Description focuses on user benefits. -* [ ] Documentation link is correct. -* [ ] No placeholder text remaining. - -The release note will appear on the Collector release notes page in reverse chronological order (newest first). - -Would you like me to help refine the description or add additional details? -``` - -## Error handling - -**If file already exists:** -* Show existing file content. -* Ask if user wants to: - * Use different type (installed vs otel). - * Use different date. - * Overwrite (requires confirmation). - -**If version number format is invalid:** -* Show expected format: X.Y.Z-N -* Ask for correction. - -**If CVE/GHSA reference looks incomplete:** -* Warn about format. -* Ask for confirmation. - -**If documentation link looks wrong (OTel):** -* Warn if does not start with `/docs/`. -* Suggest correction. - -## Tips and best practices - -**Installed Collector releases:** -* Be specific about what was fixed or upgraded. -* Include exact version numbers. -* Reference CVEs and GHSAs when applicable. -* Keep descriptions factual and brief. -* Order matters: Security → Bugs → Features - -**OpenTelemetry releases:** -* Lead with user benefit. -* Explain why the change matters. -* Link to comprehensive documentation. -* Use admonitions for breaking changes or important notes. - -**Both types:** -* Use consistent formatting throughout. -* Keep language simple and direct. -* Avoid unnecessary technical jargon. -* Focus on what changed, not how it was implemented. - -## References - -* [Collector Release Notes](https://sumologic.com/help/release-notes-collector) -* [Release Notes Index](/docs/release-notes). -* [Style Guide](/docs/contributing/style-guide). diff --git a/.claude/commands/release-note-cse.md b/.claude/commands/release-note-cse.md deleted file mode 100644 index 41e36c6c66..0000000000 --- a/.claude/commands/release-note-cse.md +++ /dev/null @@ -1,419 +0,0 @@ -# Create New Cloud SIEM Release Note - -Automates the creation of Cloud SIEM (CSE) release notes with proper formatting, frontmatter, and structure. - -## What this command does - -When you invoke `release-note-cse`, Claude will guide you through: - -1. **Determine release type**. Content release or Application release -2. **Gather release details**. Date, changes, features, bug fixes -3. **Create markdown file**. Generate file with proper frontmatter and structure -4. **Format content**. Apply correct formatting for rules, mappers, parsers, or features -5. **Validate and preview**. Check structure and provide next steps - -## When to use this command - -* Publishing Cloud SIEM content updates (rules, log mappers, parsers). -* Announcing new Cloud SIEM features or bug fixes. -* Creating regular bi-weekly or monthly CSE release notes. -* Documenting Cloud SIEM application updates. - -## Release types - -### Content Release (`-content.md`) - -For updates to Cloud SIEM detection content: -* **Rules**: New or updated detection rules -* **Log Mappers**: New or updated log mapping configurations -* **Parsers**: Parser updates and enhancements -* **Schema changes**: New fields or tags - -**Typical cadence**: Every 1-2 weeks - -### Application Release (`-application.md`) - -For Cloud SIEM product features and updates: -* **New features**: UI improvements, new capabilities -* **Bug fixes**: Issue resolutions -* **Performance improvements**: Optimizations -* **Breaking changes or deprecations**. - -**Typical cadence**: As needed when features ship - -## Workflow - -### Step 1: Gather information - -Ask the user for: - -**Required:** -* **Release type**: Content or Application -* **Release date**: Date in YYYY-MM-DD format -* **Changes**: List of what's included - -**For Content Releases:** -* New/updated rules (rule IDs and names). -* New/updated log mappers. -* New/updated parsers. -* Brief summary of changes. - -**For Application Releases:** -* Feature name and description. -* Documentation links. -* Screenshots (if applicable). -* Any breaking changes. - -**Keywords (for both types):** -* Ask user to confirm or customize keywords -* Suggest defaults based on release type (see frontmatter section below) - -**Validate:** -* Check that date is not in the future (use today's date if not specified). -* Ensure file does not already exist for this date and type. -* Confirm changes are ready to publish. -* Confirm keywords with user before creating file. - -### Step 2: Create the markdown file - -**File naming convention:** -``` -blog-cse/YYYY-MM-DD-{type}.md -``` - -Examples: -* `blog-cse/2026-03-19-content.md`. -* `blog-cse/2026-03-19-application.md`. - -**Important**: Files are created in `/blog-cse/` directory, NOT in `/docs/` - -### Step 3: Generate frontmatter - -**For Content Releases:** -```yaml ---- -title: {Month} {Day}th, {Year} - Content Release -hide_table_of_contents: true -keywords: - * rules - * log mappers - * parsers -image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 ---- -``` - -**For Application Releases:** -```yaml ---- -title: {Month} {Day}, {Year} - Application Update -image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 -keywords: - * {relevant-keyword} -hide_table_of_contents: true ---- -``` - -**Keywords guidance:** -* **Always ask user to confirm keywords before creating file** -* Suggested defaults: - * Content releases: `rules`, `log mappers`, `parsers` - * 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. - -### Step 4: Add required import - -Always include after frontmatter: -```javascript -import useBaseUrl from '@docusaurus/useBaseUrl'; -``` - -### Step 5: Write content - -#### Content Release Structure - -```markdown -This content release includes: - - {High-level summary point 1} - - {High-level summary point 2} - - {High-level summary point 3} - -Additional changes are enumerated below. - -### Rules -* [New] MATCH-SXXXX Rule Name. -* [Updated] FIRST-SXXXX Rule Name. Brief description of what changed. - -### Log Mappers -* [New] Vendor - Event Type. -* [Updated] Vendor - Event Type. - -### Parsers -* [Updated] /Parsers/System/Vendor/Parser Name. -``` - -**Content Release Guidelines:** -* Start with bulleted summary (3-5 high-level points). -* Use indentation (4 spaces) for bullet points. -* Group changes by type: Rules, Log Mappers, Parsers -* Use `[New]` or `[Updated]` tags. -* Rule IDs use format: `MATCH-SXXXX`, `FIRST-SXXXX`, `THRESHOLD-SXXXX` -* Parser paths use full hierarchy: `/Parsers/System/Vendor/Name` -* Add brief explanations for significant updates. -* Sort items alphabetically within each section. - -#### Application Release Structure - -```markdown -### {Feature Name} - -{Feature description and business value}. [Learn more](/docs/path/to/docs). - -{Optional screenshot or additional details} -``` - -**Application Release Guidelines:** -* Use H3 (`###`) for each feature. -* Start with clear, concise description. -* 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. - -### 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" - -Examples: -* ✅ "March 19th, 2026 - Content Release". -* ✅ "February 3rd, 2026 - Application Update". -* ❌ "Mar 19, 2026 - Content Release" (month abbreviated). -* ❌ "March 19 2026 - Content Release" (missing "th"). - -### Step 7: Validation checklist - -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. -* [ ] `hide_table_of_contents: true` present -* [ ] Keywords appropriate for release type. -* [ ] `import useBaseUrl` statement included. -* [ ] Content follows proper structure (Rules → Log Mappers → Parsers). -* [ ] All `[New]` and `[Updated]` tags present. -* [ ] Parser paths use full `/Parsers/System/Vendor/Name` format. -* [ ] Links use relative paths or `useBaseUrl`. -* [ ] No trailing whitespace or extra blank lines. - -## Example usage - -### Content Release Example - -``` -User: "Create a CSE content release for today with updates to AWS CloudTrail rules and new Okta log mappers" - -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" -5. Adds summary section -6. Creates sections for Rules and Log Mappers -7. Formats with proper [New]/[Updated] tags -8. Provides checklist and next steps -``` - -### Application Release Example - -``` -User: "Create a CSE application release for March 15th about the new bulk insight update feature" - -Claude: -1. Confirms date: 2026-03-15 -2. Confirms type: Application Release -3. Creates: blog-cse/2026-03-15-application.md -4. Generates frontmatter: "March 15, 2026 - Application Update" -5. Adds feature section with H3 heading -6. Includes description and Learn more link -7. Provides checklist -``` - -## Common patterns - -### Rule ID formats - -* `MATCH-SXXXX` — Match rules (most common). -* `FIRST-SXXXX` — First Seen rules. -* `THRESHOLD-SXXXX` — Threshold rules. -* `AGGREGATION-SXXXX` — Aggregation rules. -* `CHAIN-SXXXX` — Chain rules. -* `OUTLIER-SXXXX` — Outlier rules. - -### Parser path structure - -Always use full path: -``` -/Parsers/System/{Vendor}/{Parser Name} -``` - -Examples: -* `/Parsers/System/AWS/AWS CloudTrail`. -* `/Parsers/System/Okta/Okta`. -* `/Parsers/System/Microsoft/Microsoft 365`. -* `/Parsers/System/Cisco/Cisco ASA`. - -### Log Mapper naming - -Format: `{Vendor} - {Event Type}` - -Examples: -* `Okta - Authentication Events`. -* `AWS CloudTrail - Management Events`. -* `Microsoft 365 - Audit Logs`. -* `CrowdStrike Falcon - Detection Events`. - -### Vendor consistency - -Use standard vendor names: -* ✅ "Microsoft 365" (not "Office 365", "O365"). -* ✅ "Google Workspace" (not "G Suite", "GSuite"). -* ✅ "SonicWall Firewall" (not "Dell SonicWall"). -* ✅ "AWS CloudTrail" (not "Amazon CloudTrail"). - -## Archive process - -**When to archive:** -* At year-end, older releases move to archive files. -* Archive files are in `/blog-cse/{YEAR}/12-31.md`. -* Current year + 1-2 prior years remain active. -* Older years are archived. - -**Archive structure:** -```markdown ---- -title: {Year} Release Notes Archive - Cloud SIEM -keywords: [rules, signals, schema, log mappers, parsers, cloud siem] -image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 ---- - -import useBaseUrl from '@docusaurus/useBaseUrl'; - -This is an archive of {Year} Cloud SIEM release notes. [View the full archive](/release-notes-cse/archive). - - - ---- - -### {Month} {Day}, {Year} - {Type} - -{Content} - ---- -``` - -**Note:** Users typically do not need to manage archives manually. Mention this only if they ask about archiving old releases. - -## Safety principles - -* **Check existing files** before creating to avoid duplicates. -* **Validate dates** are not in the future. -* **Use consistent vendor names** (check existing releases for precedent). -* **Preserve exact rule IDs** when user provides them. -* **Do not invent rule IDs**. Ask user if not provided. -* **Link to docs** when mentioning features. - -## Post-completion message - -After successfully creating the release note, tell the user: - -``` -✅ Cloud SIEM release note created successfully! - -File created: -* 📄 blog-cse/{date}-{type}.md. - -Summary: -* Type: {Content Release | Application Update} -* Date: {formatted date} -* Changes: {count} rules, {count} log mappers, {count} parsers - -Next steps: -1. Review content for accuracy -2. Add any missing details or descriptions -3. Verify all rule IDs and parser paths are correct -4. Add screenshots for application updates (if applicable) -5. Test locally: yarn start -6. Check preview at: http://localhost:3000/release-notes-cse -7. Submit PR: "DOCS-XXX - CSE {type} release notes for {date}" - -Checklist: -* [ ] All rule IDs verified. -* [ ] Parser paths use full /Parsers/System/ format. -* [ ] Vendor names consistent with existing releases. -* [ ] Links tested and working. -* [ ] No placeholder text remaining. - -The release note will appear on the Cloud SIEM release notes page in reverse chronological order (newest first). - -Would you like me to help fill in any additional details? -``` - -## Error handling - -**If file already exists:** -* Show existing file path and date. -* Ask if user wants to: - * Add to existing release (append content). - * Create with different date. - * Overwrite (requires confirmation). - -**If date is invalid:** -* Show error and ask for correct format (YYYY-MM-DD). -* Suggest today's date as default. - -**If rule IDs do not match pattern:** -* Warn user about non-standard format. -* Ask for confirmation before proceeding. - -**If vendor names are inconsistent:** -* Check recent releases for the vendor. -* Suggest standard name. -* Ask user to confirm. - -## Tips and best practices - -**Content releases:** -* Lead with most significant changes in summary. -* Group related changes together (e.g., all Okta updates). -* Include context for major updates ("Updated detection expression for improved query performance"). -* Keep descriptions concise (one sentence per update). - -**Application releases:** -* Lead with user benefit, not technical details. -* Always link to documentation. -* Use screenshots for UI changes. -* Mention if feature requires admin privileges. - -**General:** -* Be consistent with formatting across releases. -* Use active voice ("Added support for.." not "Support was added.."). -* Spell out acronyms on first use in each release. -* Keep release notes focused on what changed, not why. - -## References - -* [Cloud SIEM Release Notes](https://sumologic.com/help/release-notes-cse) -* [Release Notes Index](/docs/release-notes). -* [Style Guide](/docs/contributing/style-guide). diff --git a/.claude/commands/release-note-csoar.md b/.claude/commands/release-note-csoar.md deleted file mode 100644 index ebe2508bbd..0000000000 --- a/.claude/commands/release-note-csoar.md +++ /dev/null @@ -1,605 +0,0 @@ -# Create New Cloud SOAR Release Note - -Automates the creation of Cloud SOAR (Automation Service) release notes for platform updates, integration changes, and bug fixes. - -## What this command does - -When you invoke `release-note-csoar`, Claude will guide you through: - -1. **Determine release type**. Content Release or Application Update -2. **Gather release details**. Date, changes, integrations, playbooks, or platform updates -3. **Create markdown file**. Generate file with proper frontmatter and structure -4. **Format content**. Apply correct formatting for the release type -5. **Validate and preview**. Check structure and provide next steps - -## When to use this command - -* Publishing new integrations and playbooks (Content Release) -* Publishing Cloud SOAR platform updates (Application Update) -* Documenting integration updates or bug fixes -* Announcing new API endpoints or features -* Releasing playbook improvements - -## Release types - -### Content Release (`-content-release.md`) - -For releases focused on new content (integrations and playbooks): -* **New integrations**: Brand new integrations added to App Central -* **Updated integrations**: Improvements to existing integrations -* **New playbooks**: New playbooks with ID numbers and titles -* **Simple format**: Just lists of what's new/updated, minimal descriptions - -**Typical cadence**: Monthly or as content batches are released - -### Application Update (`-application-update.md`) - -For platform features, enhancements, and bug fixes: -* **Platform features**: New capabilities, UX improvements, APIs -* **Integration changes**: With detailed descriptions of what changed -* **Bug fixes**: Issues resolved in integrations, platform, or playbooks -* **Detailed format**: Sections with descriptions and context - -**Typical cadence**: Monthly, published early the following month - -## Release structure (varies by type) - -### Content Release Structure - -Simple format with just lists: - -1. **Intro paragraph** - Brief description of release -2. **Integrations** (H3) - Bulleted list of [New]/[Updated] integrations -3. **Playbooks** (H3) - Bulleted list of [New] playbooks with IDs and titles - -### Application Update Structure - -Detailed format with descriptions and bug fixes: - -1. **Release month header** (H2) - "## {Month} release" -2. **Changes and enhancements** (H3) - - **Integrations** (H4) - New or updated integrations with descriptions - - **Platform** (H4) - Platform features and improvements - - **Playbooks** (H4) - Playbook-related changes (optional) -3. **Bug Fixes** (H3) - - **Integrations** (H4) - Integration bug fixes - - **Platform** (H4) - Platform bug fixes - - **Playbooks** (H4) - Playbook bug fixes - -## Workflow - -### Step 1: Determine release type - -Ask the user which type of release: - -**Content Release** - For new integrations and playbooks -* Simple list format -* No detailed descriptions -* No bug fixes section -* Use when: Releasing batch of new content - -**Application Update** - For platform features and bug fixes -* Detailed descriptions -* Bug fixes section -* Organized by month -* Use when: Monthly platform updates - -### Step 2: Gather information - -**For Content Release:** -* **Publication date**: Date in YYYY-MM-DD format -* **New integrations**: List of integrations to add -* **Updated integrations**: List of integrations to update -* **New playbooks**: List with ID numbers and titles (if any) - -**For Application Update:** -* **Release month**: Which month is this release for? (e.g., "February") -* **Publication date**: Date in YYYY-MM-DD format (typically early next month) -* **Integration changes**: New or updated integrations with descriptions -* **Platform changes**: Platform features and improvements -* **Bug fixes**: List of bugs fixed - -**Keywords (for both types):** -* Ask user to confirm or customize keywords -* Suggested defaults (see frontmatter section below) - -**Validate:** -* Check that date is not in the future -* For Application Update: Ensure release month aligns with publication date -* Verify integration links are valid -* Confirm keywords with user before creating file - -### Step 3: Create the markdown file - -**File naming convention:** - -For Content Release: -``` -blog-csoar/YYYY-MM-DD-content-release.md -``` - -For Application Update: -``` -blog-csoar/YYYY-MM-DD-application-update.md -``` - -Examples: -* `blog-csoar/2024-06-05-content-release.md` -* `blog-csoar/2026-03-06-application-update.md` - -**Important**: Files are created in `/blog-csoar/` directory (root level) - -### Step 4: Generate frontmatter - -**For Content Release:** -```yaml ---- -title: {Month DD, 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: - - automation service - - cloud soar - - soar ---- -``` - -**For Application Update:** -```yaml ---- -title: {Month DD, 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: - - automation service - - cloud soar ---- -``` - -**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) - -**Keywords:** -* **Always ask user to confirm keywords before creating file** -* Suggested defaults: - * Content Release: `automation service`, `cloud soar`, `soar` (three keywords) - * Application Update: `automation service`, `cloud soar` (two keywords) -* User may want to add additional keywords based on specific content (e.g., `integrations`, `playbooks`, `api`, `platform`) - -**Image:** -* Both types use the same standard Sumo Logic preview image: - * `https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082` - -### Step 5: Add required import - -**For both types**, add the useBaseUrl import after frontmatter: -```javascript -import useBaseUrl from '@docusaurus/useBaseUrl'; -``` - -### Step 6: Write content structure - -**Content Release template:** -```markdown ---- -title: June 05, 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: - - automation service - - cloud soar - - soar ---- - -import useBaseUrl from '@docusaurus/useBaseUrl'; - -This release introduces new integrations, new playbooks, and several updates. - -### Integrations - -* [New] [AWS WAF](/docs/platform-services/automation-service/app-central/integrations/aws-waf) -* [Updated] [Okta](/docs/platform-services/automation-service/app-central/integrations/okta) - -### Playbooks - -* [New] 541 - Management of AWS EKS Insights -* [New] 542 - Resolution of AWS EKS Insights -``` - -**Application Update template:** -```markdown ---- -title: March 06, 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: - - automation service - - cloud soar ---- - -import useBaseUrl from '@docusaurus/useBaseUrl'; - -## {Month} release - -Following are the updates made in {Month} {YYYY}. - -### Changes and enhancements - -#### Integrations - -* [Added] [Integration Name](/docs/path/to/integration/) - Description of what was added. -* [Updated] [Integration Name](/docs/path/to/integration/) - Description of what was updated. - -#### Platform - -* Description of platform enhancement or feature. -* Description of another platform change. - -### Bug Fixes - -#### Integrations - -* In the [Integration Name](/docs/path/to/integration/) integration, description of bug fix. - -#### Platform - -Fixed an issue where [description of bug and fix]. -``` - -### Step 7: Content formatting guidelines - -## Content Release Formatting - -#### Intro Paragraph - -* Simple one-sentence description -* Format: "This release introduces {what's new}." -* Examples: - * "This release introduces new integrations, new playbooks, and several updates." - * "This release introduces new integrations and updates to existing integrations." - -#### Integrations Section (H3) - -* Simple bulleted list with [New] or [Updated] tags -* Format: `* [Tag] [Integration Name](link)` -* NO descriptions needed - just link to integration doc -* Links use full path: `/docs/platform-services/automation-service/app-central/integrations/{slug}` - -**Example:** -```markdown -### Integrations - -* [New] [AWS WAF](/docs/platform-services/automation-service/app-central/integrations/aws-waf) -* [New] [Cyberint](/docs/platform-services/automation-service/app-central/integrations/cyberint) -* [Updated] [Okta](/docs/platform-services/automation-service/app-central/integrations/okta) -* [Updated] [ServiceNow V2](/docs/platform-services/automation-service/app-central/integrations/servicenow-v2) -``` - -#### Playbooks Section (H3) - -* Optional - only if new playbooks released -* Format: `* [New] {ID} - {Playbook Title}` -* ID is a number (e.g., 541, 542, 543) -* Use "- " between ID and title - -**Example:** -```markdown -### Playbooks - -* [New] 541 - Management of AWS EKS Insights -* [New] 542 - Resolution of AWS EKS Insights -* [New] 543 - Alert and Vulnerability detection with Sysdig Secure -``` - -## Application Update Formatting - -#### Release Month Header (H2) - -* Always use H2 (`##`) for the month -* Format: "## {Month} release" -* Examples: "## February release", "## March release" -* Followed by: "Following are the updates made in {Month} {YYYY}." - -#### Changes and Enhancements Section - -**Integrations subsection:** -* Use tags: `[Added]` for new integrations, `[Updated]` for existing ones -* Format: `[Tag] [Integration Name](link) - Description.` -* Link to integration documentation in `/docs/platform-services/automation-service/app-central/integrations/` -* Be specific about what action or feature was added/updated -* Can mention specific actions: "Added 'Count Occurrence Of Value' action" - -**Example:** -```markdown -#### Integrations - -* [Added] [Sumo Logic Automation Tools](/docs/platform-services/automation-service/app-central/integrations/sumo-logic-automation-tools/) - Added "Count Occurrence Of Value" action to count the occurrence of a specified value in texts. -* [Updated] [ThreatConnect V3](/docs/platform-services/automation-service/app-central/integrations/threatconnect-v3/) - Added observations parameter to the Update Intelligence action to enable recording observation counts for indicators. -``` - -**Platform subsection:** -* List platform-wide changes or features -* Focus on user-facing improvements -* Can include UX enhancements, new APIs, or system improvements -* Use clear, simple language - -**Example:** -```markdown -#### Platform - -* Improved the sorting UX experience on all tables in Cloud SOAR and the Automation Service to align with other Sumo Logic modules. -* Deleted records will no longer be fetched during table searches unless the `Deleted` filter is applied. -* Added new public APIs: - * [Add playbooks to an incident](https://api.sumologic.com/docs/csoar/#operation/incidents_runbook_create). - * [Retrieve all playbooks attached to a specific incident](https://api.sumologic.com/docs/csoar/#operation/incidents_runbook_retrieve). -``` - -**Playbooks subsection (optional):** -* Only include if there are playbook-specific changes -* Format similar to platform changes - -#### Bug Fixes Section - -* Group by subsection: Integrations, Platform, Playbooks -* For integrations: Start with "In the [Integration Name](link) integration, ..." -* For platform/playbooks: Use "Fixed an issue where..." or direct description -* Be specific about what was fixed - -**Example:** -```markdown -### Bug Fixes - -#### Integrations - -* In the [Microsoft EWS (Graph)](/docs/platform-services/automation-service/app-central/integrations/microsoft-ews-graph/) integration, removed the default values for the `has_attachments` and `un_read` fields in the Search Emails Extended action. The change allows users to search for emails without being forced to filter by attachment status or read/unread status. - -#### Platform - -Fixed an issue where query filters were being applied incorrectly during search. - -#### Playbooks - -Fixed issues while selecting variables containing the period character in textarea fields and test node input. -``` - -### Step 8: Validation checklist - -**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") -* [ ] Image URL: Standard Sumo Logic preview image -* [ ] Keywords: automation service, cloud soar, soar (three keywords) -* [ ] `hide_table_of_contents: true` is present -* [ ] Import statement included -* [ ] Simple intro paragraph present -* [ ] Integrations section uses [New]/[Updated] tags -* [ ] Integration links have NO descriptions (just links) -* [ ] Playbooks section uses [New] with ID numbers (if included) -* [ ] No trailing whitespace - -**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") -* [ ] Image URL: Standard Sumo Logic preview image -* [ ] Keywords: automation service, cloud soar (two keywords) -* [ ] `hide_table_of_contents: true` is present -* [ ] Import statement included -* [ ] H2 header: "## {Month} release" -* [ ] Intro: "Following are the updates made in {Month} {YYYY}." -* [ ] Integration changes use [Added]/[Updated] WITH descriptions -* [ ] Integration links point to correct paths -* [ ] All sections properly formatted (H3 for main, H4 for subsections) -* [ ] No trailing whitespace - -## Example usage - -### Content Release Example - -``` -User: "Create a Cloud SOAR content release for June 5, 2024, with new AWS integrations and playbooks" - -Claude: -1. Confirms type: Content Release -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" - - image: Standard Sumo Logic preview image - - keywords: automation service, cloud soar, soar -5. Writes content with: - - Simple intro: "This release introduces new integrations, new playbooks, and several updates." - - Integrations section with [New]/[Updated] tags (no descriptions) - - Playbooks section with ID numbers -6. Provides checklist -``` - -### Application Update Example - -``` -User: "Create a Cloud SOAR release note for February 2026, published March 6, with integration updates and bug fixes" - -Claude: -1. Confirms type: Application Update -2. Confirms publication date: March 6, 2026 -3. Confirms release month: February -4. Creates: blog-csoar/2026-03-06-application-update.md -5. Generates frontmatter: - - title: "March 06, 2026 - Application Update" - - keywords: automation service, cloud soar -6. Writes content with: - - H2: "## February release" - - Intro: "Following are the updates made in February 2026." - - Changes and enhancements section (with descriptions) - - Bug fixes section -7. Provides checklist -``` - -## Integration documentation paths - -Integration docs are located at: -``` -/docs/platform-services/automation-service/app-central/integrations/{integration-slug}/ -``` - -**Common integrations:** -* Microsoft EWS (Graph): `/docs/platform-services/automation-service/app-central/integrations/microsoft-ews-graph/` -* ThreatConnect V3: `/docs/platform-services/automation-service/app-central/integrations/threatconnect-v3/` -* Atlassian Opsgenie: `/docs/platform-services/automation-service/app-central/integrations/atlassian-opsgenie/` -* Sumo Logic Automation Tools: `/docs/platform-services/automation-service/app-central/integrations/sumo-logic-automation-tools/` - -**Tip**: Integration slugs are lowercase with hyphens. If unsure, use Grep to find the integration doc. - -## API documentation links - -Cloud SOAR API docs: -* API reference: `https://api.sumologic.com/docs/csoar/` -* Cloud SOAR automation docs: `/docs/cloud-soar/automation/` - -## 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) - -**Examples:** -* ✅ March 06, 2026 -* ✅ January 08, 2026 -* ✅ December 31, 2025 -* ✅ June 05, 2024 -* ❌ March 6, 2026 (not zero-padded) -* ❌ March 6th, 2026 (has ordinal) -* ❌ Mar 06, 2026 (abbreviated month) -* ❌ 2026-03-06 (wrong format) - -## Release timing - -**Important**: Cloud SOAR release notes are typically published early the following month for the previous month's changes. - -**Pattern:** -* February changes → Published early March (e.g., March 6) -* January changes → Published early February -* December changes → Published early January - -**In the file:** -* Filename uses publication date: `2026-03-06-application-update.md` -* Title uses publication date: "March 6, 2026 - Application Update" -* H2 uses release month: "## February release" -* Intro uses release month: "Following are the updates made in February 2026." - -## Safety principles - -* **Check for existing files** before creating to avoid duplicates -* **Validate release month alignment** with publication date -* **Verify integration links** exist before including them -* **Use consistent formatting** for all integration changes -* **Include both keywords**. Automation service and cloud soar -* **Group bug fixes by category** for clarity -* **Keep descriptions concise** but informative - -## Post-completion message - -After successfully creating the release note, tell the user: - -``` -✅ Cloud SOAR release note created successfully! - -File created: -* 📄 blog-csoar/{YYYY-MM-DD}-application-update.md - -Summary: -* 📅 Publication: {Month Day, YYYY} -* 📆 Release month: {Month} -* 🔧 Integration updates: {count} -* 🐛 Bug fixes: {count} - -Next steps: -1. Review all integration links are correct -2. Verify bug fix descriptions are accurate -3. Ensure release month matches publication date -4. Test locally: yarn start -5. Check preview at: http://localhost:3000/release-notes-csoar -6. Submit PR: "DOCS-XXX - Cloud SOAR {Month} release notes" - -Checklist: -* [ ] Filename is {date}-application-update.md -* [ ] Title follows "Month Day, YYYY - Application Update" format -* [ ] H2 header is "## {Month} release" -* [ ] Integration changes use [Added]/[Updated] tags -* [ ] All integration links are valid -* [ ] Keywords include automation service and cloud soar -* [ ] Bug fixes grouped by category - -The release note will appear on the Cloud SOAR release notes page in reverse chronological order (newest first). - -Would you like me to help refine any sections or add additional details? -``` - -## Error handling - -**If file already exists:** -* Show existing file path and date -* Ask if user wants to: - * Update existing file (add more content) - * Use different date - * Create anyway (overwrite - requires confirmation) - -**If release month doesn't match date:** -* Warn user about mismatch -* Example: "March 6 publication should be for February release, not March" -* Ask for confirmation or correction - -**If integration link looks invalid:** -* Warn if doesn't follow standard path pattern -* Suggest searching for correct integration doc -* Proceed with user confirmation - -**If date is in the future:** -* Warn user and ask for confirmation -* Suggest using current date - -## Tips and best practices - -**For integration changes:** -* Be specific about what actions were added or updated -* Include the purpose or benefit of the change -* Always link to integration documentation -* Use [Added] for completely new integrations -* Use [Updated] for changes to existing integrations - -**For platform changes:** -* Focus on user-facing improvements -* Explain the benefit or impact -* Group related changes together -* Include API links when relevant - -**For bug fixes:** -* Clearly describe what was fixed -* Explain the previous behavior and new behavior -* Group by category for organization - -**All sections:** -* Keep language clear and concise -* Focus on what changed and why it matters -* Use bullet points for easy scanning -* Maintain consistent formatting - -## References - -* [Cloud SOAR Release Notes](https://sumologic.com/help/release-notes-csoar) -* [Cloud SOAR Documentation](/docs/cloud-soar) -* [Automation Service](/docs/platform-services/automation-service) -* [App Central Integrations](/docs/platform-services/automation-service/app-central/integrations) -* [Style Guide](/docs/contributing/style-guide) diff --git a/.claude/commands/release-note-developer.md b/.claude/commands/release-note-developer.md deleted file mode 100644 index 8b11cce1d0..0000000000 --- a/.claude/commands/release-note-developer.md +++ /dev/null @@ -1,504 +0,0 @@ -# Create New Developer Release Note - -Automates the creation of Developer release notes for APIs, SDKs, integrations, and platform changes relevant to developers. - -## What this command does - -When you invoke `release-note-developer`, Claude will guide you through: - -1. **Gather release details**. Category, date, title, and content -2. **Create markdown file**. Generate file with proper frontmatter and structure -3. **Format content**. Apply correct formatting for the release type -4. **Validate and preview**. Check structure and provide next steps - -## When to use this command - -* Announcing new API endpoints or features -* Documenting API changes, deprecations, or breaking changes -* Publishing SDK updates or new SDK versions -* Releasing developer tools or CLI updates -* Announcing platform changes affecting developers -* Documenting authentication or integration changes -* Publishing deprecation notices - -## Release categories - -Developer release notes typically cover: - -* **APIs**. New endpoints, changes, deprecations -* **SDKs**. New SDKs, version updates, improvements -* **CLI**. Command-line tool updates -* **Integrations**. New integrations or integration changes -* **Platform**. Platform changes affecting developers -* **Security**. Authentication, authorization changes -* **Deprecations**. End-of-life announcements - -## Workflow - -### Step 1: Gather information - -Ask the user for: - -**Required:** -* **Title/Topic**: Brief description of what this release is about -* **Release date**: Date in YYYY-MM-DD format -* **Content**: The release note content (what changed, why it matters) - -**Optional:** -* **Impact level**: Breaking change, deprecation, new feature, minor change -* **Documentation links**: Related doc pages -* **Slug**: Custom slug for filename (auto-generated from title if not provided) -* **Keywords**: Custom keywords for frontmatter (suggest defaults based on content) - -**Validate:** -* Check that date is not in the future -* Ensure content is clear and concise -* Verify any doc links are valid relative paths -* Ask user to confirm keywords before creating file - -### Step 2: Create the markdown file - -**File naming convention:** -``` -blog-developer/YYYY-MM-DD-{slug}.md -``` - -**Slug generation:** -* Lowercase the title -* Replace spaces with hyphens -* Remove special characters -* Keep concise (3-5 words max) - -Examples: -* `blog-developer/2026-03-23-api-endpoints.md` -* `blog-developer/2026-04-09-india-datacenter-deprecation.md` -* `blog-developer/2026-05-15-python-sdk-v2.md` - -**Important**: Files are created in `/blog-developer/` directory (root level, no subdirectories) - -### Step 3: Generate frontmatter - -**Standard frontmatter:** -```yaml ---- -title: {Month Day, YYYY} - {Topic} -image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 -hide_table_of_contents: true ---- -``` - -**Title formatting:** -* Start with full date: "Month Day, YYYY" (e.g., "April 9, 2025") -* Follow with " - " separator -* Add topic in Title Case (e.g., "Deprecation of Sumo Logic India Data Center") -* 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" - -**Image:** -* Always use the standard Sumo Logic preview image -* URL: `https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082` - -**Keywords (optional but recommended):** -* **Always ask user if they want to include keywords** -* Suggest keywords based on content type: - * API changes: `api`, `endpoints`, `rest-api` - * SDK updates: `sdk`, `python`, `java`, etc. - * Deprecations: `deprecation`, `end-of-life` - * Breaking changes: `breaking-change` - * Platform updates: `platform`, `datacenter` -* Format: - ```yaml - keywords: - - api - - deprecation - ``` -* User can choose to omit keywords or customize the list - -### Step 4: Add optional import - -For release notes that use links or useBaseUrl: -```javascript -import useBaseUrl from '@docusaurus/useBaseUrl'; -``` - -**Note**: Only add if content uses it. For simple text-only releases, omit. - -**Title guidelines:** -* Keep concise (2-5 words) -* Use title case -* Common patterns: "APIs", "SDKs", "CLI Tools", "Platform Updates" -* Can be more specific: "Python SDK", "REST API", "Management APIs" - -### Step 5: Write content - -Content goes directly after frontmatter (and optional import). No H3 heading needed — the title is in frontmatter. - -**Basic structure:** -```markdown ---- -title: March 23, 2026 - New Field Extraction Rules API -image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 -hide_table_of_contents: true ---- - -{Main content paragraph(s)} - -{Optional: H4 sections for subsections} - -{Optional: code blocks, lists, links} - -{Optional: admonitions for important notes} -``` - -### Step 6: Content formatting guidelines - -#### API Changes - -For API announcements, include: -* What changed (new endpoints, parameters, behavior) -* Impact on existing integrations -* Links to API documentation -* Migration guidance if breaking change - -**Example:** -```markdown ---- -title: March 23, 2026 - New Field Extraction Rules API -image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 -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 endpoints - -* **Field Extraction Rules API**: Create and manage Field Extraction Rules programmatically. See [Field Extraction Rules API](/docs/api/field-extraction-rules). -* **Webhook Connections API**: Create and manage webhook connections via API. See [Connections API](/docs/api/connections). - -#### Breaking changes - -**Monitors API**: The `notificationGroupFields` parameter is now required when creating monitors. Update your integrations before June 1, 2026. See the [Monitors API documentation](/docs/api/monitors) for details. -``` - -#### SDK Updates - -For SDK releases: -* Version number -* What's new or changed -* Installation instructions -* Link to SDK docs or GitHub - -**Example:** -```markdown ---- -title: March 23, 2026 - Python SDK Version 2.0 -image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 -hide_table_of_contents: true -keywords: - - sdk - - python ---- - -We've released version 2.0 of the Sumo Logic Python SDK with support for the latest APIs and improved error handling. - -#### What's new - -* Support for Field Extraction Rules API -* Async client support for better performance -* Improved error messages and debugging - -#### Installation - -```python -pip install sumologic-sdk==2.0.0 -``` - -Learn more in the [Python SDK documentation](/docs/api/python-client). -``` - -#### Deprecations - -For deprecation notices: -* What's being deprecated -* Why it's being deprecated (optional, if relevant) -* When it will be removed (end-of-life date) -* Migration path or alternatives -* Impact on existing users - -**Example (matches your template):** -```markdown ---- -title: April 9, 2025 - Deprecation of Sumo Logic India Data Center -image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 -hide_table_of_contents: true -keywords: - - deprecation - - datacenter ---- - -As previously communicated to impacted customers, effective as of April 30, 2025, customers will no longer be able to ingest data into the Sumo Logic Mumbai data center (`https://api.in.sumologic.com/`). Customers will retain access to historical data and basic search functionality until April 30, 2026, at which point all access will be terminated. - -Historical data will not be migrated to other deployments. - -**Reminder**: If you're still referencing the India endpoint, please update your integrations. For supported alternatives, see the [endpoint guide](/docs/api/about-apis/getting-started/#sumo-logic-endpoints-by-deployment-and-firewall-security). - -For help, contact [Support](https://support.sumologic.com/). -``` - -**Example (API deprecation):** -```markdown ---- -title: March 23, 2026 - Legacy Metrics API Deprecation -image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 -hide_table_of_contents: true -keywords: - - api - - deprecation ---- - -Effective **September 30, 2026**, the following legacy metrics API endpoints will be retired: -* `/v1/metrics/query` (use `/v2/metrics/query` instead) -* `/v1/metrics/catalog` (use `/v2/metrics/catalog` instead) - -**Migration**: Update your integrations to use the v2 endpoints. See the [Metrics API migration guide](/docs/api/metrics-migration) for details. - -**Impact**: After September 30, 2026, requests to legacy endpoints will return HTTP 410 (Gone). - -For help, contact [Support](https://support.sumologic.com/). -``` - -#### Minor Changes - -For small updates or enhancements: -* Brief description of the change -* Link to relevant docs -* Optional impact note - -**Example:** -```markdown ---- -title: March 23, 2026 - API Enhancements -image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 -hide_table_of_contents: true ---- - -We've made the following improvements to our APIs: - -* **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. -``` - -### Step 7: Validation checklist - -Before finishing, verify: -* [ ] File created in `/blog-developer/` directory (root level) -* [ ] Filename follows pattern: `YYYY-MM-DD-{slug}.md` -* [ ] Frontmatter complete with all required fields -* [ ] Title starts with "Month Day, YYYY - " format -* [ ] Date format uses full month name, no ordinal (e.g., "April 9" not "April 9th") -* [ ] `hide_table_of_contents: true` is present -* [ ] Standard image URL is used -* [ ] Content is clear and includes relevant links -* [ ] Breaking changes are clearly marked (use bold or H4 sections) -* [ ] Documentation links use relative paths (start with `/docs/`) -* [ ] Keywords added if applicable (deprecation, api, sdk, etc.) -* [ ] No trailing whitespace - -## Example usage - -### API Feature Example - -``` -User: "Create a developer release note for new Field Extraction Rules API endpoints, dated March 23, 2026" - -Claude: -1. Confirms date: March 23, 2026 -2. Generates slug: "field-extraction-rules-api" -3. Creates: blog-developer/2026-03-23-field-extraction-rules-api.md -4. Generates frontmatter: - - title: "March 23, 2026 - New Field Extraction Rules API" - - image: Standard Sumo Logic image - - hide_table_of_contents: true -5. Writes content with: - - Description of new endpoints - - Link to API documentation - - Impact notes -6. Provides checklist -``` - -### Deprecation Example - -``` -User: "Create a deprecation notice for Sumo Logic India Data Center, dated April 9, 2025" - -Claude: -1. Confirms date: April 9, 2025 -2. Generates slug: "india-datacenter-deprecation" -3. Creates: blog-developer/2025-04-09-india-datacenter-deprecation.md -4. Generates frontmatter: - - title: "April 9, 2025 - Deprecation of Sumo Logic India Data Center" - - keywords: deprecation, datacenter -5. Writes content with: - - What's being deprecated - - Timeline and dates - - Migration guidance - - Support contact -6. Provides checklist -``` - -## 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) - -**Examples:** -* ✅ March 23, 2026 -* ✅ January 1, 2026 -* ✅ December 31, 2025 -* ❌ March 23rd, 2026 (no ordinal) -* ❌ Mar 23, 2026 (abbreviated month) -* ❌ 2026-03-23 (wrong format) - -## Content formatting guidelines - -**Use formatting for clarity:** -* Use **bold** for important terms or breaking changes -* Use H4 sections (`####`) for subsections when needed -* Use bullet lists for multiple related items -* Use admonitions (`:::note`, `:::warning`) for important callouts - -**Example:** -```markdown -#### Breaking changes - -**Monitors API**: The `notificationGroupFields` parameter is now required when creating monitors. Update your integrations before June 1, 2026. - -:::warning -This is a breaking change. Existing integrations must be updated by June 1, 2026. -::: - -**Links:** -* Always use relative paths starting with `/docs/` -* Use descriptive link text (not "click here") -* Example: `[Metrics API documentation](/docs/api/metrics)` - -**Code blocks:** -* Use appropriate language tags (```python, ```bash, ```json) -* Keep examples concise and relevant -* Show before/after for migration guides - -## Safety principles - -* **Check for existing files** before creating to avoid duplicates -* **Use clear, descriptive slugs** that indicate content -* **Validate dates**. Ensure date is not in future -* **Include documentation links**. Help users find more info -* **Mark breaking changes clearly**. Use bold text or H4 sections -* **Use standard frontmatter**. Consistent image URL and structure -* **Keep content focused**. One topic per release note - -## Post-completion message - -After successfully creating the release note, tell the user: - -``` -✅ Developer release note created successfully! - -File created: -* 📄 blog-developer/{YYYY-MM-DD-slug}.md - -Summary: -* 📅 Title: {Month Day, YYYY} - {Topic} -* 📝 {Brief summary of content} -* 🏷️ Keywords: {keywords if added} - -Next steps: -1. Review content for accuracy and clarity -2. Verify documentation links are correct -3. Ensure breaking changes are clearly marked -4. Test locally: yarn start -5. Check preview at: http://localhost:3000/release-notes-developer -6. Submit PR: "DOCS-XXX - Developer release note: {Topic}" - -Checklist: -* [ ] Title format is correct (Month Day, YYYY - Topic) -* [ ] Date uses full month name, no ordinal -* [ ] Standard image URL is used -* [ ] hide_table_of_contents: true is present -* [ ] Documentation links use relative paths -* [ ] Breaking changes clearly marked -* [ ] Content is clear and concise - -The release note will appear on the Developer release notes page in reverse chronological order (newest first). - -Would you like me to help refine the content or add additional details? -``` - -## Error handling - -**If file already exists:** -* Show existing file path and creation date -* Ask if user wants to: - * Use different slug (e.g., add `-v2` or more specific topic) - * Use different date - * Overwrite (requires explicit confirmation) - -**If date is in the future:** -* Warn user and ask for confirmation -* Suggest using current date - -**If slug is too generic:** -* Warn if slug is too short or vague (e.g., "api", "update") -* Suggest more descriptive slug (e.g., "field-extraction-rules-api") - -**If documentation link looks invalid:** -* Warn if doesn't start with `/docs/` -* Suggest correction -* Proceed with user confirmation - -**If content is too long:** -* Suggest breaking into subsections (H4) -* Recommend creating separate doc page and linking to it from release note - -## Tips and best practices - -**For API changes:** -* Be specific about what endpoints changed -* Include examples of new request/response formats -* Provide migration timeline for breaking changes -* Link to comprehensive API documentation - -**For deprecations:** -* Give ample notice (3-6 months minimum) -* Clearly state end-of-life date -* Provide migration path with examples -* Offer support contact for questions - -**For SDK releases:** -* Include version number prominently -* Show installation/upgrade commands -* Highlight breaking changes separately -* Link to changelog or GitHub release - -**All release notes:** -* Write for developers (assume technical knowledge) -* Focus on impact and action items -* Use clear, direct language -* Provide links for more information -* Keep entries concise but complete - -## References - -* [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) diff --git a/.claude/commands/release-note-service.md b/.claude/commands/release-note-service.md deleted file mode 100644 index 4126e3a28b..0000000000 --- a/.claude/commands/release-note-service.md +++ /dev/null @@ -1,474 +0,0 @@ -# Create New Service Release Note - -Automates the creation of Service release notes for new features, updates, and improvements across Sumo Logic platform categories. - -## What this command does - -When you invoke `release-note-service`, Claude will guide you through: - -1. **Determine category**. Apps, Manage, Collection, Search, or UI -2. **Gather release details**. Feature name, description, and changes -3. **Create markdown file**. Generate file with proper frontmatter and structure -4. **Format content**. Apply correct formatting for the feature announcement -5. **Validate and preview**. Check structure and provide next steps - -## When to use this command - -* Announcing new platform features or capabilities -* Documenting updates to existing features -* Publishing UI improvements and enhancements -* Releasing new collection methods or integrations -* Announcing management and admin features -* Publishing app-related updates - -## Categories - -Service release notes are organized by platform area: - -* **Apps**. App-related features and updates -* **Collection**. Data collection features, sources, authentication -* **Manage**. Management and administration features -* **Search**. Search features, queries, analytics -* **UI**. User interface updates and improvements (often labeled "New UI") - -## Workflow - -### Step 1: Gather information - -Ask the user for: - -**Required:** -* **Category**: Which platform area (apps, collection, manage, search, ui) -* **Feature name**: Brief, descriptive name of the feature or update -* **Release date**: Date in YYYY-MM-DD format -* **Description**: What the feature does and why it matters (2-3 sentences) - -**Optional:** -* **Documentation link**: Relative path to the doc (e.g., `/docs/manage/...`) -* **"What's new" details**: Bulleted list of specific changes or capabilities -* **Keywords**: Custom keywords for frontmatter (suggest defaults based on content) - -**Validate:** -* Check that date is not in the future -* Ensure category is valid (apps, collection, manage, search, ui) -* Verify documentation link is valid relative path if provided -* Ask user to confirm keywords before creating file - -### Step 2: Create the markdown file - -**File naming convention:** -``` -blog-service/YYYY-MM-DD-{category}.md -``` - -Examples: -* `blog-service/2026-03-20-collection.md` -* `blog-service/2026-03-18-apps.md` -* `blog-service/2026-02-12-ui.md` - -**Important**: Files are created in `/blog-service/` directory - -**Note on file conflicts**: If a file already exists for the same date and category, ask the user: -* Use a different date -* Append to existing file (if related features) -* Use more specific category suffix (e.g., `-collection-m365` if needed) - -### Step 3: Generate frontmatter - -**Standard frontmatter:** -```yaml ---- -title: {Feature Description} ({Category}) -image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 -keywords: - - {keyword1} - - {keyword2} -hide_table_of_contents: true ---- -``` - -**Title formatting:** -* Feature description in Title Case -* Category in parentheses: (Apps), (Collection), (Manage), (Search), (New UI) -* NO date in title (unlike other release note types) -* Keep concise but descriptive -* Examples: - * "App Registration Authentication for Microsoft 365 Audit Source (Collection)" - * "Data Volume for MSSP (Apps)" - * "Content Item Actions Available Directly From Navigation Menus (New UI)" - -**Category labels in titles:** -* apps → (Apps) -* collection → (Collection) -* manage → (Manage) -* search → (Search) -* ui → (New UI) - -**Image:** -* Always use the standard Sumo Logic preview image -* URL: `https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082` - -**Keywords:** -* **Always ask user to confirm keywords before creating file** -* Suggest keywords based on content: - * Feature-specific terms (e.g., "Microsoft 365 Audit", "authentication") - * Category keywords (e.g., "apps", "ui", "collection") - * Product names or technologies mentioned -* Format: - ```yaml - keywords: - - keyword1 - - keyword2 - ``` -* User can customize the list - -### Step 4: Add optional import - -For release notes that use links or useBaseUrl: -```javascript -import useBaseUrl from '@docusaurus/useBaseUrl'; -``` - -**Note**: Only add if content uses it. For simple text-only releases, omit. - -### Step 5: Write content - -Content goes directly after frontmatter (and optional import). No H3 heading needed — the title is in frontmatter. - -**Basic structure:** -```markdown ---- -title: Feature Name (Category) -image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 -keywords: - - keyword1 - - keyword2 -hide_table_of_contents: true ---- - -{Description paragraph explaining the feature and its benefits} - -{Optional: What's new section with bulleted list} - -{Optional: Documentation links} -``` - -#### Simple Feature Announcement - -For straightforward feature updates: -```markdown ---- -title: App Registration Authentication for Microsoft 365 Audit Source (Collection) -image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 -keywords: - - Microsoft 365 Audit - - authentication -hide_table_of_contents: true ---- - -The Microsoft 365 Audit Source now supports the App Registration authentication method. This enhancement allows organizations to authenticate using Azure Active Directory App Registrations, providing a more secure and flexible authentication option for collecting Microsoft 365 audit logs. - -[Learn more](/docs/send-data/hosted-collectors/cloud-to-cloud-integration-framework/microsoft-365-audit-source/). -``` - -#### Feature with "What's new" Section - -For features with multiple specific changes: -```markdown ---- -title: Content Item Actions Available Directly From Navigation Menus (New UI) -image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 -keywords: - - ui -hide_table_of_contents: true ---- - -You can now perform common actions on content items directly from the navigation menus in the left-hand sidebar, making it faster and easier to manage your content without opening each item. - -**What's new:** -* Right-click on any content item in the sidebar to access a context menu -* Available actions: Open, Open in New Tab, Copy, Move, Delete, Share, Schedule Report -* Works for dashboards, searches, folders, and other content items -* Same functionality as the Actions menu in the Content Library - -This enhancement streamlines your workflow by providing quick access to frequently used actions. [Learn more](/docs/get-started/library/). -``` - -### Step 6: Content formatting guidelines - -**Write for clarity:** -* Start with a clear statement of what the feature is -* 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 - -**Use formatting for readability:** -* Use **bold** for section labels like "What's new:" -* Use bullet lists for multiple related items -* Use admonitions (`:::note`, `:::warning`) for important callouts if needed -* Keep paragraphs concise (2-4 sentences max) - -**Links:** -* Always use relative paths starting with `/docs/` -* Use descriptive link text (typically "Learn more") -* Example: `[Learn more](/docs/send-data/...)` - -**Examples by category:** - -**Apps:** -```markdown ---- -title: Data Volume for MSSP (Apps) -image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 -keywords: - - data-volume-for-mssp - - apps -hide_table_of_contents: true ---- - -The Data Volume for MSSP app is now available, providing managed security service providers with visibility into data usage across multiple customer accounts. This app helps MSSPs track, analyze, and optimize data ingestion to improve cost management and capacity planning. - -[Learn more](/docs/integrations/sumo-apps/data-volume-for-mssp). -``` - -**Collection:** -```markdown ---- -title: Enhanced Authentication Options for Cloud Sources (Collection) -image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 -keywords: - - authentication - - cloud-to-cloud - - collection -hide_table_of_contents: true ---- - -Cloud-to-Cloud sources now support additional authentication methods including OAuth 2.0 client credentials flow and service account authentication. These new options provide more flexibility for enterprise customers to integrate with cloud services using their preferred authentication standards. - -**What's new:** -* OAuth 2.0 client credentials flow for machine-to-machine authentication -* Service account support for Google Cloud and AWS integrations -* Enhanced security with token rotation and expiration handling -* Backward compatible with existing authentication methods - -[Learn more](/docs/send-data/hosted-collectors/cloud-to-cloud-integration-framework/). -``` - -**UI:** -```markdown ---- -title: Improved Dashboard Loading Performance (New UI) -image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 -keywords: - - ui - - dashboards - - performance -hide_table_of_contents: true ---- - -Dashboards now load up to 50% faster in the new UI through optimized query execution and progressive rendering. Large dashboards with many panels will see the most significant improvements, reducing wait times and improving the overall user experience. -``` - -### Step 7: Validation checklist - -Before finishing, verify: -* [ ] File created in `/blog-service/` directory -* [ ] Filename follows pattern: `YYYY-MM-DD-{category}.md` -* [ ] Frontmatter complete with all required fields -* [ ] Title includes feature description and category in parentheses -* [ ] Title does NOT include date -* [ ] `hide_table_of_contents: true` is present -* [ ] Standard image URL is used -* [ ] Keywords confirmed with user -* [ ] Category label uses correct format: (Apps), (Collection), (Manage), (Search), (New UI) -* [ ] Content is clear and focused on user benefits -* [ ] Documentation link uses relative path (starts with `/docs/`) -* [ ] No trailing whitespace - -## Example usage - -### Collection Feature Example - -``` -User: "Create a Service release note for Microsoft 365 Audit Source App Registration authentication, collection category, dated March 20, 2026" - -Claude: -1. Confirms category: Collection -2. Confirms date: 2026-03-20 -3. Asks for keywords (suggests: "Microsoft 365 Audit", "authentication") -4. Creates: blog-service/2026-03-20-collection.md -5. Generates frontmatter: - - title: "App Registration Authentication for Microsoft 365 Audit Source (Collection)" - - keywords: Microsoft 365 Audit, authentication -6. Writes content with: - - Description of new authentication method - - Business value - - Link to documentation -7. Provides checklist -``` - -### UI Feature Example - -``` -User: "Create a Service release note for new context menu actions in the sidebar, UI category, dated February 12, 2026" - -Claude: -1. Confirms category: UI -2. Confirms date: 2026-02-12 -3. Asks for keywords (suggests: "ui", "navigation") -4. Creates: blog-service/2026-02-12-ui.md -5. Generates frontmatter: - - title: "Content Item Actions Available Directly From Navigation Menus (New UI)" - - keywords: ui -6. Writes content with: - - Feature description - - "What's new" section with bullets - - Link to documentation -7. Provides checklist -``` - -## Category guidelines - -**Apps**. Use for: -* New apps or app updates -* App integrations -* App-specific features -* MSSP or multi-tenant features - -**Collection**. Use for: -* New sources or source types -* Collection authentication changes -* Collector features -* Data ingestion enhancements - -**Manage**. Use for: -* Account management features -* User and role management -* Security and compliance features -* Settings and configuration updates - -**Search**. Use for: -* Search language enhancements -* Query performance improvements -* Analytics features -* Data parsing updates - -**UI**. Use for: -* User interface changes -* Navigation improvements -* Visual design updates -* Workflow enhancements -* Label as "(New UI)" in title - -## Safety principles - -* **Check for existing files** before creating (same date + category = conflict) -* **Validate category** is one of: apps, collection, manage, search, ui -* **Use clear, descriptive titles** that explain the feature -* **Include documentation links**. Help users find more info -* **Use standard frontmatter**. Consistent image URL and structure -* **Keep content focused**. One feature per release note -* **Always ask user to confirm keywords** before creating file - -## Post-completion message - -After successfully creating the release note, tell the user: - -``` -✅ Service release note created successfully! - -File created: -* 📄 blog-service/{YYYY-MM-DD-category}.md - -Summary: -* 📋 Category: {Category} -* 📝 Title: {Feature Description} ({Category}) -* 🏷️ Keywords: {keywords} - -Next steps: -1. Review content for accuracy and clarity -2. Verify documentation link is correct -3. Ensure keywords are appropriate -4. Test locally: yarn start -5. Check preview at: http://localhost:3000/release-notes-service -6. Submit PR: "DOCS-XXX - Service release note: {Feature Description}" - -Checklist: -* [ ] Title format is correct (Feature Description (Category)) -* [ ] Title does NOT include date -* [ ] Category label uses correct format -* [ ] Standard image URL is used -* [ ] hide_table_of_contents: true is present -* [ ] Documentation link uses relative path -* [ ] Content is clear and concise -* [ ] Keywords confirmed with user - -The release note will appear on the Service release notes page in reverse chronological order (newest first). - -Would you like me to help refine the content or add additional details? -``` - -## Error handling - -**If file already exists:** -* Show existing file path and creation date -* Ask if user wants to: - * Use different date - * Append to existing file (if related features) - * Use more specific category suffix (e.g., `-collection-m365`) - * Overwrite (requires explicit confirmation) - -**If date is in the future:** -* Warn user and ask for confirmation -* Suggest using current date - -**If category is invalid:** -* Show error: "Category must be one of: apps, collection, manage, search, ui" -* Ask user to select valid category - -**If documentation link looks invalid:** -* Warn if doesn't start with `/docs/` -* Suggest correction -* Proceed with user confirmation - -**If title is too long:** -* Warn if title exceeds 100 characters -* Suggest shorter, more concise wording -* Category label must stay in title - -**If keywords not confirmed:** -* Do not create file until user confirms keywords -* Show suggested keywords and wait for approval/modification - -## Tips and best practices - -**For all Service releases:** -* 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 - -**Title guidelines:** -* Be specific about the feature (not "New Collection Feature") -* Use active language ("Enhanced...", "New...", "Improved...") -* Include category in parentheses at end -* No date in title (unlike other release types) -* Keep under 100 characters including category - -**Content structure:** -* First paragraph: What is it and why does it matter? -* Optional "What's new" section: Specific capabilities or changes -* Final element: "Learn more" link to docs - -**Keywords:** -* Include feature-specific terms -* Add category keyword (apps, ui, collection, etc.) -* Mention product names or technologies -* Keep list focused (2-5 keywords) - -## References - -* [Service Release Notes](https://sumologic.com/help/release-notes-service) -* [Release Notes Index](/docs/release-notes) -* [Style Guide](/docs/contributing/style-guide) diff --git a/.claude/commands/release-note.md b/.claude/commands/release-note.md new file mode 100644 index 0000000000..1d819cb272 --- /dev/null +++ b/.claude/commands/release-note.md @@ -0,0 +1,369 @@ +# Release Note + +Creates release notes for Sumo Logic products. Ask the user which type before proceeding. + +## Types + +| Type | Blog dir | File pattern | +|---|---|---| +| **Service** | `blog-service/` | `YYYY-MM-DD-{category}.md` | +| **Collector** | `blog-collector/` | `YYYY-MM-DD-{type}.md` | +| **Cloud SIEM** | `blog-cse/` | `YYYY-MM-DD-{type}.md` | +| **Cloud SOAR** | `blog-csoar/` | `YYYY-MM-DD-{subtype}.md` | +| **Developer** | `blog-developer/` | `YYYY-MM-DD-{slug}.md` | + +Ask the user which type, then follow the appropriate section below. + +**Shared frontmatter values (all types):** +- `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` + +If a file already exists for the same date and type, ask the user to use a different date, append to the existing file, or add a more specific suffix. + +--- + +## Service (`blog-service/`) + +**Subtypes**: apps, collection, manage, search, ui + +**Gather**: category, feature name, release date, description (2–3 sentences), doc link (optional), "What's new" bullets (optional), keywords (confirm with user before creating file). + +**File**: `blog-service/YYYY-MM-DD-{category}.md` + +**Frontmatter**: +```yaml +--- +title: {Feature Description} ({Category Label}) +image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 +keywords: + - {keyword1} +hide_table_of_contents: true +--- +``` + +**Title**: Feature description in Title Case + category label in parentheses. No date in title. +- apps → (Apps) | collection → (Collection) | manage → (Manage) | search → (Search) | ui → (New UI) + +**Content**: +```markdown +{Description — what the feature is and why it matters} + +**What's new:** +* {Specific capability} + +[Learn more](/docs/path/to/doc). +``` + +"What's new:" is optional — use for multiple specific changes, omit for single-point announcements. Only add `import useBaseUrl` if the content uses it. + +**Validation**: +- [ ] `blog-service/YYYY-MM-DD-{category}.md` +- [ ] Title: feature description + category label in parens, no date +- [ ] `hide_table_of_contents: true` +- [ ] Keywords confirmed with user +- [ ] Doc link uses `/docs/...` relative path + +--- + +## Collector (`blog-collector/`) + +**File**: `blog-collector/YYYY-MM-DD-{type}.md` (`-installed` or `-otel`) + +### Installed Collector + +**Gather**: version number (X.Y.Z-N), release date, list of security fixes / bug fixes / features. + +**Frontmatter**: +```yaml +--- +title: Installed Collector Version {X.Y.Z-N} +image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 +hide_table_of_contents: true +keywords: + - installed-collector +--- +``` + +**Content**: +```markdown +In this release, we've enhanced the security and stability of the Collector with added support for {security patches/bug fixes/features}. + +#### Security fix + +* Upgraded `{package}` to version **{version}** to address known security vulnerability ({CVE-YYYY-NNNNN}). + +#### Bug fix + +* {Bug fix description}. +``` + +- Sections use H4 (`####`). Order: Security fix → Bug fix → Feature. +- Package names in backticks, version numbers in **bold**. +- Include CVE/GHSA references (CVE-YYYY-NNNNN or GHSA-XXXX-XXXX-XXXX). +- Keywords are always `installed-collector` — no user confirmation needed. + +**Validation**: +- [ ] Title: "Installed Collector Version X.Y.Z-N" +- [ ] H4 sections in correct order (Security → Bug → Feature) +- [ ] Versions in **bold**, packages in backticks +- [ ] CVE/GHSA references where applicable + +### OpenTelemetry Collector + +**Gather**: feature name, release date, description (focus on user benefit), doc link. + +**Frontmatter**: +```yaml +--- +title: {Feature Name} +image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 +hide_table_of_contents: true +keywords: + - opentelemetry-collector +--- +``` + +**Content**: +```markdown +import useBaseUrl from '@docusaurus/useBaseUrl'; + +We're excited to announce {feature description}. {Benefits}. [Learn more](/docs/path/to/doc). +``` + +Start with "We're excited to announce..." or "We're excited to introduce...". Keywords are always `opentelemetry-collector` — no user confirmation needed. Use admonitions for important notes or breaking changes. + +**Validation**: +- [ ] Starts with "We're excited to..." +- [ ] "Learn more" link with relative path +- [ ] Keywords: `opentelemetry-collector` + +--- + +## Cloud SIEM (`blog-cse/`) + +**File**: `blog-cse/YYYY-MM-DD-{type}.md` (`-content` or `-application`) + +Always include `import useBaseUrl from '@docusaurus/useBaseUrl';` after frontmatter. + +### Content release + +**Gather**: release date, new/updated rules (IDs and names), log mappers, parsers, 3–5 high-level summary points, keywords (confirm with user; default: rules, log mappers, parsers). + +**Frontmatter**: +```yaml +--- +title: {Month} {Day ordinal}, {Year} - Content Release +hide_table_of_contents: true +keywords: + - rules + - log mappers + - parsers +image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 +--- +``` + +Title uses ordinal suffix (12th, 3rd, 21st). Full month name, not abbreviated. Examples: "March 19th, 2026 - Content Release", "February 3rd, 2026 - Content Release". + +**Content**: +```markdown +This content release includes: + - {Summary point 1} + - {Summary point 2} + +Additional changes are enumerated below. + +### Rules +* [New] MATCH-SXXXX Rule Name. +* [Updated] FIRST-SXXXX Rule Name. Brief description of what changed. + +### Log Mappers +* [New] Vendor - Event Type. + +### Parsers +* [Updated] /Parsers/System/Vendor/Parser Name. +``` + +- Summary bullets use 4-space indentation. +- `[New]` or `[Updated]` tag on every item. +- Rule ID formats: `MATCH-SXXXX`, `FIRST-SXXXX`, `THRESHOLD-SXXXX`, `AGGREGATION-SXXXX`, `CHAIN-SXXXX`, `OUTLIER-SXXXX` +- Parser paths use full hierarchy: `/Parsers/System/Vendor/Name` +- Log mapper format: `Vendor - Event Type` +- Sort alphabetically within each section. +- Do not invent rule IDs — ask the user if not provided. + +### Application release + +**Gather**: release date, features with descriptions and doc links, screenshots (if applicable), keywords (confirm with user). + +**Frontmatter**: +```yaml +--- +title: {Month} {Day}, {Year} - Application Update +image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 +keywords: + - {keyword} +hide_table_of_contents: true +--- +``` + +**Content**: +```markdown +### {Feature Name} + +{Description and business value}. [Learn more](/docs/path/to/docs). +``` + +H3 for each feature. Add screenshots with `description` for UI changes. + +**Validation (both CSE types)**: +- [ ] `blog-cse/YYYY-MM-DD-{type}.md` +- [ ] Title uses ordinal suffix for content releases +- [ ] `import useBaseUrl` included +- [ ] `hide_table_of_contents: true` +- [ ] Content: `[New]`/`[Updated]` tags on all items; parser paths complete +- [ ] Keywords confirmed with user + +--- + +## Cloud SOAR (`blog-csoar/`) + +**File**: `blog-csoar/YYYY-MM-DD-{subtype}.md` +- Content release: `YYYY-MM-DD-content-release.md` +- Application update: `YYYY-MM-DD-application-update.md` + +Always include `import useBaseUrl from '@docusaurus/useBaseUrl';` after frontmatter. + +**Date format in title**: "Month DD, YYYY" — full month name, zero-padded day, no ordinal. Examples: "March 06, 2026" ✅, "March 6, 2026" ❌, "March 6th, 2026" ❌. + +Application Updates are published early the following month for the previous month's changes. Filename and title use the publication date; the H2 header and intro use the release month. + +**Keywords** (confirm with user): +- Content release: `automation service`, `cloud soar`, `soar` +- Application update: `automation service`, `cloud soar` + +**Integration doc path**: `/docs/platform-services/automation-service/app-central/integrations/{slug}/` + +### Content release + +**Frontmatter**: +```yaml +--- +title: {Month DD, 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: + - automation service + - cloud soar + - soar +--- +``` + +**Content**: +```markdown +This release introduces {what's new}. + +### Integrations + +* [New] [Integration Name](/docs/platform-services/automation-service/app-central/integrations/{slug}/) +* [Updated] [Integration Name](/docs/platform-services/automation-service/app-central/integrations/{slug}/) + +### Playbooks + +* [New] {ID} - {Playbook Title} +``` + +Integration entries are link-only — no descriptions. Playbooks section is optional. + +### Application update + +**Frontmatter**: +```yaml +--- +title: {Month DD, 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: + - automation service + - cloud soar +--- +``` + +**Content**: +```markdown +## {Release month} release + +Following are the updates made in {Month} {YYYY}. + +### Changes and enhancements + +#### Integrations + +* [Added] [Integration Name](/docs/path/) - Description of what was added. +* [Updated] [Integration Name](/docs/path/) - Description of what was updated. + +#### Platform + +* Platform enhancement description. + +### Bug Fixes + +#### Integrations + +* In the [Integration Name](/docs/path/) integration, description of fix. + +#### Platform + +Fixed an issue where {description}. +``` + +Integration changes use `[Added]` for new integrations, `[Updated]` for existing. Always include descriptions (unlike content releases). + +**Validation (both SOAR types)**: +- [ ] `blog-csoar/`; filename uses full suffix (`-content-release.md` or `-application-update.md`) +- [ ] Title: "Month DD, YYYY" format (zero-padded, no ordinal) +- [ ] `import useBaseUrl` included +- [ ] `hide_table_of_contents: true` +- [ ] Keywords confirmed with user +- [ ] Application update: H2 header uses release month, not publication month + +--- + +## Developer (`blog-developer/`) + +**Gather**: title/topic, release date, content (what changed, why it matters, impact), doc links, keywords (optional; ask user). + +**File**: `blog-developer/YYYY-MM-DD-{slug}.md` + +Slug: lowercase, hyphens, 3–5 words. Examples: `api-endpoints`, `india-datacenter-deprecation`, `python-sdk-v2`. + +**Frontmatter**: +```yaml +--- +title: {Month Day, YYYY} - {Topic} +image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 +hide_table_of_contents: true +--- +``` + +**Title format**: "Month Day, YYYY - Topic" — full month, no ordinal. Examples: "April 9, 2025" ✅, "April 9th, 2025" ❌, "Apr 9, 2025" ❌. + +**Content**: +```markdown +{Main paragraph — what changed, why it matters} + +#### {Subsection if needed} + +* {Item} +``` + +- H4 (`####`) for subsections. +- `:::warning` admonitions for breaking changes. +- Doc links always use relative paths (`/docs/...`). +- Only add `import useBaseUrl` if content uses images. + +**Validation**: +- [ ] `blog-developer/YYYY-MM-DD-{slug}.md` +- [ ] Title: "Month Day, YYYY - Topic" (no ordinal) +- [ ] `hide_table_of_contents: true` +- [ ] Breaking changes clearly marked +- [ ] Doc links use relative paths diff --git a/.claude/commands/remove-doc.md b/.claude/commands/remove-doc.md index 6a2821a8fe..1755ba360f 100644 --- a/.claude/commands/remove-doc.md +++ b/.claude/commands/remove-doc.md @@ -2,24 +2,6 @@ Automates the complete workflow for removing or moving a Sumo Logic doc while preventing broken links and maintaining SEO health. -## What this command does - -When you invoke `/remove-doc`, Claude will guide you through: - -1. **Create 301 redirect**. Add redirect mapping to `cid-redirects.json`. -2. **Update internal links**. Find and replace all references to the old URL. -3. **Remove from hub pages**. Delete card from parent `index.md` and Product List. -4. **Delete the doc file**. Remove the actual markdown file. -5. **Remove from navigation**. Delete entry from `sidebars.ts`. -6. **Optional steps**. Add deprecation notes, hide from search engines. - -## When to use this command - -* Deprecating legacy docs in favor of new versions. -* Consolidating duplicate content. -* Removing outdated documentation. -* Moving docs to new locations. - ## Workflow ### Step 1: Gather information @@ -102,24 +84,6 @@ Before finishing, verify: * [ ] JSON files valid (no syntax errors). * [ ] Build test passes (optional: `yarn build`). -## Example usage - -``` -User: "Remove the nginx-legacy.md doc and redirect to nginx.md" - -Claude: -1. Confirms old path: docs/integrations/web-servers/nginx-legacy.md -2. Confirms new path: docs/integrations/web-servers/nginx.md -3. Adds redirect: "/docs/integrations/web-servers/nginx-legacy": "/docs/integrations/web-servers/nginx" -4. Searches for all references to nginx-legacy -5. Updates links in 3 files -6. Removes from web-servers index.md hub page -7. Deletes nginx-legacy.md -8. Removes from sidebars.ts -9. Asks about deprecation note -10. Provides verification checklist -``` - ## Safety principles * **Always create the redirect first** before deleting anything. @@ -169,30 +133,3 @@ Create: Multiple redirects, all pointing to unified-doc.md * Revert the change. * Fix and retry. -## Post-completion message - -After successfully removing a doc, tell the user: - -``` -✅ Doc removal complete! - -Summary: -* Added 301 redirect: /old-path → /new-path -* Updated X internal links across Y files -* Removed from hub page and sidebar -* Deleted old doc file - -Next steps: -1. Test locally: yarn start -2. Verify redirect works -3. Submit PR with description: "DOCS-XXX - Remove deprecated [doc name]" -4. Note: Google may take weeks to update search results - -Would you like me to run a build test or create a commit? -``` - -## References - -* [Contributing guide: Move or Remove a Doc](/docs/contributing/remove-doc). -* [CID redirects documentation](/docs/contributing/create-edit-doc#step-6-create-cid-url). -* [Sidebar configuration patterns](.claude/skills/docusaurus/). diff --git a/.claude/commands/rewrite-intro.md b/.claude/commands/rewrite-intro.md index f460af749c..e5b8f63425 100644 --- a/.claude/commands/rewrite-intro.md +++ b/.claude/commands/rewrite-intro.md @@ -2,26 +2,6 @@ Rewrites the intro/opening paragraph of a documentation page to match Sumo Logic voice and tone standards. -## What this command does - -When you invoke `/rewrite-intro`, Claude will: - -1. **Fetch the style guide**. Get latest voice and tone rules from live style guide -2. **Read the documentation file**. Analyze the current introduction -3. **Identify issues**. Find voice/tone violations, branding issues, clarity problems -4. **Rewrite the intro**. Create a new opening that matches Sumo Logic standards -5. **Present changes**. Show before/after with explanation of what changed -6. **Apply edits**. Update the file with user approval - -## When to use this command - -* Improving existing documentation intros that don't match Sumo Logic voice -* Converting formal or stiff language to conversational tone -* Fixing branding issues (missing app/source openers) -* Simplifying overly complex opening paragraphs -* Applying 8th-grade reading level to introductions -* Fixing passive voice in opening content - ## Workflow ### Step 1: Fetch Style Guide @@ -297,19 +277,3 @@ Metrics provide quantitative measurements of your infrastructure and application - Simplified: "This functionality" → direct statement - Added specific use cases (track, alert, visualize) -## Tips for Good Rewrites - -1. **Lead with value**. Start with what it is and what it does, not background -2. **Be specific**. "monitor login patterns" not "gain visibility" -3. **Show benefits**. Tell the reader why they should care -4. **Keep it short**. 2-3 sentences is usually enough for an intro -5. **Match document type**. Apps and sources have specific openers -6. **Test reading level**. Read it aloud; if it sounds stiff, simplify -7. **Focus on the user**. "You can..." not "This allows users to..." - -## After the Rewrite - -Once applied, suggest: -- Review the rest of the document for similar issues -- Consider using `/tone-check` on the full file -- Verify that the intro flows into the next section diff --git a/.claude/commands/seo-audit.md b/.claude/commands/seo-audit.md index c31de4d476..472e1e94fb 100644 --- a/.claude/commands/seo-audit.md +++ b/.claude/commands/seo-audit.md @@ -2,26 +2,6 @@ Audits documentation for search engine optimization (SEO), answer engine optimization (AEO), and generative engine optimization (GEO) signals. Produces a prioritized report and offers to apply fixes. -## What this command does - -When you invoke `/seo-audit`, Claude will: - -1. **Read the specified file or directory** -2. **Check SEO signals**. Title length, meta description, keywords, heading structure -3. **Check AEO signals**. Question-format headings, direct answers, featured snippet readiness -4. **Check GEO signals**. Authoritative statements, structured facts, LLM citation patterns -5. **Check internal linking**. Presence of links, descriptive anchor text -6. **Generate a prioritized report**. Issues ranked by impact -7. **Offer to fix issues**. Apply improvements with user approval - -## When to use this command - -* Before submitting a PR for new or updated content -* Auditing a section or category for discoverability gaps -* Preparing docs for a product launch or announcement -* Quarterly content health checks -* After rewriting or restructuring a doc - ## Signal definitions **SEO** (Search Engine Optimization): signals that help traditional search engines rank and surface pages. diff --git a/.claude/commands/simplify.md b/.claude/commands/simplify.md index abdefb2024..7f978b80d1 100644 --- a/.claude/commands/simplify.md +++ b/.claude/commands/simplify.md @@ -2,26 +2,6 @@ Simplifies overly complex, verbose, or hard-to-understand documentation content to meet 8th-grade reading level standards. -## What this command does - -When you invoke `/simplify`, Claude will: - -1. **Read target content**. Get the file, section, or text to simplify -2. **Analyze complexity**. Identify reading level, passive voice, long sentences, jargon -3. **Rewrite content**. Simplify while maintaining technical accuracy -4. **Present comparison**. Show before/after with complexity analysis -5. **Apply changes**. Update with user approval - -## When to use this command - -* Content is too technical or wordy -* Reading level above 8th grade -* Long, complex sentences (20+ words) -* Excessive passive voice -* Unnecessary jargon or filler words -* User feedback that docs are "hard to understand" -* Preparing content for broader audience - ## Workflow ### Step 1: Get Target Content @@ -376,20 +356,3 @@ May already be optimal: - Remove filler only - Don't over-engineer -## Tips for Good Simplification - -1. **Read aloud**. If it sounds stiff or confusing, simplify more -2. **One idea per sentence**. Don't combine unrelated concepts -3. **Front-load information**. Put the main point first -4. **Use familiar words**. Choose words most people know -5. **Provide examples**. Concrete examples clarify abstract concepts -6. **Test with fresh eyes**. Would a new user understand this? -7. **Maintain voice**. Keep Sumo Logic conversational tone - -## After Simplification - -Suggest: -- Review the rest of the document for similar issues -- Use `/tone-check` to validate voice and tone -- Consider if other sections need simplification -- Test with someone unfamiliar with the topic diff --git a/.claude/commands/tone-check.md b/.claude/commands/tone-check.md index 3a5c217c08..97715675ea 100644 --- a/.claude/commands/tone-check.md +++ b/.claude/commands/tone-check.md @@ -2,26 +2,6 @@ Validates documentation against Sumo Logic voice and tone rules, identifying violations and suggesting fixes. -## What this command does - -When you invoke `/tone-check`, Claude will: - -1. **Fetch style guide**. Get latest voice and tone rules -2. **Read documentation**. Analyze the specified file -3. **Identify violations**. Find voice/tone issues with line numbers -4. **Generate report**. Categorize by severity (Critical, Warning, Suggestion) -5. **Offer fixes**. Show specific corrections -6. **Apply changes**. Update with user approval - -## When to use this command - -* Before submitting a pull request -* After writing new documentation -* Validating existing docs for compliance -* Checking docs flagged in reviews -* Ensuring voice/tone consistency -* Training on Sumo Logic style - ## Workflow ### Step 1: Fetch Style Guide @@ -478,14 +458,6 @@ Some documents may have valid exceptions: Flag these as suggestions, not critical issues. -## After the Tone Check - -Suggest next steps: -- If many issues: Use `/rewrite-intro` or `/simplify` on problematic sections -- If clean: Ready for PR -- If medium issues: Fix and re-run tone check -- Consider running `/audit-doc` for full quality check - ## Common Patterns ### Serial Offenders @@ -512,12 +484,3 @@ For 1-2 violations, just fix them: "Found one negative contraction on line 45. Should I fix it?" ``` -## Tips for Running Tone Checks - -1. **Run early and often**. Catch issues before they multiply -2. **Check before PRs**. Don't let violations reach review -3. **Use with /simplify**. Tone check after simplifying content -4. **Train your eye**. Learn common patterns to avoid them -5. **Focus on critical first**. Don't get bogged down in suggestions -6. **Batch similar fixes**. Fix all passive voice at once -7. **Re-run after fixes**. Verify all issues resolved diff --git a/CLAUDE.md b/CLAUDE.md index dd253e69b4..ea66bcbc40 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -81,9 +81,59 @@ Primary commands for documentation work. Proactively suggest when context fits - Doc needs discoverability improvements → suggest `/geo-optimize` - User asks about doc quality → suggest `/audit-doc` and `/seo-audit` together -**Key distinctions:** -- `/jira` = manage tickets | `/doc-from-jira` = scaffold doc from ticket -- `/audit-doc` = structure/style/links | `/seo-audit` = discoverability signals (run both before PRs) +### Slash commands + +**Creating docs** + +| Command | What it does | +|---------|-------------| +| `/doc` | Create a new feature, how-to, concept, reference, or troubleshooting doc | +| `/doc-from-jira` | Fetch a DOCS Jira ticket and scaffold a complete doc from it | +| `/app-doc` | Create a new app integration doc | +| `/c2c-source-doc` | Create a new Cloud-to-Cloud source integration doc | + +**Release notes** + +| Command | What it does | +|---------|-------------| +| `/release-note` | New release note (service, collector, Cloud SIEM, Cloud SOAR, or developer) | + +**Editing and reviewing** + +| Command | What it does | +|---------|-------------| +| `/audit-doc` | Full quality audit: structure, style, links, frontmatter, completeness | +| `/seo-audit` | Discoverability audit: SEO, AEO, and GEO signals — run this before a PR | +| `/geo-optimize` | Rewrite a doc to improve AI citation and generative engine visibility | +| `/tone-check` | Check voice and tone against Sumo Logic style rules | +| `/rewrite-intro` | Rewrite a doc's opening paragraph | +| `/simplify` | Simplify overly complex content | +| `/review` | Review a pull request | + +**Jira** + +| Command | What it does | +|---------|-------------| +| `/jira` | Create, update, search, or transition DOCS Jira tickets | +| `/doc-from-jira` | Start a new doc from a Jira ticket (use this instead of `/jira` when the goal is to write a doc) | + +**Removing docs** + +| Command | What it does | +|---------|-------------| +| `/remove-doc` | Safely deprecate or move a doc with redirects | + +### Which audit command to use + +Run both for a thorough pre-PR check — they cover different things: + +- **`/audit-doc`** — structure, required sections, broken links, frontmatter completeness, style guide +- **`/seo-audit`** — SEO/AEO/GEO signals: title length, description quality, question headings, direct answers, GEO patterns + +### `/jira` vs `/doc-from-jira` + +- Use **`/jira`** to manage tickets: create, search, update fields, change status, view your queue +- Use **`/doc-from-jira`** when you have a ticket and want to start writing the doc it describes — it fetches the ticket and scaffolds the file ## Commands From ecad9b1907e4b10cd4af702dbbc5b1ebe6e29c2e Mon Sep 17 00:00:00 2001 From: Kim Pohas Date: Wed, 20 May 2026 02:29:15 -0700 Subject: [PATCH 11/22] DOCS-1640: Add review.md command for PR-level doc quality checks MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Applies audit-doc checks to all changed .md files in a PR and produces a consolidated review comment. Read-only — surfaces issues without fixing. Also fixes sentence case rule in audit-doc.md (was incorrectly Title Case). Co-Authored-By: Claude Sonnet 4.6 --- .claude/commands/audit-doc.md | 2 +- .claude/commands/review.md | 115 ++++++++++++++++++++++++++++++++++ CLAUDE.md | 2 +- 3 files changed, 117 insertions(+), 2 deletions(-) create mode 100644 .claude/commands/review.md diff --git a/.claude/commands/audit-doc.md b/.claude/commands/audit-doc.md index 94848f5cba..0400b1dee3 100644 --- a/.claude/commands/audit-doc.md +++ b/.claude/commands/audit-doc.md @@ -46,7 +46,7 @@ Check for required fields and proper formatting: * [ ] Only one H1 heading (the title in frontmatter) * [ ] H2 sections used for main sections * [ ] No skipped heading levels (H2 → H4 without H3) -* [ ] Headings use Title Case +* [ ] Headings use sentence case (only first word and proper nouns capitalized) **Required sections (by doc type):** diff --git a/.claude/commands/review.md b/.claude/commands/review.md new file mode 100644 index 0000000000..4dff1db6f4 --- /dev/null +++ b/.claude/commands/review.md @@ -0,0 +1,115 @@ +# Review Pull Request — Documentation Quality Review + +Reviews all changed `.md` files in a pull request using the same checks as `/audit-doc`, then produces a single consolidated PR review comment. + +## Workflow + +### Step 1: Get the PR + +If a PR number or URL is provided, use it. Otherwise run `gh pr list` and ask the user which PR to review. + +Extract the PR number from URLs (e.g., `https://github.com/.../pull/6707` → `6707`). + +### Step 2: Fetch PR details and diff + +Run in parallel: +- `gh pr view --json title,body,author,headRefName,baseRefName,changedFiles` +- `gh pr diff ` + +### Step 3: Identify changed doc files + +From the diff, collect all files with a `.md` extension that were added or modified (ignore deletions). Skip non-doc files (`.ts`, `.json`, `.js`, `.yml`, etc.). + +If no `.md` files changed, report: "No documentation files changed in this PR." + +### Step 4: Determine doc type for each file + +Use the file path to infer the doc type: + +| Path pattern | Doc type | +|---|---| +| `blog-service/`, `blog-collector/`, `blog-cse/`, `blog-csoar/`, `blog-developer/` | Release note | +| `docs/integrations/` or `docs/platform-services/automation-service/app-central/` | App doc | +| `docs/send-data/hosted-collectors/cloud-to-cloud-integration-framework/` | C2C source doc | +| Everything else under `docs/` | Feature / how-to / concept / reference | + +If the type is ambiguous, read the file's frontmatter `tags` field or intro paragraph to confirm. + +### Step 5: Read each changed file + +Use the Read tool to fetch the full current content of each changed `.md` file (not just the diff lines — the full file is needed to check structure, frontmatter, and links in context). + +### Step 6: Apply audit-doc checks to each file + +Apply all checks from `/audit-doc` — frontmatter, structure, links, images, style guide, doc-type-specific requirements — using the same severity levels: + +- **Critical**: must fix before merging +- **Warning**: should fix +- **Suggestion**: nice to have + +See `/audit-doc` for the full checklist. Key things to flag in a PR review: + +- Missing or invalid frontmatter fields (`id`, `title`, `description`) +- Branding violations ("Sumo" instead of "Sumo Logic", wrong app/source opener) +- Wrong heading case (sentence case required — only first word and proper nouns capitalized) +- Missing required sections for the doc type +- Negative contractions (can't, won't, don't → cannot, will not, do not) +- "the user" or "users" instead of "you" +- Bare URLs, missing alt text, missing code block language tags +- Release note format violations (date format, `[New]`/`[Updated]` tags, rule ID patterns) + +Focus on issues introduced by this PR. If the file has pre-existing issues that weren't touched by the diff, note them briefly but do not block the PR over them. + +### Step 7: Produce the review + +Output a single consolidated review covering all changed files. Format: + +``` +## PR review: {PR title} + +{N} doc file(s) changed: {list of filenames} + +--- + +### {filename} +**Type**: {doc type} + +**Critical issues** (must fix): +- {issue with line reference if possible} + +**Warnings** (should fix): +- {issue} + +**Suggestions**: +- {issue} + +✅ No issues / ⚠️ {N} warnings / ❌ {N} critical + +--- + +### {next filename} +... + +--- + +## Overall + +{Pass | Pass with warnings | Needs work} + +{1-2 sentence summary of the most important things to address} +``` + +If a file has no issues: `✅ {filename} — looks good.` + +### Step 8: Offer next steps + +After the review, offer: +- "Run `/audit-doc {file}` to get a detailed report with line numbers and fix options" +- "Run `/seo-audit {file}` to check discoverability signals" + +## Constraints + +- **Read-only**. Do not edit any files. The purpose is to surface issues, not fix them. +- **Diff-aware**. Prioritize issues in lines added or modified by the PR. Flag pre-existing issues separately as "pre-existing" if needed. +- **Concise**. This is a PR review, not a full audit report. One line per issue where possible. +- **No duplication**. The checks live in `/audit-doc`. Do not re-list every rule here — apply them, don't describe them. diff --git a/CLAUDE.md b/CLAUDE.md index ea66bcbc40..14f0a3a1cd 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -108,7 +108,7 @@ Primary commands for documentation work. Proactively suggest when context fits | `/tone-check` | Check voice and tone against Sumo Logic style rules | | `/rewrite-intro` | Rewrite a doc's opening paragraph | | `/simplify` | Simplify overly complex content | -| `/review` | Review a pull request | +| `/review` | Review a pull request — applies audit-doc checks to all changed `.md` files | **Jira** From 91d7a7790603a1d1aefcc639b580e77e25b17ae3 Mon Sep 17 00:00:00 2001 From: Kim Pohas Date: Wed, 20 May 2026 02:31:06 -0700 Subject: [PATCH 12/22] DOCS-1640: Delete tone-check, simplify, rewrite-intro commands Rules are covered by the sumo-style skill. Standalone commands were unlikely to be invoked and added clutter to the command list. Co-Authored-By: Claude Sonnet 4.6 --- .claude/commands/audit-doc.md | 1 - .claude/commands/rewrite-intro.md | 279 ----------------- .claude/commands/simplify.md | 358 ---------------------- .claude/commands/tone-check.md | 486 ------------------------------ CLAUDE.md | 3 - 5 files changed, 1127 deletions(-) delete mode 100644 .claude/commands/rewrite-intro.md delete mode 100644 .claude/commands/simplify.md delete mode 100644 .claude/commands/tone-check.md diff --git a/.claude/commands/audit-doc.md b/.claude/commands/audit-doc.md index 0400b1dee3..46312d92e4 100644 --- a/.claude/commands/audit-doc.md +++ b/.claude/commands/audit-doc.md @@ -359,4 +359,3 @@ check SEO/AEO/GEO signals. For discoverability, run both: * **`/seo-audit`** — checks title length, description quality, question headings, GEO patterns * **`/geo-optimize`** — rewrites content to improve AI citation and search visibility -* **`/tone-check`** — checks voice and tone against Sumo Logic style rules (standalone voice check) diff --git a/.claude/commands/rewrite-intro.md b/.claude/commands/rewrite-intro.md deleted file mode 100644 index e5b8f63425..0000000000 --- a/.claude/commands/rewrite-intro.md +++ /dev/null @@ -1,279 +0,0 @@ -# Rewrite Intro — Documentation Opening Paragraph Rewrite - -Rewrites the intro/opening paragraph of a documentation page to match Sumo Logic voice and tone standards. - -## Workflow - -### Step 1: Fetch Style Guide - -Before rewriting, always fetch the live style guide: -- https://www.sumologic.com/help/docs/contributing/style-guide/ -- https://www.sumologic.com/help/docs/contributing/word-list/ - -These contain the authoritative voice and tone rules. - -### Step 2: Get the File - -Ask the user which file to rewrite if not specified. Accept: -- **Full path**: `/Users/kpohas/sumologic-documentation/docs/integrations/amazon-aws/cloudtrail.md` -- **Relative path**: `docs/integrations/amazon-aws/cloudtrail.md` -- **Filename only**: `cloudtrail.md` (search for it) - -### Step 3: Analyze Current Intro - -Read the file and identify: - -1. **The introduction section** - - Usually first 1-3 paragraphs after frontmatter - - Before the first H2 heading - - May include multiple paragraphs - -2. **Document type** - - App doc (requires app opener) - - C2C source doc (requires source opener) - - Feature documentation - - Tutorial or guide - - Release note - -3. **Current issues** - - Voice and tone violations - - Branding compliance - - Reading level - - Clarity and conciseness - -### Step 4: Apply Rewrite Rules - -#### Branding Requirements - -**App docs MUST open with:** -```markdown -The Sumo Logic app for [Vendor] [what it does and why you'd use it]. -``` - -Examples: -- "The Sumo Logic app for AWS CloudTrail provides comprehensive visibility into AWS API activity and security events." -- "The Sumo Logic app for Salesforce helps you monitor user activity, track performance, and analyze security events." - -**C2C source docs MUST open with:** -```markdown -The Sumo Logic source for [Vendor] [what it does]. -``` - -Examples: -- "The Sumo Logic source for Okta collects authentication logs, system logs, and user activity events." -- "The Sumo Logic source for GitHub ingests repository events, pull request activity, and security alerts." - -#### Voice and Tone Principles - -**Address reader as "you":** -- ❌ "Users can configure the source" -- ✅ "You can configure the source" -- ❌ "One should consider performance" -- ✅ "You should consider performance" - -**Active voice:** -- ❌ "Data is collected by the Collector" -- ✅ "The Collector collects data" -- ❌ "Logs are parsed and indexed" -- ✅ "Sumo Logic parses and indexes logs" - -**Conversational but professional:** -- ❌ "This document delineates the methodology for configuration" -- ✅ "This guide explains how to configure the source" -- ❌ "Utilize the subsequent instructions" -- ✅ "Follow these steps" - -**8th-grade reading level:** -- Short sentences (under 20 words) -- Common words over technical jargon -- Simple sentence structure -- One idea per sentence - -**No "please" in directives:** -- ❌ "Please configure the source" -- ✅ "Configure the source" -- ❌ "Please refer to the documentation" -- ✅ "Learn more in the documentation" - -**Use "need to" not "must":** -- ❌ "You must configure authentication" -- ✅ "You need to configure authentication" - -**No filler adjectives:** -- ❌ "very important", "simply click", "just add", "easy to use", "straightforward process" -- ✅ Remove or rewrite without filler - -**Spell out negative contractions:** -- ❌ "can't", "won't", "don't", "isn't" -- ✅ "cannot", "will not", "do not", "is not" - -#### Introduction Structure - -Good intros typically follow this pattern: - -1. **What this is** (1-2 sentences) - - For apps: Branded opener + what it monitors - - For sources: Branded opener + what data it collects - - For features: What the feature does - -2. **Why you'd use it** (1-2 sentences) - - Key benefits - - Main use cases - - Problems it solves - -3. **What you'll learn** (1 sentence, optional for tutorials/guides) - - "This guide shows you how to..." - - "You'll learn to..." - -**Example - App doc intro:** -```markdown -The Sumo Logic app for AWS CloudTrail provides visibility into AWS account activity and API usage. The app includes dashboards that help you monitor user activity, detect security threats, and maintain compliance. This guide shows you how to install the app and configure data collection. -``` - -**Example - Source doc intro:** -```markdown -The Sumo Logic source for Okta collects authentication logs, system logs, and user activity events from your Okta organization. You can use this data to monitor login patterns, detect suspicious activity, and audit user permissions. This guide explains how to configure the source and verify data collection. -``` - -### Step 5: Present Rewrite - -Show the user: - -```markdown -## Current intro -[Show original text with line numbers] - -## Rewritten intro -[Show new text] - -## Changes made -- Fixed passive voice in sentence 2: "data is collected" → "the source collects data" -- Added proper app opener branding: "The Sumo Logic app for [Vendor]..." -- Removed filler words: "simply", "just", "easy" (3 instances) -- Spelled out "can't" → "cannot" -- Broke 42-word sentence into two shorter sentences -- Changed "users can" → "you can" (addressing reader directly) -- Simplified "utilize" → "use", "in order to" → "to" -- Reduced reading level from 11th grade to 8th grade -``` - -Be specific about what changed and why. - -### Step 6: Apply Changes - -After user approval: - -1. **Use Edit tool** to replace the intro section -2. **Preserve all other content**. only replace the intro paragraphs -3. **Maintain formatting**. keep existing markdown structure, images, code blocks -4. **Confirm success**. Let user know the changes were applied - -## Safety Guidelines - -- **NEVER modify files automatically**. always show the rewrite and get user approval first -- **Preserve existing content**. only replace the intro section, don't touch anything else -- **Maintain formatting**. keep existing markdown structure, line breaks, spacing -- **Don't change frontmatter**. unless specifically asked -- **Verify document type**. apply correct branding rules (app vs. source vs. feature) - -## Edge Cases - -### No intro exists -If the doc has no introduction: -- Offer to write one from scratch -- Use document type to determine opener format -- Ask user for key information (what it does, why use it) - -### Intro is already good -If intro already meets standards: -- Tell the user it's in good shape -- Suggest only minor tweaks if any -- Don't rewrite just for the sake of rewriting - -### Multiple intro paragraphs -If there are 3+ intro paragraphs: -- Ask user which paragraphs to include in rewrite scope -- Consider if all are needed (may be too long) -- Suggest condensing if appropriate - -### Different doc types -Apply appropriate rules: -- **App docs**: Must have app opener -- **Source docs**: Must have source opener -- **Feature docs**: No special opener, focus on clarity -- **Tutorials**: Include "what you'll learn" -- **Release notes**: Different format, may not need rewrite - -### Technical content -If intro contains necessary technical terms: -- Keep technical terms that are unavoidable -- Define acronyms on first use -- Simplify surrounding prose -- Don't sacrifice accuracy for simplicity - -## Examples - -### Example 1: App Doc - -**User:** `/rewrite-intro docs/integrations/amazon-aws/cloudtrail.md` - -**Original:** -``` -CloudTrail is utilized by organizations to monitor AWS API activity. The application can be used by users to gain visibility into account activity. Data is collected and visualized through various dashboards which are very helpful for security teams. -``` - -**Rewritten:** -``` -The Sumo Logic app for AWS CloudTrail provides visibility into AWS account activity and API usage. You can monitor user actions, detect security threats, and maintain compliance with pre-built dashboards and alerts. -``` - -**Changes:** -- Added proper app opener: "The Sumo Logic app for AWS CloudTrail" -- Changed passive voice: "Data is collected" → "You can monitor" -- Addressed reader as "you" instead of "users" -- Removed filler: "very helpful" -- Simplified: "utilized" → "provides", "gain visibility" → "monitor" -- Combined ideas into two focused sentences - -### Example 2: Source Doc - -**User:** `/rewrite-intro docs/send-data/hosted-collectors/cloud-to-cloud-integration-framework/okta-source.md` - -**Original:** -``` -This source integration is designed to collect logs from Okta. Users must configure the source properly. The logs that are collected can include authentication events and system logs. -``` - -**Rewritten:** -``` -The Sumo Logic source for Okta collects authentication logs, system logs, and user activity events from your Okta organization. You can use this data to monitor login patterns, detect suspicious activity, and audit user permissions. -``` - -**Changes:** -- Added proper source opener: "The Sumo Logic source for Okta" -- Removed passive voice: "logs that are collected" → "collects authentication logs" -- Changed "Users must" → "You can" -- Added value proposition (what you can do with the data) -- More specific about log types - -### Example 3: Feature Doc - -**User:** `/rewrite-intro docs/metrics/introduction.md` - -**Original:** -``` -Metrics are utilized within Sumo Logic to provide quantitative measurements of your infrastructure and applications. This functionality is very powerful and can be used by organizations to monitor performance. The system enables users to create visualizations. -``` - -**Rewritten:** -``` -Metrics provide quantitative measurements of your infrastructure and applications. You can track performance trends, set up alerts, and create visualizations to monitor system health in real time. -``` - -**Changes:** -- Removed passive voice: "are utilized" → "provide" -- Changed "users" → "You" -- Removed filler: "very powerful" -- Simplified: "This functionality" → direct statement -- Added specific use cases (track, alert, visualize) - diff --git a/.claude/commands/simplify.md b/.claude/commands/simplify.md deleted file mode 100644 index 7f978b80d1..0000000000 --- a/.claude/commands/simplify.md +++ /dev/null @@ -1,358 +0,0 @@ -# Simplify — Documentation Content Simplification - -Simplifies overly complex, verbose, or hard-to-understand documentation content to meet 8th-grade reading level standards. - -## Workflow - -### Step 1: Get Target Content - -Ask the user to specify what to simplify: - -**Option 1: Full file** -``` -/simplify docs/send-data/collect-from-other-sources/azure-monitoring.md -``` -Simplifies the entire document. - -**Option 2: Specific section** -``` -/simplify the Prerequisites section in docs/integrations/saas-cloud/salesforce.md -``` -Simplifies just that section. - -**Option 3: Line range** -``` -/simplify lines 45-78 in docs/metrics/introduction.md -``` -Simplifies specific lines. - -**Option 4: User provides text** -User pastes text directly for simplification. - -### Step 2: Analyze Complexity - -Check for these complexity indicators: - -#### Reading Level -- **Above 8th grade?** Needs simplification -- Use short words, simple sentences -- One idea per sentence - -**Tools to assess:** -- Long words (3+ syllables) -- Sentence length (words per sentence) -- Complex sentence structures - -#### Passive Voice -Passive voice makes content harder to read. - -❌ **Passive examples:** -- "Data is ingested by Sumo Logic" -- "The dashboard can be configured by users" -- "Logs are parsed and indexed" -- "Alerts are triggered when thresholds are exceeded" - -✅ **Active alternatives:** -- "Sumo Logic ingests data" -- "You can configure the dashboard" -- "Sumo Logic parses and indexes logs" -- "Sumo Logic triggers alerts when thresholds are exceeded" - -#### Long Sentences -Sentences over 20 words are hard to follow. - -❌ **Too long (42 words):** -"In order to configure the source properly, you need to navigate to the Cloud-to-Cloud Integration page in Sumo Logic, select the appropriate integration type from the dropdown menu, and then enter your authentication credentials in the fields provided." - -✅ **Broken up:** -"To configure the source, go to the Cloud-to-Cloud Integration page in Sumo Logic. Select your integration type from the dropdown menu. Enter your authentication credentials in the fields." - -#### Jargon and Technical Terms -Undefined jargon confuses readers. - -❌ **Undefined jargon:** -- "Instantiate a new collector" -- "Leverage the API endpoint" -- "Utilize the following methodology" - -✅ **Plain language:** -- "Create a new collector" -- "Use the API endpoint" -- "Follow these steps" - -**When technical terms are necessary:** -- Define acronyms on first use: "Application Load Balancer (ALB)" -- Provide context: "The collector (a lightweight agent that sends data)" -- Link to glossary if available - -#### Filler Words -Remove these unnecessary words: - -| Filler | Example | Better | -|--------|---------|--------| -| simply | simply click the button | click the button | -| just | just add the field | add the field | -| very | very important | important | -| easy | easy to configure | configure | -| straightforward | straightforward process | (remove or rewrite) | -| actually | actually sends data | sends data | -| basically | basically allows you | allows you | - -#### Nested Clauses -Multiple commas and dependent clauses make sentences hard to parse. - -❌ **Nested (hard to read):** -"The collector, which runs on your infrastructure, collects logs from various sources, including applications, servers, and network devices, and then sends them to Sumo Logic, where they are parsed and indexed." - -✅ **Simplified:** -"The collector runs on your infrastructure and collects logs from applications, servers, and network devices. It sends the logs to Sumo Logic for parsing and indexing." - -#### Redundancy -Common redundant phrases: - -| Replace | With | -|---------|------| -| in order to | to | -| due to the fact that | because | -| at this point in time | now | -| in the event that | if | -| prior to | before | -| subsequent to | after | -| a number of | several, many | -| is able to | can | -| in close proximity to | near | -| for the purpose of | to, for | -| has the ability to | can | -| at the present time | now | - -### Step 3: Apply Simplification Rules - -#### Sentence Structure Rules - -1. **Keep sentences under 20 words** - - Average 15-17 words per sentence - - Vary sentence length for readability - - One main idea per sentence - -2. **Use active voice** - - Subject performs the action - - More direct and clear - - Easier to understand - -3. **Start with the action or subject** - - Don't bury the main point - - Front-load important information - - Avoid long introductory clauses - -4. **Break up complex sentences** - - Multiple ideas → multiple sentences - - Dependent clauses → independent sentences - - Use periods instead of commas - -#### Word Choice Rules - -1. **Use common words** - - "use" not "utilize" - - "start" not "initiate" - - "end" not "terminate" - - "get" not "obtain" - -2. **Replace jargon** - - Technical terms → plain language when possible - - Define acronyms on first use - - Provide context for unfamiliar concepts - -3. **Remove filler adjectives** - - Delete: very, simply, just, easy, straightforward - - Only keep if adds meaning - -4. **Spell out contractions** - - Negative contractions: can't → cannot - - Keep common positive: you'll, they're, we're - -#### Paragraph Structure Rules - -1. **Keep paragraphs short** - - 3-5 sentences maximum - - One main point per paragraph - - Use white space for readability - -2. **Lead with the main point** - - Topic sentence first - - Supporting details after - - Don't bury the lead - -3. **Use bullets for lists** - - 3+ similar items → bullet list - - Easier to scan - - Better comprehension - -### Step 4: Simplification Examples - -#### Example 1: Passive Voice + Jargon - -**Original (Grade 12):** -``` -The data is ingested by the collector which then utilizes various parsing methodologies to transform the logs into a structured format that can be leveraged by the analytics engine. -``` - -**Simplified (Grade 8):** -``` -The collector ingests data and parses logs into a structured format. You can then use this data in the analytics engine. -``` - -**Changes:** -- Passive → active: "data is ingested" → "collector ingests" -- Removed jargon: "utilizes" → "parses", "leveraged" → "use" -- Split 31-word sentence into two shorter sentences (10 and 11 words) -- Added "you" to engage reader - -#### Example 2: Long Sentence + Nested Clauses - -**Original (Grade 13):** -``` -In order to configure the AWS CloudTrail source, which collects API activity logs from your AWS account, you need to first navigate to the Sumo Logic console, then select the Manage Data option from the left navigation menu, and finally click on Collection in order to access the configuration page where you can add a new source. -``` - -**Simplified (Grade 7):** -``` -To configure the AWS CloudTrail source, go to the Sumo Logic console. Select **Manage Data** from the left menu, then click **Collection**. This opens the configuration page where you can add the source. The source collects API activity logs from your AWS account. -``` - -**Changes:** -- Removed "in order to" → "To" (2 instances) -- Split 52-word sentence into 4 shorter sentences (9, 10, 11, 10 words) -- Removed nested clause, moved to separate sentence -- Added bold formatting for UI elements -- More direct instructions - -#### Example 3: Technical Jargon - -**Original (Grade 14):** -``` -The application leverages a sophisticated algorithm to instantiate correlations between disparate data points, thereby enabling users to ascertain patterns that would otherwise remain obfuscated within the raw log data. -``` - -**Simplified (Grade 8):** -``` -The app finds connections between different data points. This helps you spot patterns that are hard to see in raw logs. -``` - -**Changes:** -- "leverages" → "uses" (then simplified to implicit) -- "instantiate correlations" → "finds connections" -- "disparate" → "different" -- "ascertain patterns" → "spot patterns" -- "remain obfuscated" → "hard to see" -- Split into two short sentences (8 and 11 words) - -#### Example 4: Filler Words + Redundancy - -**Original (Grade 10):** -``` -Simply navigate to the configuration page and just enter your credentials. This is a very straightforward process that is actually quite easy to complete, due to the fact that the interface is basically self-explanatory. -``` - -**Simplified (Grade 6):** -``` -Go to the configuration page and enter your credentials. The interface is self-explanatory. -``` - -**Changes:** -- Removed fillers: "Simply", "just", "very", "actually quite", "basically" -- Removed redundancy: "due to the fact that" → (removed) -- "navigate to" → "Go to" -- Cut from 28 words to 13 words -- More direct and confident - -### Step 5: Present Simplified Version - -Show the user: - -```markdown -## Original -**Reading level:** 12th grade -**Average sentence length:** 28 words -**Passive voice:** 4 instances - -[Original text] - -## Simplified -**Reading level:** 8th grade -**Average sentence length:** 14 words -**Passive voice:** 0 instances - -[Simplified text] - -## Changes made -- Broke 3 long sentences (25+ words) into 7 shorter sentences -- Changed 4 passive voice constructions to active voice -- Removed jargon: "instantiate" → "create", "utilize" → "use", "leverage" → "use" -- Removed filler words: "simply", "very", "just" (5 instances) -- Defined acronym: ALB (Application Load Balancer) -- Removed redundancy: "in order to" → "to" (3 instances) -- Split complex paragraph into two focused paragraphs -- Reduced word count from 247 to 178 words (28% reduction) -``` - -### Step 6: Apply Changes - -After user approval: - -1. **Use Edit tool** to replace the content -2. **Preserve structure**. keep headings, lists, code blocks unchanged -3. **Maintain formatting**. line breaks, markdown syntax -4. **Confirm success** - -## Safety Guidelines - -- **NEVER modify automatically**. always show simplified version first and get approval -- **Preserve technical accuracy**. don't oversimplify to the point of incorrectness -- **Keep code unchanged**. only simplify prose, not code snippets or examples -- **Maintain original meaning**. clarify, don't change intent or facts -- **Don't remove necessary technical terms**. if a term is required, define it instead - -## What NOT to Simplify - -1. **Code snippets or examples**. Leave code as-is -2. **API endpoint names**. Don't change technical identifiers -3. **Product names**. Proper nouns stay the same -4. **Quotes or references**. Don't modify quoted content -5. **Already-simple content**. If it's 8th grade or below, leave it -6. **URLs or file paths**. Technical paths must stay exact -7. **Version numbers**. Don't change technical specifications - -## Edge Cases - -### Already simple content -If content already meets readability standards: -``` -This content already meets the 8th-grade reading level standard. The average sentence length is 15 words, and there's no passive voice or excessive jargon. No simplification needed. -``` - -### Highly technical content -If content must stay technical: -- Simplify the surrounding explanation -- Define technical terms clearly -- Add examples or analogies -- Don't sacrifice accuracy - -Example: -``` -Before: "The OAuth 2.0 authorization framework leverages bearer tokens." -After: "The OAuth 2.0 authorization framework uses bearer tokens (credentials that grant access without additional verification)." -``` - -### Lists and tables -Focus on descriptive text, not list items: -- Simplify list introductions -- Clarify bullet descriptions -- Don't change list structure - -### Short content (1-2 sentences) -May already be optimal: -- Check reading level -- Fix passive voice if present -- Remove filler only -- Don't over-engineer - diff --git a/.claude/commands/tone-check.md b/.claude/commands/tone-check.md deleted file mode 100644 index 97715675ea..0000000000 --- a/.claude/commands/tone-check.md +++ /dev/null @@ -1,486 +0,0 @@ -# Tone Check — Sumo Logic Voice and Tone Validation - -Validates documentation against Sumo Logic voice and tone rules, identifying violations and suggesting fixes. - -## Workflow - -### Step 1: Fetch Style Guide - -Always fetch before analyzing: -- https://www.sumologic.com/help/docs/contributing/style-guide/ -- https://www.sumologic.com/help/docs/contributing/word-list/ - -These are the authoritative sources for voice and tone rules. - -### Step 2: Get the File - -Ask user which file to check if not specified: -- **Full path**: `/Users/kpohas/sumologic-documentation/docs/integrations/amazon-aws/cloudtrail.md` -- **Relative path**: `docs/integrations/amazon-aws/cloudtrail.md` -- **Filename**: `cloudtrail.md` (search for it) - -### Step 3: Analyze Voice and Tone - -Check for specific violations in order of severity: - -## Critical Issues (Must Fix) - -These MUST be fixed before merging. - -### Wrong Pronouns - -❌ **Violations:** -- "the user can configure" -- "users should navigate" -- "one can access" -- "customers will receive" - -✅ **Correct:** -- "you can configure" -- "you should navigate" or "Navigate" -- "you can access" -- "you'll receive" - -**Why it matters:** Directly addressing the reader as "you" is conversational and engaging. Third-person references ("the user", "one") create distance and feel institutional. - -### Negative Contractions - -❌ **Violations:** -- can't → **cannot** -- won't → **will not** -- don't → **do not** -- isn't → **is not** -- aren't → **are not** -- wasn't → **was not** -- weren't → **were not** -- hasn't → **has not** -- haven't → **have not** -- didn't → **did not** -- doesn't → **does not** -- shouldn't → **should not** -- wouldn't → **would not** -- couldn't → **could not** - -✅ **Correct:** Always spell out negative contractions - -**Why it matters:** This is a firm Sumo Logic style rule. Negative contractions must always be spelled out, even in conversational tone. - -**Positive contractions are OK:** -- you'll, they're, we're, it's, you've, we've - -### Incorrect Branding - -❌ **Violations:** -- "Sumo" (in prose, not code) -- App doc without proper opener -- Source doc without proper opener - -✅ **Correct:** -- "Sumo Logic" or "we" -- App docs: "The Sumo Logic app for [Vendor]..." -- Source docs: "The Sumo Logic source for [Vendor]..." - -**Why it matters:** Consistent branding and proper document openers establish authority and professionalism. - -## Warnings (Should Fix) - -These should be fixed but won't block merging. - -### Passive Voice - -Passive voice is wordy and less direct. - -❌ **Passive examples:** -- "Data is ingested by Sumo Logic" -- "The dashboard can be configured by users" -- "Logs are parsed and indexed" -- "Alerts are triggered when thresholds are exceeded" -- "The source can be set up in minutes" - -✅ **Active alternatives:** -- "Sumo Logic ingests data" -- "You can configure the dashboard" -- "Sumo Logic parses and indexes logs" -- "Sumo Logic triggers alerts when thresholds are exceeded" -- "You can set up the source in minutes" - -**How to identify:** -- Look for "is/are/was/were + past participle" -- Look for "by [actor]" phrases -- Ask: "Who/what is doing the action?" - -**When passive is OK:** -- When the actor is unknown or unimportant -- In technical specifications -- In rare cases for emphasis - -### "Please" in Directives - -Don't use "please" in task instructions. - -❌ **Violations:** -- "Please configure the source" -- "Please click **Save**" -- "Please refer to the documentation" -- "Please note that..." - -✅ **Correct:** -- "Configure the source" -- "Click **Save**" -- "Learn more in the documentation" or "See [link]" -- "Note that..." or just state the fact - -**Why it matters:** Instructional directives should be clear and confident, not apologetic. "Please" makes them sound tentative. - -### "Must" Instead of "Need To" - -Prefer "need to" over "must" for a friendlier tone. - -❌ **Violations:** -- "You must configure authentication" -- "Users must have admin access" -- "You must restart the service" - -✅ **Correct:** -- "You need to configure authentication" -- "You need admin access" -- "You need to restart the service" - -**Exception:** "Must" is OK for hard requirements in technical specifications or legal compliance. - -### Filler Adjectives - -Remove words that add no meaning. - -❌ **Common fillers:** -- **very** (very important, very useful) -- **simply** (simply click, simply add) -- **just** (just navigate, just enter) -- **easy** (easy to use, easy to configure) -- **straightforward** (straightforward process) -- **quickly** (quickly set up) — unless specific time is meant -- **easily** (easily configure) -- **basic** (basic setup) — unless contrasting with advanced - -✅ **Correct:** -- "important" (not "very important") -- "click" (not "simply click") -- "navigate" (not "just navigate") -- "configure" (not "easy to configure") -- Remove or rewrite without filler - -**Why it matters:** Filler words dilute meaning and make content less confident. They often telegraph that something is harder than claimed. - -## Suggestions (Nice to Have) - -These improve quality but are lower priority. - -### Overly Formal Language - -Replace stiff, institutional language with conversational alternatives. - -❌ **Formal:** -- utilize → **use** -- in order to → **to** -- due to the fact that → **because** -- at this point in time → **now** -- in the event that → **if** -- prior to → **before** -- subsequent to → **after** -- commence → **start, begin** -- terminate → **end, stop** -- ascertain → **find out, determine** -- facilitate → **help, enable** -- leverage → **use** - -✅ **Conversational:** Use simpler alternatives - -### Uncommon Contractions - -Avoid contractions that sound awkward when read aloud. - -❌ **Uncommon:** -- should've -- it'll -- they'd -- you'd -- there'd - -✅ **Alternatives:** -- "should have" or rewrite -- "it will" or rewrite -- "they would" or rewrite -- "you would" or rewrite -- "there would" or rewrite - -**Common contractions are OK:** -- you'll, they're, we're, it's, you've, we've, that's, here's - -### Regional Idioms - -Avoid phrases that may not translate well. - -❌ **Regional idioms:** -- "hit the ground running" -- "low-hanging fruit" -- "ballpark figure" -- "touch base" -- "circle back" -- "boil the ocean" - -✅ **Clear alternatives:** -- "start quickly" -- "quick wins" or "easy improvements" -- "rough estimate" -- "check in" or "follow up" -- "revisit this" -- "attempt too much" - -### Step 4: Generate Report - -Format the report with severity levels: - -```markdown -# Tone Check Report -**File**: docs/integrations/amazon-aws/cloudtrail.md -**Date**: March 23, 2026 -**Status**: ⚠️ 12 issues found - -## Summary -- 3 Critical issues (must fix) -- 6 Warnings (should fix) -- 3 Suggestions (nice to have) - ---- - -## Critical Issues (Must Fix) - -### Wrong Pronouns (2 instances) - -**Line 45:** -``` -the user can configure the source -``` -→ Should be: `you can configure the source` - -**Line 67:** -``` -Users should navigate to the Collection page -``` -→ Should be: `You should navigate to the Collection page` or `Navigate to the Collection page` - ---- - -### Negative Contractions (1 instance) - -**Line 89:** -``` -The field can't be modified after creation -``` -→ Should be: `The field cannot be modified after creation` - ---- - -## Warnings (Should Fix) - -### Passive Voice (4 instances) - -**Line 23:** -``` -Data is collected by the Collector -``` -→ Should be: `The Collector collects data` - -**Line 34:** -``` -Logs are parsed and indexed by Sumo Logic -``` -→ Should be: `Sumo Logic parses and indexes logs` - -**Line 56:** -``` -The dashboard can be customized by users -``` -→ Should be: `You can customize the dashboard` - -**Line 78:** -``` -Alerts are triggered when thresholds are exceeded -``` -→ Should be: `Sumo Logic triggers alerts when thresholds are exceeded` - ---- - -### "Please" in Directives (2 instances) - -**Line 12:** -``` -Please click **Save** to apply changes. -``` -→ Should be: `Click **Save** to apply changes.` - -**Line 91:** -``` -Please refer to the troubleshooting guide for help. -``` -→ Should be: `See the troubleshooting guide for help.` or `Learn more in the troubleshooting guide.` - ---- - -## Suggestions (Nice to Have) - -### Filler Words (3 instances) - -**Line 15:** -``` -Simply click the **Add** button to begin. -``` -→ Should be: `Click the **Add** button to begin.` - -**Line 42:** -``` -This feature is very important for security. -``` -→ Should be: `This feature is important for security.` - -**Line 73:** -``` -The source is easy to configure in just a few steps. -``` -→ Should be: `Configure the source in a few steps.` or `You can configure the source in a few steps.` - ---- - -## Next Steps - -Would you like me to: -1. **Auto-fix all issues**. Apply all corrections automatically -2. **Fix critical issues only**. Just fix the must-have items -3. **Show specific fixes**. Let me walk through each fix -4. **Generate checklist**. Create a manual review checklist -5. **Export report**. Save this report as a markdown file -``` - -### Step 5: Offer Fixes - -After presenting the report, ask what the user wants to do: - -**Option 1: Auto-fix all** -- Apply all corrections using Edit tool -- Show summary of changes made -- Re-run tone check to verify - -**Option 2: Fix by severity** -- Critical only -- Critical + warnings -- Custom selection - -**Option 3: Manual review** -- User fixes themselves -- Provide checklist -- Available for questions - -## Safety Guidelines - -- **NEVER modify automatically without asking**. always present report first -- **Provide context**. explain WHY something violates tone rules, not just WHAT -- **Show specific fixes**. don't just flag issues, suggest corrections with line numbers -- **Preserve technical accuracy**. tone fixes should not change meaning -- **Respect user decisions**. if they decline a fix, respect that choice - -## What NOT to Flag - -1. **Code blocks**. Don't check voice/tone in code snippets -2. **Quoted content**. Don't flag violations in quotations -3. **Product names**. Don't flag "Sumo" in product names like "Sumo App" -4. **URLs and paths**. Don't check tone in technical identifiers -5. **Examples of wrong usage**. Don't flag intentionally incorrect examples -6. **Comments or notes**. May use different tone - -## Edge Cases - -### No Issues Found - -If content passes all checks: -```markdown -# Tone Check Report -**File**: docs/integrations/amazon-aws/cloudtrail.md -**Status**: ✅ All checks passed - -This document meets all Sumo Logic voice and tone standards: -- No pronoun violations -- No negative contractions -- No passive voice -- No "please" in directives -- No filler words -- Proper branding - -Great work! -``` - -### Too Many Issues - -If there are 20+ violations: -```markdown -# Tone Check Report -**Status**: ⚠️ 47 issues found - -This document has significant voice and tone issues. I recommend: - -1. Start with critical issues (12 found) -2. Review patterns (passive voice appears 23 times) -3. Consider rewriting sections instead of fixing individually -4. Use /rewrite-intro for the opening -5. Use /simplify for complex sections - -Would you like me to: -- Fix all critical issues first? -- Rewrite the most problematic sections? -- Provide a training overview of the main issues? -``` - -### Mixed Content Types - -Different sections may have different standards: -- **Prose**: Apply all voice/tone rules -- **Code**: Skip tone checks -- **Examples**: Check explanatory text, not examples themselves -- **Quotes**: Don't check quoted content -- **Technical specs**: More lenient on passive voice - -### Document-Specific Exceptions - -Some documents may have valid exceptions: -- **API reference**: May use passive voice for specifications -- **Release notes**: May use past tense and passive voice -- **Legal/compliance**: May need formal language -- **Migration guides**: May reference "users" when describing old vs. new behavior - -Flag these as suggestions, not critical issues. - -## Common Patterns - -### Serial Offenders - -**Passive voice throughout:** -``` -Recommend: "I found 15 instances of passive voice. Would you like me to convert them all to active voice?" -``` - -**Wrong pronouns everywhere:** -``` -Recommend: "The document consistently uses 'users' instead of 'you'. Let me update all 12 instances." -``` - -**Filler word addiction:** -``` -Recommend: "'Simply' appears 8 times and 'just' appears 11 times. These can all be removed." -``` - -### One-Off Violations - -For 1-2 violations, just fix them: -``` -"Found one negative contraction on line 45. Should I fix it?" -``` - diff --git a/CLAUDE.md b/CLAUDE.md index 14f0a3a1cd..5c84b15572 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -105,9 +105,6 @@ Primary commands for documentation work. Proactively suggest when context fits | `/audit-doc` | Full quality audit: structure, style, links, frontmatter, completeness | | `/seo-audit` | Discoverability audit: SEO, AEO, and GEO signals — run this before a PR | | `/geo-optimize` | Rewrite a doc to improve AI citation and generative engine visibility | -| `/tone-check` | Check voice and tone against Sumo Logic style rules | -| `/rewrite-intro` | Rewrite a doc's opening paragraph | -| `/simplify` | Simplify overly complex content | | `/review` | Review a pull request — applies audit-doc checks to all changed `.md` files | **Jira** From 45ac0e51b2c60746b8b7d986638206d648563629 Mon Sep 17 00:00:00 2001 From: Kim Pohas Date: Fri, 5 Jun 2026 00:26:21 -0700 Subject: [PATCH 13/22] revert release notes --- .claude/commands/release-note-collector.md | 102 ++++++ .claude/commands/release-note-cse.md | 111 +++++++ .claude/commands/release-note-csoar.md | 131 ++++++++ .claude/commands/release-note-developer.md | 63 ++++ .claude/commands/release-note-service.md | 57 ++++ .claude/commands/release-note.md | 369 --------------------- CLAUDE.md | 6 +- 7 files changed, 469 insertions(+), 370 deletions(-) create mode 100644 .claude/commands/release-note-collector.md create mode 100644 .claude/commands/release-note-cse.md create mode 100644 .claude/commands/release-note-csoar.md create mode 100644 .claude/commands/release-note-developer.md create mode 100644 .claude/commands/release-note-service.md delete mode 100644 .claude/commands/release-note.md diff --git a/.claude/commands/release-note-collector.md b/.claude/commands/release-note-collector.md new file mode 100644 index 0000000000..9e6474d99d --- /dev/null +++ b/.claude/commands/release-note-collector.md @@ -0,0 +1,102 @@ +# Create New Collector Release Note + +Creates a Collector release note — either an Installed Collector version release or an OpenTelemetry Collector feature announcement. + +## Workflow + +### Step 1: Determine release type + +Ask the user: **Installed Collector** (version release with security/bug fixes) or **OpenTelemetry Collector** (feature announcement)? + +### Step 2: Gather information + +**For Installed Collector:** +- Version number (X.Y.Z-N format, e.g. 19.535-6) +- Release date (YYYY-MM-DD) +- List of security fixes, bug fixes, and/or features + +**For OpenTelemetry Collector:** +- Feature name +- Release date (YYYY-MM-DD) +- Description (focus on user benefit, 2–3 sentences) +- Doc link (relative path) + +### Step 3: Create the file + +**File**: `blog-collector/YYYY-MM-DD-{type}.md` — type is `-installed` or `-otel` + +If a file already exists for the same date and type, ask the user to use a different date or append. + +--- + +#### Installed Collector + +**Frontmatter**: +```yaml +--- +title: Installed Collector Version {X.Y.Z-N} +image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 +hide_table_of_contents: true +keywords: + - installed-collector +--- +``` + +**Content**: +```markdown +In this release, we've enhanced the security and stability of the Collector with added support for {security patches/bug fixes/features}. + +#### Security fix + +* Upgraded `{package}` to version **{version}** to address known security vulnerability ({CVE-YYYY-NNNNN}). + +#### Bug fix + +* {Bug fix description}. +``` + +- Sections use H4 (`####`). Order: Security fix → Bug fix → Feature. +- Package names in backticks, version numbers in **bold**. +- Include CVE/GHSA references where applicable (CVE-YYYY-NNNNN or GHSA-XXXX-XXXX-XXXX). +- Keywords are always `installed-collector` — no confirmation needed. + +--- + +#### OpenTelemetry Collector + +**Frontmatter**: +```yaml +--- +title: {Feature Name} +image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 +hide_table_of_contents: true +keywords: + - opentelemetry-collector +--- +``` + +**Content**: +```markdown +import useBaseUrl from '@docusaurus/useBaseUrl'; + +We're excited to announce {feature description}. {Benefits}. [Learn more](/docs/path/to/doc). +``` + +- Start with "We're excited to announce..." or "We're excited to introduce..." +- Keywords are always `opentelemetry-collector` — no confirmation needed. +- Use admonitions for important notes or breaking changes. + +### Step 4: Validate + +**Installed Collector:** +- [ ] `blog-collector/YYYY-MM-DD-installed.md` +- [ ] Title: "Installed Collector Version X.Y.Z-N" +- [ ] H4 sections in correct order (Security → Bug → Feature) +- [ ] Versions in **bold**, packages in backticks +- [ ] CVE/GHSA references where applicable + +**OpenTelemetry Collector:** +- [ ] `blog-collector/YYYY-MM-DD-otel.md` +- [ ] Starts with "We're excited to..." +- [ ] "Learn more" link with relative path +- [ ] Keywords: `opentelemetry-collector` diff --git a/.claude/commands/release-note-cse.md b/.claude/commands/release-note-cse.md new file mode 100644 index 0000000000..bbb7238631 --- /dev/null +++ b/.claude/commands/release-note-cse.md @@ -0,0 +1,111 @@ +# Create New Cloud SIEM Release Note + +Creates a Cloud SIEM (CSE) release note — either a content release (rules, log mappers, parsers) or an application release (features, bug fixes, UI updates). + +## Workflow + +### Step 1: Determine release type + +Ask the user: **Content release** (rules, log mappers, parsers — typically bi-weekly) or **Application release** (new features, bug fixes, UI improvements)? + +### Step 2: Gather information + +**For content releases:** +- Release date (YYYY-MM-DD) +- New/updated rules (IDs and names) — do not invent rule IDs, ask the user +- New/updated log mappers +- New/updated parsers +- 3–5 high-level summary points +- Keywords (confirm with user; default: rules, log mappers, parsers) + +**For application releases:** +- Release date (YYYY-MM-DD) +- Features with descriptions and doc links +- Keywords (confirm with user) + +### Step 3: Create the file + +**File**: `blog-cse/YYYY-MM-DD-{type}.md` — type is `-content` or `-application` + +Always include `import useBaseUrl from '@docusaurus/useBaseUrl';` after frontmatter. + +If a file already exists for the same date and type, ask the user to use a different date or append. + +--- + +#### Content release + +**Frontmatter**: +```yaml +--- +title: {Month} {Day ordinal}, {Year} - Content Release +hide_table_of_contents: true +keywords: + - rules + - log mappers + - parsers +image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 +--- +``` + +Title uses ordinal suffix: "March 19th, 2026 - Content Release", "February 3rd, 2026 - Content Release". Full month name, not abbreviated. + +**Content**: +```markdown +This content release includes: + - {Summary point 1} + - {Summary point 2} + +Additional changes are enumerated below. + +### Rules +* [New] MATCH-SXXXX Rule Name. +* [Updated] FIRST-SXXXX Rule Name. Brief description of what changed. + +### Log Mappers +* [New] Vendor - Event Type. + +### Parsers +* [Updated] /Parsers/System/Vendor/Parser Name. +``` + +- Summary bullets use 4-space indentation. +- `[New]` or `[Updated]` tag on every item. +- Rule ID formats: `MATCH-SXXXX`, `FIRST-SXXXX`, `THRESHOLD-SXXXX`, `AGGREGATION-SXXXX`, `CHAIN-SXXXX`, `OUTLIER-SXXXX` +- Parser paths use full hierarchy: `/Parsers/System/Vendor/Name` +- Log mapper format: `Vendor - Event Type` +- Sort alphabetically within each section. + +--- + +#### Application release + +**Frontmatter**: +```yaml +--- +title: {Month} {Day}, {Year} - Application Update +image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 +keywords: + - {keyword} +hide_table_of_contents: true +--- +``` + +**Content**: +```markdown +### {Feature Name} + +{Description and business value}. [Learn more](/docs/path/to/docs). +``` + +H3 for each feature. Add screenshots with `description` for UI changes. + +### Step 4: Validate + +- [ ] `blog-cse/YYYY-MM-DD-{type}.md` +- [ ] Title uses ordinal suffix for content releases +- [ ] `import useBaseUrl` included +- [ ] `hide_table_of_contents: true` +- [ ] Content: `[New]`/`[Updated]` tags on all items; parser paths complete +- [ ] Keywords confirmed with user +- [ ] No trailing whitespace diff --git a/.claude/commands/release-note-csoar.md b/.claude/commands/release-note-csoar.md new file mode 100644 index 0000000000..9c0ff2bc39 --- /dev/null +++ b/.claude/commands/release-note-csoar.md @@ -0,0 +1,131 @@ +# Create New Cloud SOAR Release Note + +Creates a Cloud SOAR (Automation Service) release note — either a content release (new integrations and playbooks) or an application update (platform features, enhancements, bug fixes). + +## Workflow + +### Step 1: Determine release type + +Ask the user: **Content release** (new/updated integrations and playbooks) or **Application update** (platform features, enhancements, bug fixes — published early the following month)? + +### Step 2: Gather information + +**For content releases:** +- Publication date (YYYY-MM-DD) +- New/updated integrations (names and doc links) +- New playbooks (ID numbers and titles) +- Keywords (confirm with user; default: automation service, cloud soar, soar) + +**For application updates:** +- Publication date (YYYY-MM-DD) — typically early the month following the release month +- Release month (e.g. "February" if published in March) +- Integration changes with descriptions +- Platform changes +- Bug fixes +- Keywords (confirm with user; default: automation service, cloud soar) + +### Step 3: Create the file + +**File**: +- Content release: `blog-csoar/YYYY-MM-DD-content-release.md` +- Application update: `blog-csoar/YYYY-MM-DD-application-update.md` + +Always include `import useBaseUrl from '@docusaurus/useBaseUrl';` after frontmatter. + +**Date format in title**: "Month DD, YYYY" — full month name, zero-padded day, no ordinal. +- ✅ "March 06, 2026" | ❌ "March 6, 2026" | ❌ "March 6th, 2026" + +**Integration doc path**: `/docs/platform-services/automation-service/app-central/integrations/{slug}/` + +If a file already exists, ask the user to use a different date or append. + +--- + +#### Content release + +**Frontmatter**: +```yaml +--- +title: {Month DD, 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: + - automation service + - cloud soar + - soar +--- +``` + +**Content**: +```markdown +This release introduces {what's new}. + +### Integrations + +* [New] [Integration Name](/docs/platform-services/automation-service/app-central/integrations/{slug}/) +* [Updated] [Integration Name](/docs/platform-services/automation-service/app-central/integrations/{slug}/) + +### Playbooks + +* [New] {ID} - {Playbook Title} +``` + +Integration entries are link-only — no descriptions. Playbooks section is optional. + +--- + +#### Application update + +Application Updates cover the previous month's changes. Filename and title use the publication date; the H2 header and intro use the release month. + +**Frontmatter**: +```yaml +--- +title: {Month DD, 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: + - automation service + - cloud soar +--- +``` + +**Content**: +```markdown +## {Release month} release + +Following are the updates made in {Month} {YYYY}. + +### Changes and enhancements + +#### Integrations + +* [Added] [Integration Name](/docs/path/) - Description of what was added. +* [Updated] [Integration Name](/docs/path/) - Description of what was updated. + +#### Platform + +* Platform enhancement description. + +### Bug Fixes + +#### Integrations + +* In the [Integration Name](/docs/path/) integration, description of fix. + +#### Platform + +Fixed an issue where {description}. +``` + +Integration changes use `[Added]` for new integrations, `[Updated]` for existing — always include descriptions (unlike content releases). + +### Step 4: Validate + +- [ ] Filename uses full suffix (`-content-release.md` or `-application-update.md`) +- [ ] Title: "Month DD, YYYY" format (zero-padded, no ordinal) +- [ ] `import useBaseUrl` included +- [ ] `hide_table_of_contents: true` +- [ ] Keywords confirmed with user +- [ ] Application update: H2 header uses release month, not publication month +- [ ] No trailing whitespace diff --git a/.claude/commands/release-note-developer.md b/.claude/commands/release-note-developer.md new file mode 100644 index 0000000000..50913bc53f --- /dev/null +++ b/.claude/commands/release-note-developer.md @@ -0,0 +1,63 @@ +# Create New Developer Release Note + +Creates a Developer release note for API changes, SDK updates, deprecations, CLI updates, or other developer-facing platform changes. + +## Workflow + +### Step 1: Gather information + +Ask the user for: +- **Title/topic**: brief description (e.g. "New Field Extraction Rules API", "Deprecation of India Data Center") +- **Release date**: YYYY-MM-DD format +- **Content**: what changed, why it matters, impact on existing users +- **Doc links**: relative paths to relevant docs +- **Keywords**: optional; ask the user — suggest based on content type: + - API changes: `api`, `endpoints` + - SDK updates: `sdk`, `python`, `java`, etc. + - Deprecations: `deprecation`, `end-of-life` + - Breaking changes: `breaking-change` + +### Step 2: Create the file + +**File**: `blog-developer/YYYY-MM-DD-{slug}.md` + +Slug: lowercase, hyphens, 3–5 words. Examples: `api-endpoints`, `india-datacenter-deprecation`, `python-sdk-v2`. + +If a file already exists, ask the user to use a different date or a more specific slug. + +**Frontmatter**: +```yaml +--- +title: {Month Day, YYYY} - {Topic} +image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 +hide_table_of_contents: true +--- +``` + +**Title format**: "Month Day, YYYY - Topic" — full month name, no ordinal. +- ✅ "April 9, 2025" | ❌ "April 9th, 2025" | ❌ "Apr 9, 2025" + +Add `keywords` to frontmatter only if the user wants them. + +**Content**: +```markdown +{Main paragraph — what changed, why it matters} + +#### {Subsection if needed} + +* {Item} +``` + +- H4 (`####`) for subsections (new endpoints, breaking changes, migration steps, etc.). +- Use `:::warning` admonitions for breaking changes. +- Doc links always use relative paths (`/docs/...`). +- Only add `import useBaseUrl` if content uses images. + +### Step 3: Validate + +- [ ] `blog-developer/YYYY-MM-DD-{slug}.md` +- [ ] Title: "Month Day, YYYY - Topic" (no ordinal) +- [ ] `hide_table_of_contents: true` +- [ ] Breaking changes clearly marked +- [ ] Doc links use relative paths +- [ ] No trailing whitespace diff --git a/.claude/commands/release-note-service.md b/.claude/commands/release-note-service.md new file mode 100644 index 0000000000..09ca45aff9 --- /dev/null +++ b/.claude/commands/release-note-service.md @@ -0,0 +1,57 @@ +# Create New Service Release Note + +Creates a Service release note for a new feature, update, or improvement across Sumo Logic platform categories. + +## Workflow + +### Step 1: Gather information + +Ask the user for: +- **Category**: apps, collection, manage, search, or ui +- **Feature name**: brief, descriptive name +- **Release date**: YYYY-MM-DD format +- **Description**: 2–3 sentences — what the feature is and why it matters +- **Doc link**: relative path (optional) +- **"What's new" bullets**: optional, for multiple specific changes +- **Keywords**: confirm with user before creating file + +### Step 2: Create the file + +**File**: `blog-service/YYYY-MM-DD-{category}.md` + +If a file already exists for the same date and category, ask the user to use a different date, append to the existing file, or add a more specific suffix. + +**Frontmatter**: +```yaml +--- +title: {Feature Description} ({Category Label}) +image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 +keywords: + - {keyword1} +hide_table_of_contents: true +--- +``` + +**Title**: Feature description in Title Case + category label in parentheses. No date in title. +- apps → (Apps) | collection → (Collection) | manage → (Manage) | search → (Search) | ui → (New UI) + +**Content**: +```markdown +{Description — what the feature is and why it matters} + +**What's new:** +* {Specific capability} + +[Learn more](/docs/path/to/doc). +``` + +"What's new:" is optional — use for multiple specific changes, omit for single-point announcements. Only add `import useBaseUrl` if the content uses it. + +### Step 3: Validate + +- [ ] `blog-service/YYYY-MM-DD-{category}.md` +- [ ] Title: feature description + category label in parens, no date +- [ ] `hide_table_of_contents: true` +- [ ] Keywords confirmed with user +- [ ] Doc link uses `/docs/...` relative path +- [ ] No trailing whitespace diff --git a/.claude/commands/release-note.md b/.claude/commands/release-note.md deleted file mode 100644 index 1d819cb272..0000000000 --- a/.claude/commands/release-note.md +++ /dev/null @@ -1,369 +0,0 @@ -# Release Note - -Creates release notes for Sumo Logic products. Ask the user which type before proceeding. - -## Types - -| Type | Blog dir | File pattern | -|---|---|---| -| **Service** | `blog-service/` | `YYYY-MM-DD-{category}.md` | -| **Collector** | `blog-collector/` | `YYYY-MM-DD-{type}.md` | -| **Cloud SIEM** | `blog-cse/` | `YYYY-MM-DD-{type}.md` | -| **Cloud SOAR** | `blog-csoar/` | `YYYY-MM-DD-{subtype}.md` | -| **Developer** | `blog-developer/` | `YYYY-MM-DD-{slug}.md` | - -Ask the user which type, then follow the appropriate section below. - -**Shared frontmatter values (all types):** -- `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` - -If a file already exists for the same date and type, ask the user to use a different date, append to the existing file, or add a more specific suffix. - ---- - -## Service (`blog-service/`) - -**Subtypes**: apps, collection, manage, search, ui - -**Gather**: category, feature name, release date, description (2–3 sentences), doc link (optional), "What's new" bullets (optional), keywords (confirm with user before creating file). - -**File**: `blog-service/YYYY-MM-DD-{category}.md` - -**Frontmatter**: -```yaml ---- -title: {Feature Description} ({Category Label}) -image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 -keywords: - - {keyword1} -hide_table_of_contents: true ---- -``` - -**Title**: Feature description in Title Case + category label in parentheses. No date in title. -- apps → (Apps) | collection → (Collection) | manage → (Manage) | search → (Search) | ui → (New UI) - -**Content**: -```markdown -{Description — what the feature is and why it matters} - -**What's new:** -* {Specific capability} - -[Learn more](/docs/path/to/doc). -``` - -"What's new:" is optional — use for multiple specific changes, omit for single-point announcements. Only add `import useBaseUrl` if the content uses it. - -**Validation**: -- [ ] `blog-service/YYYY-MM-DD-{category}.md` -- [ ] Title: feature description + category label in parens, no date -- [ ] `hide_table_of_contents: true` -- [ ] Keywords confirmed with user -- [ ] Doc link uses `/docs/...` relative path - ---- - -## Collector (`blog-collector/`) - -**File**: `blog-collector/YYYY-MM-DD-{type}.md` (`-installed` or `-otel`) - -### Installed Collector - -**Gather**: version number (X.Y.Z-N), release date, list of security fixes / bug fixes / features. - -**Frontmatter**: -```yaml ---- -title: Installed Collector Version {X.Y.Z-N} -image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 -hide_table_of_contents: true -keywords: - - installed-collector ---- -``` - -**Content**: -```markdown -In this release, we've enhanced the security and stability of the Collector with added support for {security patches/bug fixes/features}. - -#### Security fix - -* Upgraded `{package}` to version **{version}** to address known security vulnerability ({CVE-YYYY-NNNNN}). - -#### Bug fix - -* {Bug fix description}. -``` - -- Sections use H4 (`####`). Order: Security fix → Bug fix → Feature. -- Package names in backticks, version numbers in **bold**. -- Include CVE/GHSA references (CVE-YYYY-NNNNN or GHSA-XXXX-XXXX-XXXX). -- Keywords are always `installed-collector` — no user confirmation needed. - -**Validation**: -- [ ] Title: "Installed Collector Version X.Y.Z-N" -- [ ] H4 sections in correct order (Security → Bug → Feature) -- [ ] Versions in **bold**, packages in backticks -- [ ] CVE/GHSA references where applicable - -### OpenTelemetry Collector - -**Gather**: feature name, release date, description (focus on user benefit), doc link. - -**Frontmatter**: -```yaml ---- -title: {Feature Name} -image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 -hide_table_of_contents: true -keywords: - - opentelemetry-collector ---- -``` - -**Content**: -```markdown -import useBaseUrl from '@docusaurus/useBaseUrl'; - -We're excited to announce {feature description}. {Benefits}. [Learn more](/docs/path/to/doc). -``` - -Start with "We're excited to announce..." or "We're excited to introduce...". Keywords are always `opentelemetry-collector` — no user confirmation needed. Use admonitions for important notes or breaking changes. - -**Validation**: -- [ ] Starts with "We're excited to..." -- [ ] "Learn more" link with relative path -- [ ] Keywords: `opentelemetry-collector` - ---- - -## Cloud SIEM (`blog-cse/`) - -**File**: `blog-cse/YYYY-MM-DD-{type}.md` (`-content` or `-application`) - -Always include `import useBaseUrl from '@docusaurus/useBaseUrl';` after frontmatter. - -### Content release - -**Gather**: release date, new/updated rules (IDs and names), log mappers, parsers, 3–5 high-level summary points, keywords (confirm with user; default: rules, log mappers, parsers). - -**Frontmatter**: -```yaml ---- -title: {Month} {Day ordinal}, {Year} - Content Release -hide_table_of_contents: true -keywords: - - rules - - log mappers - - parsers -image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 ---- -``` - -Title uses ordinal suffix (12th, 3rd, 21st). Full month name, not abbreviated. Examples: "March 19th, 2026 - Content Release", "February 3rd, 2026 - Content Release". - -**Content**: -```markdown -This content release includes: - - {Summary point 1} - - {Summary point 2} - -Additional changes are enumerated below. - -### Rules -* [New] MATCH-SXXXX Rule Name. -* [Updated] FIRST-SXXXX Rule Name. Brief description of what changed. - -### Log Mappers -* [New] Vendor - Event Type. - -### Parsers -* [Updated] /Parsers/System/Vendor/Parser Name. -``` - -- Summary bullets use 4-space indentation. -- `[New]` or `[Updated]` tag on every item. -- Rule ID formats: `MATCH-SXXXX`, `FIRST-SXXXX`, `THRESHOLD-SXXXX`, `AGGREGATION-SXXXX`, `CHAIN-SXXXX`, `OUTLIER-SXXXX` -- Parser paths use full hierarchy: `/Parsers/System/Vendor/Name` -- Log mapper format: `Vendor - Event Type` -- Sort alphabetically within each section. -- Do not invent rule IDs — ask the user if not provided. - -### Application release - -**Gather**: release date, features with descriptions and doc links, screenshots (if applicable), keywords (confirm with user). - -**Frontmatter**: -```yaml ---- -title: {Month} {Day}, {Year} - Application Update -image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 -keywords: - - {keyword} -hide_table_of_contents: true ---- -``` - -**Content**: -```markdown -### {Feature Name} - -{Description and business value}. [Learn more](/docs/path/to/docs). -``` - -H3 for each feature. Add screenshots with `description` for UI changes. - -**Validation (both CSE types)**: -- [ ] `blog-cse/YYYY-MM-DD-{type}.md` -- [ ] Title uses ordinal suffix for content releases -- [ ] `import useBaseUrl` included -- [ ] `hide_table_of_contents: true` -- [ ] Content: `[New]`/`[Updated]` tags on all items; parser paths complete -- [ ] Keywords confirmed with user - ---- - -## Cloud SOAR (`blog-csoar/`) - -**File**: `blog-csoar/YYYY-MM-DD-{subtype}.md` -- Content release: `YYYY-MM-DD-content-release.md` -- Application update: `YYYY-MM-DD-application-update.md` - -Always include `import useBaseUrl from '@docusaurus/useBaseUrl';` after frontmatter. - -**Date format in title**: "Month DD, YYYY" — full month name, zero-padded day, no ordinal. Examples: "March 06, 2026" ✅, "March 6, 2026" ❌, "March 6th, 2026" ❌. - -Application Updates are published early the following month for the previous month's changes. Filename and title use the publication date; the H2 header and intro use the release month. - -**Keywords** (confirm with user): -- Content release: `automation service`, `cloud soar`, `soar` -- Application update: `automation service`, `cloud soar` - -**Integration doc path**: `/docs/platform-services/automation-service/app-central/integrations/{slug}/` - -### Content release - -**Frontmatter**: -```yaml ---- -title: {Month DD, 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: - - automation service - - cloud soar - - soar ---- -``` - -**Content**: -```markdown -This release introduces {what's new}. - -### Integrations - -* [New] [Integration Name](/docs/platform-services/automation-service/app-central/integrations/{slug}/) -* [Updated] [Integration Name](/docs/platform-services/automation-service/app-central/integrations/{slug}/) - -### Playbooks - -* [New] {ID} - {Playbook Title} -``` - -Integration entries are link-only — no descriptions. Playbooks section is optional. - -### Application update - -**Frontmatter**: -```yaml ---- -title: {Month DD, 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: - - automation service - - cloud soar ---- -``` - -**Content**: -```markdown -## {Release month} release - -Following are the updates made in {Month} {YYYY}. - -### Changes and enhancements - -#### Integrations - -* [Added] [Integration Name](/docs/path/) - Description of what was added. -* [Updated] [Integration Name](/docs/path/) - Description of what was updated. - -#### Platform - -* Platform enhancement description. - -### Bug Fixes - -#### Integrations - -* In the [Integration Name](/docs/path/) integration, description of fix. - -#### Platform - -Fixed an issue where {description}. -``` - -Integration changes use `[Added]` for new integrations, `[Updated]` for existing. Always include descriptions (unlike content releases). - -**Validation (both SOAR types)**: -- [ ] `blog-csoar/`; filename uses full suffix (`-content-release.md` or `-application-update.md`) -- [ ] Title: "Month DD, YYYY" format (zero-padded, no ordinal) -- [ ] `import useBaseUrl` included -- [ ] `hide_table_of_contents: true` -- [ ] Keywords confirmed with user -- [ ] Application update: H2 header uses release month, not publication month - ---- - -## Developer (`blog-developer/`) - -**Gather**: title/topic, release date, content (what changed, why it matters, impact), doc links, keywords (optional; ask user). - -**File**: `blog-developer/YYYY-MM-DD-{slug}.md` - -Slug: lowercase, hyphens, 3–5 words. Examples: `api-endpoints`, `india-datacenter-deprecation`, `python-sdk-v2`. - -**Frontmatter**: -```yaml ---- -title: {Month Day, YYYY} - {Topic} -image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 -hide_table_of_contents: true ---- -``` - -**Title format**: "Month Day, YYYY - Topic" — full month, no ordinal. Examples: "April 9, 2025" ✅, "April 9th, 2025" ❌, "Apr 9, 2025" ❌. - -**Content**: -```markdown -{Main paragraph — what changed, why it matters} - -#### {Subsection if needed} - -* {Item} -``` - -- H4 (`####`) for subsections. -- `:::warning` admonitions for breaking changes. -- Doc links always use relative paths (`/docs/...`). -- Only add `import useBaseUrl` if content uses images. - -**Validation**: -- [ ] `blog-developer/YYYY-MM-DD-{slug}.md` -- [ ] Title: "Month Day, YYYY - Topic" (no ordinal) -- [ ] `hide_table_of_contents: true` -- [ ] Breaking changes clearly marked -- [ ] Doc links use relative paths diff --git a/CLAUDE.md b/CLAUDE.md index 5c84b15572..ca0fe74ec5 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -96,7 +96,11 @@ Primary commands for documentation work. Proactively suggest when context fits | Command | What it does | |---------|-------------| -| `/release-note` | New release note (service, collector, Cloud SIEM, Cloud SOAR, or developer) | +| `/release-note-service` | New service release note | +| `/release-note-collector` | New Collector release note | +| `/release-note-cse` | New Cloud SIEM release note | +| `/release-note-csoar` | New Cloud SOAR release note | +| `/release-note-developer` | New developer/API release note | **Editing and reviewing** From e33b73ba16883a3bedd05d70562d8a685b8b1e6c Mon Sep 17 00:00:00 2001 From: Kim Pohas Date: Fri, 5 Jun 2026 00:35:33 -0700 Subject: [PATCH 14/22] revert release notes --- .claude/commands/release-note-collector.md | 410 ++++++++++++-- .claude/commands/release-note-cse.md | 422 +++++++++++++-- .claude/commands/release-note-csoar.md | 590 +++++++++++++++++++-- .claude/commands/release-note-developer.md | 507 ++++++++++++++++-- .claude/commands/release-note-service.md | 471 +++++++++++++++- 5 files changed, 2171 insertions(+), 229 deletions(-) diff --git a/.claude/commands/release-note-collector.md b/.claude/commands/release-note-collector.md index 9e6474d99d..faef82018f 100644 --- a/.claude/commands/release-note-collector.md +++ b/.claude/commands/release-note-collector.md @@ -1,37 +1,83 @@ # Create New Collector Release Note -Creates a Collector release note — either an Installed Collector version release or an OpenTelemetry Collector feature announcement. +Automates the creation of Collector release notes for Installed Collector versions and OpenTelemetry features. + +## What this command does + +When you invoke `release-note-collector`, Claude will guide you through: + +1. **Determine release type**. Installed Collector version or OpenTelemetry feature +2. **Gather release details**. Version number, changes, features, or fixes +3. **Create markdown file**. Generate file with proper frontmatter and structure +4. **Format content**. Apply correct formatting for version releases or features +5. **Validate and preview**. Check structure and provide next steps + +## When to use this command + +* Publishing new Installed Collector versions with bug or security fixes. +* Announcing OpenTelemetry collector features and improvements. +* Documenting collector version updates. +* Releasing new OpenTelemetry integrations or capabilities. + +## Release types + +### Installed Collector Release (`-installed.md`) + +For Installed Collector version releases: +* **Version numbers**: Format X.Y.Z-N (e.g., 19.535-6). +* **Security fixes**: CVE patches, dependency upgrades. +* **Bug fixes**: Issue resolutions and stability improvements. +* **Minor features**: Small enhancements in collector behavior. + +**Typical cadence**: As needed when versions ship + +### OpenTelemetry Release (`-otel.md`) + +For OpenTelemetry collector features: +* **New features**: Installation methods, integrations, capabilities. +* **Improvements**: Performance enhancements, reliability updates. +* **Announcements**: CDN changes, configuration updates. + +**Typical cadence**: As features are released ## Workflow -### Step 1: Determine release type +### Step 1: Gather information -Ask the user: **Installed Collector** (version release with security/bug fixes) or **OpenTelemetry Collector** (feature announcement)? +Ask the user for: -### Step 2: Gather information +**For Installed Collector releases:** +* **Version number**: Full version (e.g., 19.535-6). +* **Release date**: Date in YYYY-MM-DD format. +* **Changes**: List of security fixes, bug fixes, or features. -**For Installed Collector:** -- Version number (X.Y.Z-N format, e.g. 19.535-6) -- Release date (YYYY-MM-DD) -- List of security fixes, bug fixes, and/or features +**For OpenTelemetry releases:** +* **Feature name**: Name of the feature or update. +* **Release date**: Date in YYYY-MM-DD format. +* **Description**: What it does and why it matters (2-3 sentences). +* **Documentation link**: Relative path to the doc. -**For OpenTelemetry Collector:** -- Feature name -- Release date (YYYY-MM-DD) -- Description (focus on user benefit, 2–3 sentences) -- Doc link (relative path) +**Validate:** +* Check that date is not in the future. +* For installed releases, validate version number format. +* For OTel releases, ensure documentation link exists. -### Step 3: Create the file +### Step 2: Create the markdown file -**File**: `blog-collector/YYYY-MM-DD-{type}.md` — type is `-installed` or `-otel` +**File naming convention:** +``` +blog-collector/YYYY-MM-DD-{type}.md +``` -If a file already exists for the same date and type, ask the user to use a different date or append. +Examples: +* `blog-collector/2026-03-19-installed.md`. +* `blog-collector/2026-03-19-otel.md`. ---- +**Important**: Files are created in `/blog-collector/` directory -#### Installed Collector +### Step 3: Generate frontmatter -**Frontmatter**: +**For Installed Collector releases:** ```yaml --- title: Installed Collector Version {X.Y.Z-N} @@ -42,61 +88,317 @@ keywords: --- ``` -**Content**: +**For OpenTelemetry releases:** +```yaml +--- +title: {Feature Name} +image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 +hide_table_of_contents: true +keywords: + - opentelemetry-collector +--- +``` + +**Title formatting:** +* Installed: "Installed Collector Version X.Y.Z-N" +* OTel: Feature name in Title Case (no category suffix) + +**Keywords:** +* Installed Collector: Always use `installed-collector` +* OpenTelemetry: Always use `opentelemetry-collector` +* These keywords are standard and do not need user confirmation + +### Step 4: Add required import + +For OpenTelemetry releases that use links or useBaseUrl: +```javascript +import useBaseUrl from '@docusaurus/useBaseUrl'; +``` + +**Note**: Only add if content uses it. For simple version releases, omit. + +### Step 5: Write content + +#### Installed Collector Release Structure + ```markdown -In this release, we've enhanced the security and stability of the Collector with added support for {security patches/bug fixes/features}. +In this release, we've enhanced the security and stability of the Collector with added support for security patches. #### Security fix -* Upgraded `{package}` to version **{version}** to address known security vulnerability ({CVE-YYYY-NNNNN}). +* {Security fix description with version numbers and CVE references}. +* {Additional security fixes}. #### Bug fix * {Bug fix description}. +* {Additional bug fixes}. ``` -- Sections use H4 (`####`). Order: Security fix → Bug fix → Feature. -- Package names in backticks, version numbers in **bold**. -- Include CVE/GHSA references where applicable (CVE-YYYY-NNNNN or GHSA-XXXX-XXXX-XXXX). -- Keywords are always `installed-collector` — no confirmation needed. +**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}." +* Use H4 (`####`) for section headings: Security fix, Bug fix, Feature +* 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 ---- +**Example:** +```markdown +In this release, we've enhanced the security and stability of the Collector with added support for security patches. -#### OpenTelemetry Collector +#### Security fix -**Frontmatter**: -```yaml ---- -title: {Feature Name} -image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 -hide_table_of_contents: true -keywords: - - opentelemetry-collector ---- +* Upgraded `io.netty:netty-codec-http` to version **4.1.129.Final** to address known security vulnerability (CVE-2025-67735). +* Upgraded `com.fasterxml.jackson.core` packages to use patched version **2.18.6** to address known security vulnerability (GHSA-72hv-8253-57qq). + +#### Bug fix + +* Fixed an issue with forwarded Windows event collection that occurred on systems running with latest Windows version. +``` + +#### OpenTelemetry Release Structure + +```markdown +We're excited to {announce/introduce} {feature description}. {What it does and benefits}. [Learn more](/docs/path/to/doc). + +{Optional: Additional paragraphs with more details} + +{Optional: Related documentation list} + +{Optional: Important notes in admonition} ``` -**Content**: +**OpenTelemetry Guidelines:** +* Start with "We're excited to announce..." or "We're excited to introduce...". +* Write 2-3 sentences in first paragraph. +* Focus on user benefits and business value. +* End first paragraph with "Learn more" link. +* 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):** ```markdown import useBaseUrl from '@docusaurus/useBaseUrl'; -We're excited to announce {feature description}. {Benefits}. [Learn more](/docs/path/to/doc). +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/). ``` -- Start with "We're excited to announce..." or "We're excited to introduce..." -- Keywords are always `opentelemetry-collector` — no confirmation needed. -- Use admonitions for important notes or breaking changes. +**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. + +Refer to the following documentation to view the updated URLs in the UI. +* [Ansible](/docs/send-data/opentelemetry-collector/install-collector/ansible/). +* [Chef](/docs/send-data/opentelemetry-collector/install-collector/chef/). +* [Puppet](/docs/send-data/opentelemetry-collector/install-collector/puppet/). + +:::note +* Existing OpenTelemetry binaries and other packages remain in their current locations. +* This change does not affect the UI itself. The download process looks the same, but the underlying URL now uses a CDN to improve reliability and speed. +::: +``` + +### Step 6: Validation checklist + +Before finishing, verify: +* [ ] File created in `/blog-collector/` directory. +* [ ] Filename follows pattern: `YYYY-MM-DD-{type}.md` +* [ ] Frontmatter complete with all required fields. +* [ ] Title format correct (version number or feature name). +* [ ] `hide_table_of_contents: true` present +* [ ] Keywords correct for type (installed-collector or opentelemetry). +* [ ] 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: "Learn more" link included with relative path +* [ ] No trailing whitespace. + +## Example usage + +### Installed Collector Example + +``` +User: "Create a Collector release note for version 19.535-8 with a security fix for Netty and a bug fix for Windows events" + +Claude: +1. Confirms type: Installed Collector +2. Confirms date: 2026-03-19 +3. Creates: blog-collector/2026-03-19-installed.md +4. Generates frontmatter: "Installed Collector Version 19.535-8" +5. Adds standard intro paragraph +6. Creates Security fix section with Netty upgrade +7. Creates Bug fix section with Windows events fix +8. Provides checklist +``` + +### OpenTelemetry Example + +``` +User: "Create an OTel Collector release note about new Kubernetes monitoring support" + +Claude: +1. Confirms type: OpenTelemetry +2. Confirms date: 2026-03-19 +3. Asks for description and doc link +4. Creates: blog-collector/2026-03-19-otel.md +5. Generates frontmatter: "Kubernetes Monitoring Support" +6. Writes announcement with feature benefits +7. Adds "Learn more" link +8. Provides checklist +``` + +## Version number format + +Installed Collector versions follow this pattern: +``` +Major.Minor.Patch-Build +``` + +Examples: +* `19.535-6` — Version 19.535, build 6. +* `19.535-4` — Version 19.535, build 4. +* `20.0-1` — Version 20.0, build 1. + +**Formatting in title:** +* Always include full version with build number. +* No spaces around hyphen. +* Example: "Installed Collector Version 19.535-6" + +## Dependency upgrade format + +When listing upgraded dependencies: +* Use backticks for package names. +* Use **bold** for version numbers. +* Include full CVE or GHSA reference if applicable. + +**Examples:** +* ✅ `io.netty:netty-codec-http` to version **4.1.129.Final** to address known security vulnerability (CVE-2025-67735) +* ✅ `com.fasterxml.jackson.core` packages to use patched version **2.18.6** (GHSA-72hv-8253-57qq). +* ✅ Collector JRE to **Amazon Corretto Version 17.0.18.8.1**. +* ❌ Upgraded netty-codec-http to 4.1.129.Final (missing backticks and bold). + +## Safety principles + +* **Check existing files** before creating to avoid duplicates. +* **Validate version numbers** follow the correct format. +* **Verify CVE/GHSA references** are accurate. +* **Use consistent formatting** for dependencies and versions. +* **Keep installed releases brief**. Just the facts. +* **Focus OTel releases on benefits** not technical details. + +## Post-completion message + +After successfully creating the release note, tell the user: + +**For Installed Collector:** +``` +✅ Installed Collector release note created successfully! + +File created: +* 📄 blog-collector/{date}-installed.md. + +Summary: +* Version: {version} +* Security fixes: {count} +* Bug fixes: {count} + +Next steps: +1. Review CVE/GHSA references for accuracy +2. Verify version numbers are correct +3. Ensure all fixes are documented +4. Test locally: yarn start +5. Check preview at: http://localhost:3000/release-notes-collector +6. Submit PR: "DOCS-XXX - Installed Collector {version} release notes" + +Checklist: +* [ ] Version number is correct. +* [ ] All security vulnerabilities referenced. +* [ ] Dependencies use backticks and bold versions. +* [ ] Bug fixes are complete. + +The release note will appear on the Collector release notes page in reverse chronological order (newest first). +``` + +**For OpenTelemetry:** +``` +✅ OpenTelemetry Collector release note created successfully! + +File created: +* 📄 blog-collector/{date}-otel.md. + +Summary: +* Feature: {Feature Name} +* Keywords: opentelemetry + +Next steps: +1. Review content for accuracy and clarity +2. Verify documentation link is correct +3. Ensure feature name and description are clear +4. Test locally: yarn start +5. Check preview at: http://localhost:3000/release-notes-collector +6. Submit PR: "DOCS-XXX - OTel Collector: {Feature Name}" + +Checklist: +* [ ] Feature name is clear and concise. +* [ ] Description focuses on user benefits. +* [ ] Documentation link is correct. +* [ ] No placeholder text remaining. + +The release note will appear on the Collector release notes page in reverse chronological order (newest first). + +Would you like me to help refine the description or add additional details? +``` + +## Error handling + +**If file already exists:** +* Show existing file content. +* Ask if user wants to: + * Use different type (installed vs otel). + * Use different date. + * Overwrite (requires confirmation). + +**If version number format is invalid:** +* Show expected format: X.Y.Z-N +* Ask for correction. + +**If CVE/GHSA reference looks incomplete:** +* Warn about format. +* Ask for confirmation. + +**If documentation link looks wrong (OTel):** +* Warn if does not start with `/docs/`. +* Suggest correction. + +## Tips and best practices + +**Installed Collector releases:** +* Be specific about what was fixed or upgraded. +* Include exact version numbers. +* Reference CVEs and GHSAs when applicable. +* Keep descriptions factual and brief. +* Order matters: Security → Bugs → Features + +**OpenTelemetry releases:** +* Lead with user benefit. +* Explain why the change matters. +* Link to comprehensive documentation. +* Use admonitions for breaking changes or important notes. -### Step 4: Validate +**Both types:** +* Use consistent formatting throughout. +* Keep language simple and direct. +* Avoid unnecessary technical jargon. +* Focus on what changed, not how it was implemented. -**Installed Collector:** -- [ ] `blog-collector/YYYY-MM-DD-installed.md` -- [ ] Title: "Installed Collector Version X.Y.Z-N" -- [ ] H4 sections in correct order (Security → Bug → Feature) -- [ ] Versions in **bold**, packages in backticks -- [ ] CVE/GHSA references where applicable +## References -**OpenTelemetry Collector:** -- [ ] `blog-collector/YYYY-MM-DD-otel.md` -- [ ] Starts with "We're excited to..." -- [ ] "Learn more" link with relative path -- [ ] Keywords: `opentelemetry-collector` +* [Collector Release Notes](https://sumologic.com/help/release-notes-collector) +* [Release Notes Index](/docs/release-notes). +* [Style Guide](/docs/contributing/style-guide). diff --git a/.claude/commands/release-note-cse.md b/.claude/commands/release-note-cse.md index bbb7238631..41e36c6c66 100644 --- a/.claude/commands/release-note-cse.md +++ b/.claude/commands/release-note-cse.md @@ -1,60 +1,145 @@ # Create New Cloud SIEM Release Note -Creates a Cloud SIEM (CSE) release note — either a content release (rules, log mappers, parsers) or an application release (features, bug fixes, UI updates). +Automates the creation of Cloud SIEM (CSE) release notes with proper formatting, frontmatter, and structure. + +## What this command does + +When you invoke `release-note-cse`, Claude will guide you through: + +1. **Determine release type**. Content release or Application release +2. **Gather release details**. Date, changes, features, bug fixes +3. **Create markdown file**. Generate file with proper frontmatter and structure +4. **Format content**. Apply correct formatting for rules, mappers, parsers, or features +5. **Validate and preview**. Check structure and provide next steps + +## When to use this command + +* Publishing Cloud SIEM content updates (rules, log mappers, parsers). +* Announcing new Cloud SIEM features or bug fixes. +* Creating regular bi-weekly or monthly CSE release notes. +* Documenting Cloud SIEM application updates. + +## Release types + +### Content Release (`-content.md`) + +For updates to Cloud SIEM detection content: +* **Rules**: New or updated detection rules +* **Log Mappers**: New or updated log mapping configurations +* **Parsers**: Parser updates and enhancements +* **Schema changes**: New fields or tags + +**Typical cadence**: Every 1-2 weeks + +### Application Release (`-application.md`) + +For Cloud SIEM product features and updates: +* **New features**: UI improvements, new capabilities +* **Bug fixes**: Issue resolutions +* **Performance improvements**: Optimizations +* **Breaking changes or deprecations**. + +**Typical cadence**: As needed when features ship ## Workflow -### Step 1: Determine release type +### Step 1: Gather information + +Ask the user for: -Ask the user: **Content release** (rules, log mappers, parsers — typically bi-weekly) or **Application release** (new features, bug fixes, UI improvements)? +**Required:** +* **Release type**: Content or Application +* **Release date**: Date in YYYY-MM-DD format +* **Changes**: List of what's included -### Step 2: Gather information +**For Content Releases:** +* New/updated rules (rule IDs and names). +* New/updated log mappers. +* New/updated parsers. +* Brief summary of changes. -**For content releases:** -- Release date (YYYY-MM-DD) -- New/updated rules (IDs and names) — do not invent rule IDs, ask the user -- New/updated log mappers -- New/updated parsers -- 3–5 high-level summary points -- Keywords (confirm with user; default: rules, log mappers, parsers) +**For Application Releases:** +* Feature name and description. +* Documentation links. +* Screenshots (if applicable). +* Any breaking changes. -**For application releases:** -- Release date (YYYY-MM-DD) -- Features with descriptions and doc links -- Keywords (confirm with user) +**Keywords (for both types):** +* Ask user to confirm or customize keywords +* Suggest defaults based on release type (see frontmatter section below) -### Step 3: Create the file +**Validate:** +* Check that date is not in the future (use today's date if not specified). +* Ensure file does not already exist for this date and type. +* Confirm changes are ready to publish. +* Confirm keywords with user before creating file. -**File**: `blog-cse/YYYY-MM-DD-{type}.md` — type is `-content` or `-application` +### Step 2: Create the markdown file -Always include `import useBaseUrl from '@docusaurus/useBaseUrl';` after frontmatter. +**File naming convention:** +``` +blog-cse/YYYY-MM-DD-{type}.md +``` -If a file already exists for the same date and type, ask the user to use a different date or append. +Examples: +* `blog-cse/2026-03-19-content.md`. +* `blog-cse/2026-03-19-application.md`. ---- +**Important**: Files are created in `/blog-cse/` directory, NOT in `/docs/` -#### Content release +### Step 3: Generate frontmatter -**Frontmatter**: +**For Content Releases:** ```yaml --- -title: {Month} {Day ordinal}, {Year} - Content Release +title: {Month} {Day}th, {Year} - Content Release hide_table_of_contents: true keywords: - - rules - - log mappers - - parsers + * rules + * log mappers + * parsers image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 --- ``` -Title uses ordinal suffix: "March 19th, 2026 - Content Release", "February 3rd, 2026 - Content Release". Full month name, not abbreviated. +**For Application Releases:** +```yaml +--- +title: {Month} {Day}, {Year} - Application Update +image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 +keywords: + * {relevant-keyword} +hide_table_of_contents: true +--- +``` + +**Keywords guidance:** +* **Always ask user to confirm keywords before creating file** +* Suggested defaults: + * Content releases: `rules`, `log mappers`, `parsers` + * 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. + +### Step 4: Add required import + +Always include after frontmatter: +```javascript +import useBaseUrl from '@docusaurus/useBaseUrl'; +``` + +### Step 5: Write content + +#### Content Release Structure -**Content**: ```markdown This content release includes: - - {Summary point 1} - - {Summary point 2} + - {High-level summary point 1} + - {High-level summary point 2} + - {High-level summary point 3} Additional changes are enumerated below. @@ -64,48 +149,271 @@ Additional changes are enumerated below. ### Log Mappers * [New] Vendor - Event Type. +* [Updated] Vendor - Event Type. ### Parsers * [Updated] /Parsers/System/Vendor/Parser Name. ``` -- Summary bullets use 4-space indentation. -- `[New]` or `[Updated]` tag on every item. -- Rule ID formats: `MATCH-SXXXX`, `FIRST-SXXXX`, `THRESHOLD-SXXXX`, `AGGREGATION-SXXXX`, `CHAIN-SXXXX`, `OUTLIER-SXXXX` -- Parser paths use full hierarchy: `/Parsers/System/Vendor/Name` -- Log mapper format: `Vendor - Event Type` -- Sort alphabetically within each section. +**Content Release Guidelines:** +* Start with bulleted summary (3-5 high-level points). +* Use indentation (4 spaces) for bullet points. +* Group changes by type: Rules, Log Mappers, Parsers +* Use `[New]` or `[Updated]` tags. +* Rule IDs use format: `MATCH-SXXXX`, `FIRST-SXXXX`, `THRESHOLD-SXXXX` +* Parser paths use full hierarchy: `/Parsers/System/Vendor/Name` +* Add brief explanations for significant updates. +* Sort items alphabetically within each section. ---- +#### Application Release Structure -#### Application release +```markdown +### {Feature Name} -**Frontmatter**: -```yaml +{Feature description and business value}. [Learn more](/docs/path/to/docs). + +{Optional screenshot or additional details} +``` + +**Application Release Guidelines:** +* Use H3 (`###`) for each feature. +* Start with clear, concise description. +* 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. + +### 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" + +Examples: +* ✅ "March 19th, 2026 - Content Release". +* ✅ "February 3rd, 2026 - Application Update". +* ❌ "Mar 19, 2026 - Content Release" (month abbreviated). +* ❌ "March 19 2026 - Content Release" (missing "th"). + +### Step 7: Validation checklist + +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. +* [ ] `hide_table_of_contents: true` present +* [ ] Keywords appropriate for release type. +* [ ] `import useBaseUrl` statement included. +* [ ] Content follows proper structure (Rules → Log Mappers → Parsers). +* [ ] All `[New]` and `[Updated]` tags present. +* [ ] Parser paths use full `/Parsers/System/Vendor/Name` format. +* [ ] Links use relative paths or `useBaseUrl`. +* [ ] No trailing whitespace or extra blank lines. + +## Example usage + +### Content Release Example + +``` +User: "Create a CSE content release for today with updates to AWS CloudTrail rules and new Okta log mappers" + +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" +5. Adds summary section +6. Creates sections for Rules and Log Mappers +7. Formats with proper [New]/[Updated] tags +8. Provides checklist and next steps +``` + +### Application Release Example + +``` +User: "Create a CSE application release for March 15th about the new bulk insight update feature" + +Claude: +1. Confirms date: 2026-03-15 +2. Confirms type: Application Release +3. Creates: blog-cse/2026-03-15-application.md +4. Generates frontmatter: "March 15, 2026 - Application Update" +5. Adds feature section with H3 heading +6. Includes description and Learn more link +7. Provides checklist +``` + +## Common patterns + +### Rule ID formats + +* `MATCH-SXXXX` — Match rules (most common). +* `FIRST-SXXXX` — First Seen rules. +* `THRESHOLD-SXXXX` — Threshold rules. +* `AGGREGATION-SXXXX` — Aggregation rules. +* `CHAIN-SXXXX` — Chain rules. +* `OUTLIER-SXXXX` — Outlier rules. + +### Parser path structure + +Always use full path: +``` +/Parsers/System/{Vendor}/{Parser Name} +``` + +Examples: +* `/Parsers/System/AWS/AWS CloudTrail`. +* `/Parsers/System/Okta/Okta`. +* `/Parsers/System/Microsoft/Microsoft 365`. +* `/Parsers/System/Cisco/Cisco ASA`. + +### Log Mapper naming + +Format: `{Vendor} - {Event Type}` + +Examples: +* `Okta - Authentication Events`. +* `AWS CloudTrail - Management Events`. +* `Microsoft 365 - Audit Logs`. +* `CrowdStrike Falcon - Detection Events`. + +### Vendor consistency + +Use standard vendor names: +* ✅ "Microsoft 365" (not "Office 365", "O365"). +* ✅ "Google Workspace" (not "G Suite", "GSuite"). +* ✅ "SonicWall Firewall" (not "Dell SonicWall"). +* ✅ "AWS CloudTrail" (not "Amazon CloudTrail"). + +## Archive process + +**When to archive:** +* At year-end, older releases move to archive files. +* Archive files are in `/blog-cse/{YEAR}/12-31.md`. +* Current year + 1-2 prior years remain active. +* Older years are archived. + +**Archive structure:** +```markdown --- -title: {Month} {Day}, {Year} - Application Update +title: {Year} Release Notes Archive - Cloud SIEM +keywords: [rules, signals, schema, log mappers, parsers, cloud siem] image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 -keywords: - - {keyword} -hide_table_of_contents: true +--- + +import useBaseUrl from '@docusaurus/useBaseUrl'; + +This is an archive of {Year} Cloud SIEM release notes. [View the full archive](/release-notes-cse/archive). + + + +--- + +### {Month} {Day}, {Year} - {Type} + +{Content} + --- ``` -**Content**: -```markdown -### {Feature Name} +**Note:** Users typically do not need to manage archives manually. Mention this only if they ask about archiving old releases. + +## Safety principles + +* **Check existing files** before creating to avoid duplicates. +* **Validate dates** are not in the future. +* **Use consistent vendor names** (check existing releases for precedent). +* **Preserve exact rule IDs** when user provides them. +* **Do not invent rule IDs**. Ask user if not provided. +* **Link to docs** when mentioning features. + +## Post-completion message + +After successfully creating the release note, tell the user: + +``` +✅ Cloud SIEM release note created successfully! -{Description and business value}. [Learn more](/docs/path/to/docs). +File created: +* 📄 blog-cse/{date}-{type}.md. + +Summary: +* Type: {Content Release | Application Update} +* Date: {formatted date} +* Changes: {count} rules, {count} log mappers, {count} parsers + +Next steps: +1. Review content for accuracy +2. Add any missing details or descriptions +3. Verify all rule IDs and parser paths are correct +4. Add screenshots for application updates (if applicable) +5. Test locally: yarn start +6. Check preview at: http://localhost:3000/release-notes-cse +7. Submit PR: "DOCS-XXX - CSE {type} release notes for {date}" + +Checklist: +* [ ] All rule IDs verified. +* [ ] Parser paths use full /Parsers/System/ format. +* [ ] Vendor names consistent with existing releases. +* [ ] Links tested and working. +* [ ] No placeholder text remaining. + +The release note will appear on the Cloud SIEM release notes page in reverse chronological order (newest first). + +Would you like me to help fill in any additional details? ``` -H3 for each feature. Add screenshots with `description` for UI changes. +## Error handling + +**If file already exists:** +* Show existing file path and date. +* Ask if user wants to: + * Add to existing release (append content). + * Create with different date. + * Overwrite (requires confirmation). + +**If date is invalid:** +* Show error and ask for correct format (YYYY-MM-DD). +* Suggest today's date as default. + +**If rule IDs do not match pattern:** +* Warn user about non-standard format. +* Ask for confirmation before proceeding. + +**If vendor names are inconsistent:** +* Check recent releases for the vendor. +* Suggest standard name. +* Ask user to confirm. + +## Tips and best practices + +**Content releases:** +* Lead with most significant changes in summary. +* Group related changes together (e.g., all Okta updates). +* Include context for major updates ("Updated detection expression for improved query performance"). +* Keep descriptions concise (one sentence per update). + +**Application releases:** +* Lead with user benefit, not technical details. +* Always link to documentation. +* Use screenshots for UI changes. +* Mention if feature requires admin privileges. + +**General:** +* Be consistent with formatting across releases. +* Use active voice ("Added support for.." not "Support was added.."). +* Spell out acronyms on first use in each release. +* Keep release notes focused on what changed, not why. -### Step 4: Validate +## References -- [ ] `blog-cse/YYYY-MM-DD-{type}.md` -- [ ] Title uses ordinal suffix for content releases -- [ ] `import useBaseUrl` included -- [ ] `hide_table_of_contents: true` -- [ ] Content: `[New]`/`[Updated]` tags on all items; parser paths complete -- [ ] Keywords confirmed with user -- [ ] No trailing whitespace +* [Cloud SIEM Release Notes](https://sumologic.com/help/release-notes-cse) +* [Release Notes Index](/docs/release-notes). +* [Style Guide](/docs/contributing/style-guide). diff --git a/.claude/commands/release-note-csoar.md b/.claude/commands/release-note-csoar.md index 9c0ff2bc39..ebe2508bbd 100644 --- a/.claude/commands/release-note-csoar.md +++ b/.claude/commands/release-note-csoar.md @@ -1,49 +1,137 @@ # Create New Cloud SOAR Release Note -Creates a Cloud SOAR (Automation Service) release note — either a content release (new integrations and playbooks) or an application update (platform features, enhancements, bug fixes). +Automates the creation of Cloud SOAR (Automation Service) release notes for platform updates, integration changes, and bug fixes. + +## What this command does + +When you invoke `release-note-csoar`, Claude will guide you through: + +1. **Determine release type**. Content Release or Application Update +2. **Gather release details**. Date, changes, integrations, playbooks, or platform updates +3. **Create markdown file**. Generate file with proper frontmatter and structure +4. **Format content**. Apply correct formatting for the release type +5. **Validate and preview**. Check structure and provide next steps + +## When to use this command + +* Publishing new integrations and playbooks (Content Release) +* Publishing Cloud SOAR platform updates (Application Update) +* Documenting integration updates or bug fixes +* Announcing new API endpoints or features +* Releasing playbook improvements + +## Release types + +### Content Release (`-content-release.md`) + +For releases focused on new content (integrations and playbooks): +* **New integrations**: Brand new integrations added to App Central +* **Updated integrations**: Improvements to existing integrations +* **New playbooks**: New playbooks with ID numbers and titles +* **Simple format**: Just lists of what's new/updated, minimal descriptions + +**Typical cadence**: Monthly or as content batches are released + +### Application Update (`-application-update.md`) + +For platform features, enhancements, and bug fixes: +* **Platform features**: New capabilities, UX improvements, APIs +* **Integration changes**: With detailed descriptions of what changed +* **Bug fixes**: Issues resolved in integrations, platform, or playbooks +* **Detailed format**: Sections with descriptions and context + +**Typical cadence**: Monthly, published early the following month + +## Release structure (varies by type) + +### Content Release Structure + +Simple format with just lists: + +1. **Intro paragraph** - Brief description of release +2. **Integrations** (H3) - Bulleted list of [New]/[Updated] integrations +3. **Playbooks** (H3) - Bulleted list of [New] playbooks with IDs and titles + +### Application Update Structure + +Detailed format with descriptions and bug fixes: + +1. **Release month header** (H2) - "## {Month} release" +2. **Changes and enhancements** (H3) + - **Integrations** (H4) - New or updated integrations with descriptions + - **Platform** (H4) - Platform features and improvements + - **Playbooks** (H4) - Playbook-related changes (optional) +3. **Bug Fixes** (H3) + - **Integrations** (H4) - Integration bug fixes + - **Platform** (H4) - Platform bug fixes + - **Playbooks** (H4) - Playbook bug fixes ## Workflow ### Step 1: Determine release type -Ask the user: **Content release** (new/updated integrations and playbooks) or **Application update** (platform features, enhancements, bug fixes — published early the following month)? +Ask the user which type of release: + +**Content Release** - For new integrations and playbooks +* Simple list format +* No detailed descriptions +* No bug fixes section +* Use when: Releasing batch of new content + +**Application Update** - For platform features and bug fixes +* Detailed descriptions +* Bug fixes section +* Organized by month +* Use when: Monthly platform updates ### Step 2: Gather information -**For content releases:** -- Publication date (YYYY-MM-DD) -- New/updated integrations (names and doc links) -- New playbooks (ID numbers and titles) -- Keywords (confirm with user; default: automation service, cloud soar, soar) +**For Content Release:** +* **Publication date**: Date in YYYY-MM-DD format +* **New integrations**: List of integrations to add +* **Updated integrations**: List of integrations to update +* **New playbooks**: List with ID numbers and titles (if any) -**For application updates:** -- Publication date (YYYY-MM-DD) — typically early the month following the release month -- Release month (e.g. "February" if published in March) -- Integration changes with descriptions -- Platform changes -- Bug fixes -- Keywords (confirm with user; default: automation service, cloud soar) +**For Application Update:** +* **Release month**: Which month is this release for? (e.g., "February") +* **Publication date**: Date in YYYY-MM-DD format (typically early next month) +* **Integration changes**: New or updated integrations with descriptions +* **Platform changes**: Platform features and improvements +* **Bug fixes**: List of bugs fixed -### Step 3: Create the file +**Keywords (for both types):** +* Ask user to confirm or customize keywords +* Suggested defaults (see frontmatter section below) -**File**: -- Content release: `blog-csoar/YYYY-MM-DD-content-release.md` -- Application update: `blog-csoar/YYYY-MM-DD-application-update.md` +**Validate:** +* Check that date is not in the future +* For Application Update: Ensure release month aligns with publication date +* Verify integration links are valid +* Confirm keywords with user before creating file -Always include `import useBaseUrl from '@docusaurus/useBaseUrl';` after frontmatter. +### Step 3: Create the markdown file -**Date format in title**: "Month DD, YYYY" — full month name, zero-padded day, no ordinal. -- ✅ "March 06, 2026" | ❌ "March 6, 2026" | ❌ "March 6th, 2026" +**File naming convention:** -**Integration doc path**: `/docs/platform-services/automation-service/app-central/integrations/{slug}/` +For Content Release: +``` +blog-csoar/YYYY-MM-DD-content-release.md +``` -If a file already exists, ask the user to use a different date or append. +For Application Update: +``` +blog-csoar/YYYY-MM-DD-application-update.md +``` ---- +Examples: +* `blog-csoar/2024-06-05-content-release.md` +* `blog-csoar/2026-03-06-application-update.md` + +**Important**: Files are created in `/blog-csoar/` directory (root level) -#### Content release +### Step 4: Generate frontmatter -**Frontmatter**: +**For Content Release:** ```yaml --- title: {Month DD, YYYY} - Content Release @@ -56,43 +144,87 @@ keywords: --- ``` -**Content**: -```markdown -This release introduces {what's new}. +**For Application Update:** +```yaml +--- +title: {Month DD, 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: + - automation service + - cloud soar +--- +``` -### Integrations +**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" -* [New] [Integration Name](/docs/platform-services/automation-service/app-central/integrations/{slug}/) -* [Updated] [Integration Name](/docs/platform-services/automation-service/app-central/integrations/{slug}/) +**Date formatting:** +* Use full month name (January, February, March, etc.) +* Use zero-padded day (01, 05, 06, 08, not 1, 5, 6, 8) -### Playbooks +**Keywords:** +* **Always ask user to confirm keywords before creating file** +* Suggested defaults: + * Content Release: `automation service`, `cloud soar`, `soar` (three keywords) + * Application Update: `automation service`, `cloud soar` (two keywords) +* User may want to add additional keywords based on specific content (e.g., `integrations`, `playbooks`, `api`, `platform`) + +**Image:** +* Both types use the same standard Sumo Logic preview image: + * `https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082` -* [New] {ID} - {Playbook Title} +### Step 5: Add required import + +**For both types**, add the useBaseUrl import after frontmatter: +```javascript +import useBaseUrl from '@docusaurus/useBaseUrl'; ``` -Integration entries are link-only — no descriptions. Playbooks section is optional. +### Step 6: Write content structure +**Content Release template:** +```markdown +--- +title: June 05, 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: + - automation service + - cloud soar + - soar --- -#### Application update +import useBaseUrl from '@docusaurus/useBaseUrl'; -Application Updates cover the previous month's changes. Filename and title use the publication date; the H2 header and intro use the release month. +This release introduces new integrations, new playbooks, and several updates. -**Frontmatter**: -```yaml +### Integrations + +* [New] [AWS WAF](/docs/platform-services/automation-service/app-central/integrations/aws-waf) +* [Updated] [Okta](/docs/platform-services/automation-service/app-central/integrations/okta) + +### Playbooks + +* [New] 541 - Management of AWS EKS Insights +* [New] 542 - Resolution of AWS EKS Insights +``` + +**Application Update template:** +```markdown --- -title: {Month DD, YYYY} - Application Update +title: March 06, 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: - automation service - cloud soar --- -``` -**Content**: -```markdown -## {Release month} release +import useBaseUrl from '@docusaurus/useBaseUrl'; + +## {Month} release Following are the updates made in {Month} {YYYY}. @@ -100,32 +232,374 @@ Following are the updates made in {Month} {YYYY}. #### Integrations -* [Added] [Integration Name](/docs/path/) - Description of what was added. -* [Updated] [Integration Name](/docs/path/) - Description of what was updated. +* [Added] [Integration Name](/docs/path/to/integration/) - Description of what was added. +* [Updated] [Integration Name](/docs/path/to/integration/) - Description of what was updated. + +#### Platform + +* Description of platform enhancement or feature. +* Description of another platform change. + +### Bug Fixes + +#### Integrations + +* In the [Integration Name](/docs/path/to/integration/) integration, description of bug fix. #### Platform -* Platform enhancement description. +Fixed an issue where [description of bug and fix]. +``` + +### Step 7: Content formatting guidelines + +## Content Release Formatting + +#### Intro Paragraph + +* Simple one-sentence description +* Format: "This release introduces {what's new}." +* Examples: + * "This release introduces new integrations, new playbooks, and several updates." + * "This release introduces new integrations and updates to existing integrations." + +#### Integrations Section (H3) + +* Simple bulleted list with [New] or [Updated] tags +* Format: `* [Tag] [Integration Name](link)` +* NO descriptions needed - just link to integration doc +* Links use full path: `/docs/platform-services/automation-service/app-central/integrations/{slug}` + +**Example:** +```markdown +### Integrations + +* [New] [AWS WAF](/docs/platform-services/automation-service/app-central/integrations/aws-waf) +* [New] [Cyberint](/docs/platform-services/automation-service/app-central/integrations/cyberint) +* [Updated] [Okta](/docs/platform-services/automation-service/app-central/integrations/okta) +* [Updated] [ServiceNow V2](/docs/platform-services/automation-service/app-central/integrations/servicenow-v2) +``` + +#### Playbooks Section (H3) + +* Optional - only if new playbooks released +* Format: `* [New] {ID} - {Playbook Title}` +* ID is a number (e.g., 541, 542, 543) +* Use "- " between ID and title + +**Example:** +```markdown +### Playbooks + +* [New] 541 - Management of AWS EKS Insights +* [New] 542 - Resolution of AWS EKS Insights +* [New] 543 - Alert and Vulnerability detection with Sysdig Secure +``` + +## Application Update Formatting + +#### Release Month Header (H2) + +* Always use H2 (`##`) for the month +* Format: "## {Month} release" +* Examples: "## February release", "## March release" +* Followed by: "Following are the updates made in {Month} {YYYY}." + +#### Changes and Enhancements Section + +**Integrations subsection:** +* Use tags: `[Added]` for new integrations, `[Updated]` for existing ones +* Format: `[Tag] [Integration Name](link) - Description.` +* Link to integration documentation in `/docs/platform-services/automation-service/app-central/integrations/` +* Be specific about what action or feature was added/updated +* Can mention specific actions: "Added 'Count Occurrence Of Value' action" + +**Example:** +```markdown +#### Integrations + +* [Added] [Sumo Logic Automation Tools](/docs/platform-services/automation-service/app-central/integrations/sumo-logic-automation-tools/) - Added "Count Occurrence Of Value" action to count the occurrence of a specified value in texts. +* [Updated] [ThreatConnect V3](/docs/platform-services/automation-service/app-central/integrations/threatconnect-v3/) - Added observations parameter to the Update Intelligence action to enable recording observation counts for indicators. +``` + +**Platform subsection:** +* List platform-wide changes or features +* Focus on user-facing improvements +* Can include UX enhancements, new APIs, or system improvements +* Use clear, simple language + +**Example:** +```markdown +#### Platform + +* Improved the sorting UX experience on all tables in Cloud SOAR and the Automation Service to align with other Sumo Logic modules. +* Deleted records will no longer be fetched during table searches unless the `Deleted` filter is applied. +* Added new public APIs: + * [Add playbooks to an incident](https://api.sumologic.com/docs/csoar/#operation/incidents_runbook_create). + * [Retrieve all playbooks attached to a specific incident](https://api.sumologic.com/docs/csoar/#operation/incidents_runbook_retrieve). +``` + +**Playbooks subsection (optional):** +* Only include if there are playbook-specific changes +* Format similar to platform changes +#### Bug Fixes Section + +* Group by subsection: Integrations, Platform, Playbooks +* For integrations: Start with "In the [Integration Name](link) integration, ..." +* For platform/playbooks: Use "Fixed an issue where..." or direct description +* Be specific about what was fixed + +**Example:** +```markdown ### Bug Fixes #### Integrations -* In the [Integration Name](/docs/path/) integration, description of fix. +* In the [Microsoft EWS (Graph)](/docs/platform-services/automation-service/app-central/integrations/microsoft-ews-graph/) integration, removed the default values for the `has_attachments` and `un_read` fields in the Search Emails Extended action. The change allows users to search for emails without being forced to filter by attachment status or read/unread status. #### Platform -Fixed an issue where {description}. +Fixed an issue where query filters were being applied incorrectly during search. + +#### Playbooks + +Fixed issues while selecting variables containing the period character in textarea fields and test node input. +``` + +### Step 8: Validation checklist + +**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") +* [ ] Image URL: Standard Sumo Logic preview image +* [ ] Keywords: automation service, cloud soar, soar (three keywords) +* [ ] `hide_table_of_contents: true` is present +* [ ] Import statement included +* [ ] Simple intro paragraph present +* [ ] Integrations section uses [New]/[Updated] tags +* [ ] Integration links have NO descriptions (just links) +* [ ] Playbooks section uses [New] with ID numbers (if included) +* [ ] No trailing whitespace + +**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") +* [ ] Image URL: Standard Sumo Logic preview image +* [ ] Keywords: automation service, cloud soar (two keywords) +* [ ] `hide_table_of_contents: true` is present +* [ ] Import statement included +* [ ] H2 header: "## {Month} release" +* [ ] Intro: "Following are the updates made in {Month} {YYYY}." +* [ ] Integration changes use [Added]/[Updated] WITH descriptions +* [ ] Integration links point to correct paths +* [ ] All sections properly formatted (H3 for main, H4 for subsections) +* [ ] No trailing whitespace + +## Example usage + +### Content Release Example + +``` +User: "Create a Cloud SOAR content release for June 5, 2024, with new AWS integrations and playbooks" + +Claude: +1. Confirms type: Content Release +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" + - image: Standard Sumo Logic preview image + - keywords: automation service, cloud soar, soar +5. Writes content with: + - Simple intro: "This release introduces new integrations, new playbooks, and several updates." + - Integrations section with [New]/[Updated] tags (no descriptions) + - Playbooks section with ID numbers +6. Provides checklist +``` + +### Application Update Example + ``` +User: "Create a Cloud SOAR release note for February 2026, published March 6, with integration updates and bug fixes" + +Claude: +1. Confirms type: Application Update +2. Confirms publication date: March 6, 2026 +3. Confirms release month: February +4. Creates: blog-csoar/2026-03-06-application-update.md +5. Generates frontmatter: + - title: "March 06, 2026 - Application Update" + - keywords: automation service, cloud soar +6. Writes content with: + - H2: "## February release" + - Intro: "Following are the updates made in February 2026." + - Changes and enhancements section (with descriptions) + - Bug fixes section +7. Provides checklist +``` + +## Integration documentation paths + +Integration docs are located at: +``` +/docs/platform-services/automation-service/app-central/integrations/{integration-slug}/ +``` + +**Common integrations:** +* Microsoft EWS (Graph): `/docs/platform-services/automation-service/app-central/integrations/microsoft-ews-graph/` +* ThreatConnect V3: `/docs/platform-services/automation-service/app-central/integrations/threatconnect-v3/` +* Atlassian Opsgenie: `/docs/platform-services/automation-service/app-central/integrations/atlassian-opsgenie/` +* Sumo Logic Automation Tools: `/docs/platform-services/automation-service/app-central/integrations/sumo-logic-automation-tools/` -Integration changes use `[Added]` for new integrations, `[Updated]` for existing — always include descriptions (unlike content releases). +**Tip**: Integration slugs are lowercase with hyphens. If unsure, use Grep to find the integration doc. -### Step 4: Validate +## API documentation links + +Cloud SOAR API docs: +* API reference: `https://api.sumologic.com/docs/csoar/` +* Cloud SOAR automation docs: `/docs/cloud-soar/automation/` + +## 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) + +**Examples:** +* ✅ March 06, 2026 +* ✅ January 08, 2026 +* ✅ December 31, 2025 +* ✅ June 05, 2024 +* ❌ March 6, 2026 (not zero-padded) +* ❌ March 6th, 2026 (has ordinal) +* ❌ Mar 06, 2026 (abbreviated month) +* ❌ 2026-03-06 (wrong format) + +## Release timing + +**Important**: Cloud SOAR release notes are typically published early the following month for the previous month's changes. + +**Pattern:** +* February changes → Published early March (e.g., March 6) +* January changes → Published early February +* December changes → Published early January + +**In the file:** +* Filename uses publication date: `2026-03-06-application-update.md` +* Title uses publication date: "March 6, 2026 - Application Update" +* H2 uses release month: "## February release" +* Intro uses release month: "Following are the updates made in February 2026." + +## Safety principles + +* **Check for existing files** before creating to avoid duplicates +* **Validate release month alignment** with publication date +* **Verify integration links** exist before including them +* **Use consistent formatting** for all integration changes +* **Include both keywords**. Automation service and cloud soar +* **Group bug fixes by category** for clarity +* **Keep descriptions concise** but informative + +## Post-completion message + +After successfully creating the release note, tell the user: + +``` +✅ Cloud SOAR release note created successfully! + +File created: +* 📄 blog-csoar/{YYYY-MM-DD}-application-update.md + +Summary: +* 📅 Publication: {Month Day, YYYY} +* 📆 Release month: {Month} +* 🔧 Integration updates: {count} +* 🐛 Bug fixes: {count} + +Next steps: +1. Review all integration links are correct +2. Verify bug fix descriptions are accurate +3. Ensure release month matches publication date +4. Test locally: yarn start +5. Check preview at: http://localhost:3000/release-notes-csoar +6. Submit PR: "DOCS-XXX - Cloud SOAR {Month} release notes" + +Checklist: +* [ ] Filename is {date}-application-update.md +* [ ] Title follows "Month Day, YYYY - Application Update" format +* [ ] H2 header is "## {Month} release" +* [ ] Integration changes use [Added]/[Updated] tags +* [ ] All integration links are valid +* [ ] Keywords include automation service and cloud soar +* [ ] Bug fixes grouped by category + +The release note will appear on the Cloud SOAR release notes page in reverse chronological order (newest first). + +Would you like me to help refine any sections or add additional details? +``` -- [ ] Filename uses full suffix (`-content-release.md` or `-application-update.md`) -- [ ] Title: "Month DD, YYYY" format (zero-padded, no ordinal) -- [ ] `import useBaseUrl` included -- [ ] `hide_table_of_contents: true` -- [ ] Keywords confirmed with user -- [ ] Application update: H2 header uses release month, not publication month -- [ ] No trailing whitespace +## Error handling + +**If file already exists:** +* Show existing file path and date +* Ask if user wants to: + * Update existing file (add more content) + * Use different date + * Create anyway (overwrite - requires confirmation) + +**If release month doesn't match date:** +* Warn user about mismatch +* Example: "March 6 publication should be for February release, not March" +* Ask for confirmation or correction + +**If integration link looks invalid:** +* Warn if doesn't follow standard path pattern +* Suggest searching for correct integration doc +* Proceed with user confirmation + +**If date is in the future:** +* Warn user and ask for confirmation +* Suggest using current date + +## Tips and best practices + +**For integration changes:** +* Be specific about what actions were added or updated +* Include the purpose or benefit of the change +* Always link to integration documentation +* Use [Added] for completely new integrations +* Use [Updated] for changes to existing integrations + +**For platform changes:** +* Focus on user-facing improvements +* Explain the benefit or impact +* Group related changes together +* Include API links when relevant + +**For bug fixes:** +* Clearly describe what was fixed +* Explain the previous behavior and new behavior +* Group by category for organization + +**All sections:** +* Keep language clear and concise +* Focus on what changed and why it matters +* Use bullet points for easy scanning +* Maintain consistent formatting + +## References + +* [Cloud SOAR Release Notes](https://sumologic.com/help/release-notes-csoar) +* [Cloud SOAR Documentation](/docs/cloud-soar) +* [Automation Service](/docs/platform-services/automation-service) +* [App Central Integrations](/docs/platform-services/automation-service/app-central/integrations) +* [Style Guide](/docs/contributing/style-guide) diff --git a/.claude/commands/release-note-developer.md b/.claude/commands/release-note-developer.md index 50913bc53f..8b11cce1d0 100644 --- a/.claude/commands/release-note-developer.md +++ b/.claude/commands/release-note-developer.md @@ -1,31 +1,84 @@ # Create New Developer Release Note -Creates a Developer release note for API changes, SDK updates, deprecations, CLI updates, or other developer-facing platform changes. +Automates the creation of Developer release notes for APIs, SDKs, integrations, and platform changes relevant to developers. + +## What this command does + +When you invoke `release-note-developer`, Claude will guide you through: + +1. **Gather release details**. Category, date, title, and content +2. **Create markdown file**. Generate file with proper frontmatter and structure +3. **Format content**. Apply correct formatting for the release type +4. **Validate and preview**. Check structure and provide next steps + +## When to use this command + +* Announcing new API endpoints or features +* Documenting API changes, deprecations, or breaking changes +* Publishing SDK updates or new SDK versions +* Releasing developer tools or CLI updates +* Announcing platform changes affecting developers +* Documenting authentication or integration changes +* Publishing deprecation notices + +## Release categories + +Developer release notes typically cover: + +* **APIs**. New endpoints, changes, deprecations +* **SDKs**. New SDKs, version updates, improvements +* **CLI**. Command-line tool updates +* **Integrations**. New integrations or integration changes +* **Platform**. Platform changes affecting developers +* **Security**. Authentication, authorization changes +* **Deprecations**. End-of-life announcements ## Workflow ### Step 1: Gather information Ask the user for: -- **Title/topic**: brief description (e.g. "New Field Extraction Rules API", "Deprecation of India Data Center") -- **Release date**: YYYY-MM-DD format -- **Content**: what changed, why it matters, impact on existing users -- **Doc links**: relative paths to relevant docs -- **Keywords**: optional; ask the user — suggest based on content type: - - API changes: `api`, `endpoints` - - SDK updates: `sdk`, `python`, `java`, etc. - - Deprecations: `deprecation`, `end-of-life` - - Breaking changes: `breaking-change` -### Step 2: Create the file +**Required:** +* **Title/Topic**: Brief description of what this release is about +* **Release date**: Date in YYYY-MM-DD format +* **Content**: The release note content (what changed, why it matters) -**File**: `blog-developer/YYYY-MM-DD-{slug}.md` +**Optional:** +* **Impact level**: Breaking change, deprecation, new feature, minor change +* **Documentation links**: Related doc pages +* **Slug**: Custom slug for filename (auto-generated from title if not provided) +* **Keywords**: Custom keywords for frontmatter (suggest defaults based on content) -Slug: lowercase, hyphens, 3–5 words. Examples: `api-endpoints`, `india-datacenter-deprecation`, `python-sdk-v2`. +**Validate:** +* Check that date is not in the future +* Ensure content is clear and concise +* Verify any doc links are valid relative paths +* Ask user to confirm keywords before creating file -If a file already exists, ask the user to use a different date or a more specific slug. +### Step 2: Create the markdown file -**Frontmatter**: +**File naming convention:** +``` +blog-developer/YYYY-MM-DD-{slug}.md +``` + +**Slug generation:** +* Lowercase the title +* Replace spaces with hyphens +* Remove special characters +* Keep concise (3-5 words max) + +Examples: +* `blog-developer/2026-03-23-api-endpoints.md` +* `blog-developer/2026-04-09-india-datacenter-deprecation.md` +* `blog-developer/2026-05-15-python-sdk-v2.md` + +**Important**: Files are created in `/blog-developer/` directory (root level, no subdirectories) + +### Step 3: Generate frontmatter + +**Standard frontmatter:** ```yaml --- title: {Month Day, YYYY} - {Topic} @@ -34,30 +87,418 @@ hide_table_of_contents: true --- ``` -**Title format**: "Month Day, YYYY - Topic" — full month name, no ordinal. -- ✅ "April 9, 2025" | ❌ "April 9th, 2025" | ❌ "Apr 9, 2025" +**Title formatting:** +* Start with full date: "Month Day, YYYY" (e.g., "April 9, 2025") +* Follow with " - " separator +* Add topic in Title Case (e.g., "Deprecation of Sumo Logic India Data Center") +* Keep topic concise but descriptive -Add `keywords` to frontmatter only if the user wants them. +**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" -**Content**: +**Image:** +* Always use the standard Sumo Logic preview image +* URL: `https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082` + +**Keywords (optional but recommended):** +* **Always ask user if they want to include keywords** +* Suggest keywords based on content type: + * API changes: `api`, `endpoints`, `rest-api` + * SDK updates: `sdk`, `python`, `java`, etc. + * Deprecations: `deprecation`, `end-of-life` + * Breaking changes: `breaking-change` + * Platform updates: `platform`, `datacenter` +* Format: + ```yaml + keywords: + - api + - deprecation + ``` +* User can choose to omit keywords or customize the list + +### Step 4: Add optional import + +For release notes that use links or useBaseUrl: +```javascript +import useBaseUrl from '@docusaurus/useBaseUrl'; +``` + +**Note**: Only add if content uses it. For simple text-only releases, omit. + +**Title guidelines:** +* Keep concise (2-5 words) +* Use title case +* Common patterns: "APIs", "SDKs", "CLI Tools", "Platform Updates" +* Can be more specific: "Python SDK", "REST API", "Management APIs" + +### Step 5: Write content + +Content goes directly after frontmatter (and optional import). No H3 heading needed — the title is in frontmatter. + +**Basic structure:** ```markdown -{Main paragraph — what changed, why it matters} +--- +title: March 23, 2026 - New Field Extraction Rules API +image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 +hide_table_of_contents: true +--- -#### {Subsection if needed} +{Main content paragraph(s)} -* {Item} +{Optional: H4 sections for subsections} + +{Optional: code blocks, lists, links} + +{Optional: admonitions for important notes} ``` -- H4 (`####`) for subsections (new endpoints, breaking changes, migration steps, etc.). -- Use `:::warning` admonitions for breaking changes. -- Doc links always use relative paths (`/docs/...`). -- Only add `import useBaseUrl` if content uses images. +### Step 6: Content formatting guidelines + +#### API Changes + +For API announcements, include: +* What changed (new endpoints, parameters, behavior) +* Impact on existing integrations +* Links to API documentation +* Migration guidance if breaking change + +**Example:** +```markdown +--- +title: March 23, 2026 - New Field Extraction Rules API +image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 +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 endpoints + +* **Field Extraction Rules API**: Create and manage Field Extraction Rules programmatically. See [Field Extraction Rules API](/docs/api/field-extraction-rules). +* **Webhook Connections API**: Create and manage webhook connections via API. See [Connections API](/docs/api/connections). + +#### Breaking changes + +**Monitors API**: The `notificationGroupFields` parameter is now required when creating monitors. Update your integrations before June 1, 2026. See the [Monitors API documentation](/docs/api/monitors) for details. +``` + +#### SDK Updates + +For SDK releases: +* Version number +* What's new or changed +* Installation instructions +* Link to SDK docs or GitHub + +**Example:** +```markdown +--- +title: March 23, 2026 - Python SDK Version 2.0 +image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 +hide_table_of_contents: true +keywords: + - sdk + - python +--- + +We've released version 2.0 of the Sumo Logic Python SDK with support for the latest APIs and improved error handling. + +#### What's new + +* Support for Field Extraction Rules API +* Async client support for better performance +* Improved error messages and debugging + +#### Installation + +```python +pip install sumologic-sdk==2.0.0 +``` + +Learn more in the [Python SDK documentation](/docs/api/python-client). +``` + +#### Deprecations + +For deprecation notices: +* What's being deprecated +* Why it's being deprecated (optional, if relevant) +* When it will be removed (end-of-life date) +* Migration path or alternatives +* Impact on existing users + +**Example (matches your template):** +```markdown +--- +title: April 9, 2025 - Deprecation of Sumo Logic India Data Center +image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 +hide_table_of_contents: true +keywords: + - deprecation + - datacenter +--- + +As previously communicated to impacted customers, effective as of April 30, 2025, customers will no longer be able to ingest data into the Sumo Logic Mumbai data center (`https://api.in.sumologic.com/`). Customers will retain access to historical data and basic search functionality until April 30, 2026, at which point all access will be terminated. + +Historical data will not be migrated to other deployments. + +**Reminder**: If you're still referencing the India endpoint, please update your integrations. For supported alternatives, see the [endpoint guide](/docs/api/about-apis/getting-started/#sumo-logic-endpoints-by-deployment-and-firewall-security). + +For help, contact [Support](https://support.sumologic.com/). +``` + +**Example (API deprecation):** +```markdown +--- +title: March 23, 2026 - Legacy Metrics API Deprecation +image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 +hide_table_of_contents: true +keywords: + - api + - deprecation +--- + +Effective **September 30, 2026**, the following legacy metrics API endpoints will be retired: +* `/v1/metrics/query` (use `/v2/metrics/query` instead) +* `/v1/metrics/catalog` (use `/v2/metrics/catalog` instead) + +**Migration**: Update your integrations to use the v2 endpoints. See the [Metrics API migration guide](/docs/api/metrics-migration) for details. + +**Impact**: After September 30, 2026, requests to legacy endpoints will return HTTP 410 (Gone). + +For help, contact [Support](https://support.sumologic.com/). +``` + +#### Minor Changes + +For small updates or enhancements: +* Brief description of the change +* Link to relevant docs +* Optional impact note + +**Example:** +```markdown +--- +title: March 23, 2026 - API Enhancements +image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 +hide_table_of_contents: true +--- + +We've made the following improvements to our APIs: + +* **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. +``` + +### Step 7: Validation checklist + +Before finishing, verify: +* [ ] File created in `/blog-developer/` directory (root level) +* [ ] Filename follows pattern: `YYYY-MM-DD-{slug}.md` +* [ ] Frontmatter complete with all required fields +* [ ] Title starts with "Month Day, YYYY - " format +* [ ] Date format uses full month name, no ordinal (e.g., "April 9" not "April 9th") +* [ ] `hide_table_of_contents: true` is present +* [ ] Standard image URL is used +* [ ] Content is clear and includes relevant links +* [ ] Breaking changes are clearly marked (use bold or H4 sections) +* [ ] Documentation links use relative paths (start with `/docs/`) +* [ ] Keywords added if applicable (deprecation, api, sdk, etc.) +* [ ] No trailing whitespace + +## Example usage + +### API Feature Example + +``` +User: "Create a developer release note for new Field Extraction Rules API endpoints, dated March 23, 2026" + +Claude: +1. Confirms date: March 23, 2026 +2. Generates slug: "field-extraction-rules-api" +3. Creates: blog-developer/2026-03-23-field-extraction-rules-api.md +4. Generates frontmatter: + - title: "March 23, 2026 - New Field Extraction Rules API" + - image: Standard Sumo Logic image + - hide_table_of_contents: true +5. Writes content with: + - Description of new endpoints + - Link to API documentation + - Impact notes +6. Provides checklist +``` + +### Deprecation Example + +``` +User: "Create a deprecation notice for Sumo Logic India Data Center, dated April 9, 2025" + +Claude: +1. Confirms date: April 9, 2025 +2. Generates slug: "india-datacenter-deprecation" +3. Creates: blog-developer/2025-04-09-india-datacenter-deprecation.md +4. Generates frontmatter: + - title: "April 9, 2025 - Deprecation of Sumo Logic India Data Center" + - keywords: deprecation, datacenter +5. Writes content with: + - What's being deprecated + - Timeline and dates + - Migration guidance + - Support contact +6. Provides checklist +``` + +## 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) + +**Examples:** +* ✅ March 23, 2026 +* ✅ January 1, 2026 +* ✅ December 31, 2025 +* ❌ March 23rd, 2026 (no ordinal) +* ❌ Mar 23, 2026 (abbreviated month) +* ❌ 2026-03-23 (wrong format) + +## Content formatting guidelines + +**Use formatting for clarity:** +* Use **bold** for important terms or breaking changes +* Use H4 sections (`####`) for subsections when needed +* Use bullet lists for multiple related items +* Use admonitions (`:::note`, `:::warning`) for important callouts + +**Example:** +```markdown +#### Breaking changes + +**Monitors API**: The `notificationGroupFields` parameter is now required when creating monitors. Update your integrations before June 1, 2026. + +:::warning +This is a breaking change. Existing integrations must be updated by June 1, 2026. +::: + +**Links:** +* Always use relative paths starting with `/docs/` +* Use descriptive link text (not "click here") +* Example: `[Metrics API documentation](/docs/api/metrics)` + +**Code blocks:** +* Use appropriate language tags (```python, ```bash, ```json) +* Keep examples concise and relevant +* Show before/after for migration guides + +## Safety principles + +* **Check for existing files** before creating to avoid duplicates +* **Use clear, descriptive slugs** that indicate content +* **Validate dates**. Ensure date is not in future +* **Include documentation links**. Help users find more info +* **Mark breaking changes clearly**. Use bold text or H4 sections +* **Use standard frontmatter**. Consistent image URL and structure +* **Keep content focused**. One topic per release note + +## Post-completion message + +After successfully creating the release note, tell the user: + +``` +✅ Developer release note created successfully! + +File created: +* 📄 blog-developer/{YYYY-MM-DD-slug}.md + +Summary: +* 📅 Title: {Month Day, YYYY} - {Topic} +* 📝 {Brief summary of content} +* 🏷️ Keywords: {keywords if added} + +Next steps: +1. Review content for accuracy and clarity +2. Verify documentation links are correct +3. Ensure breaking changes are clearly marked +4. Test locally: yarn start +5. Check preview at: http://localhost:3000/release-notes-developer +6. Submit PR: "DOCS-XXX - Developer release note: {Topic}" + +Checklist: +* [ ] Title format is correct (Month Day, YYYY - Topic) +* [ ] Date uses full month name, no ordinal +* [ ] Standard image URL is used +* [ ] hide_table_of_contents: true is present +* [ ] Documentation links use relative paths +* [ ] Breaking changes clearly marked +* [ ] Content is clear and concise + +The release note will appear on the Developer release notes page in reverse chronological order (newest first). + +Would you like me to help refine the content or add additional details? +``` + +## Error handling + +**If file already exists:** +* Show existing file path and creation date +* Ask if user wants to: + * Use different slug (e.g., add `-v2` or more specific topic) + * Use different date + * Overwrite (requires explicit confirmation) + +**If date is in the future:** +* Warn user and ask for confirmation +* Suggest using current date + +**If slug is too generic:** +* Warn if slug is too short or vague (e.g., "api", "update") +* Suggest more descriptive slug (e.g., "field-extraction-rules-api") + +**If documentation link looks invalid:** +* Warn if doesn't start with `/docs/` +* Suggest correction +* Proceed with user confirmation + +**If content is too long:** +* Suggest breaking into subsections (H4) +* Recommend creating separate doc page and linking to it from release note + +## Tips and best practices + +**For API changes:** +* Be specific about what endpoints changed +* Include examples of new request/response formats +* Provide migration timeline for breaking changes +* Link to comprehensive API documentation + +**For deprecations:** +* Give ample notice (3-6 months minimum) +* Clearly state end-of-life date +* Provide migration path with examples +* Offer support contact for questions + +**For SDK releases:** +* Include version number prominently +* Show installation/upgrade commands +* Highlight breaking changes separately +* Link to changelog or GitHub release + +**All release notes:** +* Write for developers (assume technical knowledge) +* Focus on impact and action items +* Use clear, direct language +* Provide links for more information +* Keep entries concise but complete -### Step 3: Validate +## References -- [ ] `blog-developer/YYYY-MM-DD-{slug}.md` -- [ ] Title: "Month Day, YYYY - Topic" (no ordinal) -- [ ] `hide_table_of_contents: true` -- [ ] Breaking changes clearly marked -- [ ] Doc links use relative paths -- [ ] No trailing whitespace +* [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) diff --git a/.claude/commands/release-note-service.md b/.claude/commands/release-note-service.md index 09ca45aff9..4126e3a28b 100644 --- a/.claude/commands/release-note-service.md +++ b/.claude/commands/release-note-service.md @@ -1,57 +1,474 @@ # Create New Service Release Note -Creates a Service release note for a new feature, update, or improvement across Sumo Logic platform categories. +Automates the creation of Service release notes for new features, updates, and improvements across Sumo Logic platform categories. + +## What this command does + +When you invoke `release-note-service`, Claude will guide you through: + +1. **Determine category**. Apps, Manage, Collection, Search, or UI +2. **Gather release details**. Feature name, description, and changes +3. **Create markdown file**. Generate file with proper frontmatter and structure +4. **Format content**. Apply correct formatting for the feature announcement +5. **Validate and preview**. Check structure and provide next steps + +## When to use this command + +* Announcing new platform features or capabilities +* Documenting updates to existing features +* Publishing UI improvements and enhancements +* Releasing new collection methods or integrations +* Announcing management and admin features +* Publishing app-related updates + +## Categories + +Service release notes are organized by platform area: + +* **Apps**. App-related features and updates +* **Collection**. Data collection features, sources, authentication +* **Manage**. Management and administration features +* **Search**. Search features, queries, analytics +* **UI**. User interface updates and improvements (often labeled "New UI") ## Workflow ### Step 1: Gather information Ask the user for: -- **Category**: apps, collection, manage, search, or ui -- **Feature name**: brief, descriptive name -- **Release date**: YYYY-MM-DD format -- **Description**: 2–3 sentences — what the feature is and why it matters -- **Doc link**: relative path (optional) -- **"What's new" bullets**: optional, for multiple specific changes -- **Keywords**: confirm with user before creating file -### Step 2: Create the file +**Required:** +* **Category**: Which platform area (apps, collection, manage, search, ui) +* **Feature name**: Brief, descriptive name of the feature or update +* **Release date**: Date in YYYY-MM-DD format +* **Description**: What the feature does and why it matters (2-3 sentences) + +**Optional:** +* **Documentation link**: Relative path to the doc (e.g., `/docs/manage/...`) +* **"What's new" details**: Bulleted list of specific changes or capabilities +* **Keywords**: Custom keywords for frontmatter (suggest defaults based on content) -**File**: `blog-service/YYYY-MM-DD-{category}.md` +**Validate:** +* Check that date is not in the future +* Ensure category is valid (apps, collection, manage, search, ui) +* Verify documentation link is valid relative path if provided +* Ask user to confirm keywords before creating file -If a file already exists for the same date and category, ask the user to use a different date, append to the existing file, or add a more specific suffix. +### Step 2: Create the markdown file -**Frontmatter**: +**File naming convention:** +``` +blog-service/YYYY-MM-DD-{category}.md +``` + +Examples: +* `blog-service/2026-03-20-collection.md` +* `blog-service/2026-03-18-apps.md` +* `blog-service/2026-02-12-ui.md` + +**Important**: Files are created in `/blog-service/` directory + +**Note on file conflicts**: If a file already exists for the same date and category, ask the user: +* Use a different date +* Append to existing file (if related features) +* Use more specific category suffix (e.g., `-collection-m365` if needed) + +### Step 3: Generate frontmatter + +**Standard frontmatter:** ```yaml --- -title: {Feature Description} ({Category Label}) +title: {Feature Description} ({Category}) image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 keywords: - {keyword1} + - {keyword2} hide_table_of_contents: true --- ``` -**Title**: Feature description in Title Case + category label in parentheses. No date in title. -- apps → (Apps) | collection → (Collection) | manage → (Manage) | search → (Search) | ui → (New UI) +**Title formatting:** +* Feature description in Title Case +* Category in parentheses: (Apps), (Collection), (Manage), (Search), (New UI) +* NO date in title (unlike other release note types) +* Keep concise but descriptive +* Examples: + * "App Registration Authentication for Microsoft 365 Audit Source (Collection)" + * "Data Volume for MSSP (Apps)" + * "Content Item Actions Available Directly From Navigation Menus (New UI)" + +**Category labels in titles:** +* apps → (Apps) +* collection → (Collection) +* manage → (Manage) +* search → (Search) +* ui → (New UI) + +**Image:** +* Always use the standard Sumo Logic preview image +* URL: `https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082` + +**Keywords:** +* **Always ask user to confirm keywords before creating file** +* Suggest keywords based on content: + * Feature-specific terms (e.g., "Microsoft 365 Audit", "authentication") + * Category keywords (e.g., "apps", "ui", "collection") + * Product names or technologies mentioned +* Format: + ```yaml + keywords: + - keyword1 + - keyword2 + ``` +* User can customize the list + +### Step 4: Add optional import + +For release notes that use links or useBaseUrl: +```javascript +import useBaseUrl from '@docusaurus/useBaseUrl'; +``` + +**Note**: Only add if content uses it. For simple text-only releases, omit. + +### Step 5: Write content -**Content**: +Content goes directly after frontmatter (and optional import). No H3 heading needed — the title is in frontmatter. + +**Basic structure:** ```markdown -{Description — what the feature is and why it matters} +--- +title: Feature Name (Category) +image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 +keywords: + - keyword1 + - keyword2 +hide_table_of_contents: true +--- + +{Description paragraph explaining the feature and its benefits} + +{Optional: What's new section with bulleted list} + +{Optional: Documentation links} +``` + +#### Simple Feature Announcement + +For straightforward feature updates: +```markdown +--- +title: App Registration Authentication for Microsoft 365 Audit Source (Collection) +image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 +keywords: + - Microsoft 365 Audit + - authentication +hide_table_of_contents: true +--- + +The Microsoft 365 Audit Source now supports the App Registration authentication method. This enhancement allows organizations to authenticate using Azure Active Directory App Registrations, providing a more secure and flexible authentication option for collecting Microsoft 365 audit logs. + +[Learn more](/docs/send-data/hosted-collectors/cloud-to-cloud-integration-framework/microsoft-365-audit-source/). +``` + +#### Feature with "What's new" Section + +For features with multiple specific changes: +```markdown +--- +title: Content Item Actions Available Directly From Navigation Menus (New UI) +image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 +keywords: + - ui +hide_table_of_contents: true +--- + +You can now perform common actions on content items directly from the navigation menus in the left-hand sidebar, making it faster and easier to manage your content without opening each item. **What's new:** -* {Specific capability} +* Right-click on any content item in the sidebar to access a context menu +* Available actions: Open, Open in New Tab, Copy, Move, Delete, Share, Schedule Report +* Works for dashboards, searches, folders, and other content items +* Same functionality as the Actions menu in the Content Library -[Learn more](/docs/path/to/doc). +This enhancement streamlines your workflow by providing quick access to frequently used actions. [Learn more](/docs/get-started/library/). ``` -"What's new:" is optional — use for multiple specific changes, omit for single-point announcements. Only add `import useBaseUrl` if the content uses it. +### Step 6: Content formatting guidelines + +**Write for clarity:** +* Start with a clear statement of what the feature is +* 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 + +**Use formatting for readability:** +* Use **bold** for section labels like "What's new:" +* Use bullet lists for multiple related items +* Use admonitions (`:::note`, `:::warning`) for important callouts if needed +* Keep paragraphs concise (2-4 sentences max) + +**Links:** +* Always use relative paths starting with `/docs/` +* Use descriptive link text (typically "Learn more") +* Example: `[Learn more](/docs/send-data/...)` + +**Examples by category:** + +**Apps:** +```markdown +--- +title: Data Volume for MSSP (Apps) +image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 +keywords: + - data-volume-for-mssp + - apps +hide_table_of_contents: true +--- + +The Data Volume for MSSP app is now available, providing managed security service providers with visibility into data usage across multiple customer accounts. This app helps MSSPs track, analyze, and optimize data ingestion to improve cost management and capacity planning. + +[Learn more](/docs/integrations/sumo-apps/data-volume-for-mssp). +``` + +**Collection:** +```markdown +--- +title: Enhanced Authentication Options for Cloud Sources (Collection) +image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 +keywords: + - authentication + - cloud-to-cloud + - collection +hide_table_of_contents: true +--- + +Cloud-to-Cloud sources now support additional authentication methods including OAuth 2.0 client credentials flow and service account authentication. These new options provide more flexibility for enterprise customers to integrate with cloud services using their preferred authentication standards. + +**What's new:** +* OAuth 2.0 client credentials flow for machine-to-machine authentication +* Service account support for Google Cloud and AWS integrations +* Enhanced security with token rotation and expiration handling +* Backward compatible with existing authentication methods + +[Learn more](/docs/send-data/hosted-collectors/cloud-to-cloud-integration-framework/). +``` + +**UI:** +```markdown +--- +title: Improved Dashboard Loading Performance (New UI) +image: https://assets-www.sumologic.com/company-logos/_800x418_crop_center-center_82_none/SumoLogic_Preview_600x600.jpg?mtime=1617040082 +keywords: + - ui + - dashboards + - performance +hide_table_of_contents: true +--- + +Dashboards now load up to 50% faster in the new UI through optimized query execution and progressive rendering. Large dashboards with many panels will see the most significant improvements, reducing wait times and improving the overall user experience. +``` + +### Step 7: Validation checklist + +Before finishing, verify: +* [ ] File created in `/blog-service/` directory +* [ ] Filename follows pattern: `YYYY-MM-DD-{category}.md` +* [ ] Frontmatter complete with all required fields +* [ ] Title includes feature description and category in parentheses +* [ ] Title does NOT include date +* [ ] `hide_table_of_contents: true` is present +* [ ] Standard image URL is used +* [ ] Keywords confirmed with user +* [ ] Category label uses correct format: (Apps), (Collection), (Manage), (Search), (New UI) +* [ ] Content is clear and focused on user benefits +* [ ] Documentation link uses relative path (starts with `/docs/`) +* [ ] No trailing whitespace + +## Example usage + +### Collection Feature Example + +``` +User: "Create a Service release note for Microsoft 365 Audit Source App Registration authentication, collection category, dated March 20, 2026" + +Claude: +1. Confirms category: Collection +2. Confirms date: 2026-03-20 +3. Asks for keywords (suggests: "Microsoft 365 Audit", "authentication") +4. Creates: blog-service/2026-03-20-collection.md +5. Generates frontmatter: + - title: "App Registration Authentication for Microsoft 365 Audit Source (Collection)" + - keywords: Microsoft 365 Audit, authentication +6. Writes content with: + - Description of new authentication method + - Business value + - Link to documentation +7. Provides checklist +``` + +### UI Feature Example + +``` +User: "Create a Service release note for new context menu actions in the sidebar, UI category, dated February 12, 2026" + +Claude: +1. Confirms category: UI +2. Confirms date: 2026-02-12 +3. Asks for keywords (suggests: "ui", "navigation") +4. Creates: blog-service/2026-02-12-ui.md +5. Generates frontmatter: + - title: "Content Item Actions Available Directly From Navigation Menus (New UI)" + - keywords: ui +6. Writes content with: + - Feature description + - "What's new" section with bullets + - Link to documentation +7. Provides checklist +``` + +## Category guidelines + +**Apps**. Use for: +* New apps or app updates +* App integrations +* App-specific features +* MSSP or multi-tenant features + +**Collection**. Use for: +* New sources or source types +* Collection authentication changes +* Collector features +* Data ingestion enhancements + +**Manage**. Use for: +* Account management features +* User and role management +* Security and compliance features +* Settings and configuration updates + +**Search**. Use for: +* Search language enhancements +* Query performance improvements +* Analytics features +* Data parsing updates + +**UI**. Use for: +* User interface changes +* Navigation improvements +* Visual design updates +* Workflow enhancements +* Label as "(New UI)" in title + +## Safety principles + +* **Check for existing files** before creating (same date + category = conflict) +* **Validate category** is one of: apps, collection, manage, search, ui +* **Use clear, descriptive titles** that explain the feature +* **Include documentation links**. Help users find more info +* **Use standard frontmatter**. Consistent image URL and structure +* **Keep content focused**. One feature per release note +* **Always ask user to confirm keywords** before creating file + +## Post-completion message + +After successfully creating the release note, tell the user: + +``` +✅ Service release note created successfully! + +File created: +* 📄 blog-service/{YYYY-MM-DD-category}.md + +Summary: +* 📋 Category: {Category} +* 📝 Title: {Feature Description} ({Category}) +* 🏷️ Keywords: {keywords} + +Next steps: +1. Review content for accuracy and clarity +2. Verify documentation link is correct +3. Ensure keywords are appropriate +4. Test locally: yarn start +5. Check preview at: http://localhost:3000/release-notes-service +6. Submit PR: "DOCS-XXX - Service release note: {Feature Description}" + +Checklist: +* [ ] Title format is correct (Feature Description (Category)) +* [ ] Title does NOT include date +* [ ] Category label uses correct format +* [ ] Standard image URL is used +* [ ] hide_table_of_contents: true is present +* [ ] Documentation link uses relative path +* [ ] Content is clear and concise +* [ ] Keywords confirmed with user + +The release note will appear on the Service release notes page in reverse chronological order (newest first). + +Would you like me to help refine the content or add additional details? +``` + +## Error handling + +**If file already exists:** +* Show existing file path and creation date +* Ask if user wants to: + * Use different date + * Append to existing file (if related features) + * Use more specific category suffix (e.g., `-collection-m365`) + * Overwrite (requires explicit confirmation) + +**If date is in the future:** +* Warn user and ask for confirmation +* Suggest using current date + +**If category is invalid:** +* Show error: "Category must be one of: apps, collection, manage, search, ui" +* Ask user to select valid category + +**If documentation link looks invalid:** +* Warn if doesn't start with `/docs/` +* Suggest correction +* Proceed with user confirmation + +**If title is too long:** +* Warn if title exceeds 100 characters +* Suggest shorter, more concise wording +* Category label must stay in title + +**If keywords not confirmed:** +* Do not create file until user confirms keywords +* Show suggested keywords and wait for approval/modification + +## Tips and best practices + +**For all Service releases:** +* 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 + +**Title guidelines:** +* Be specific about the feature (not "New Collection Feature") +* Use active language ("Enhanced...", "New...", "Improved...") +* Include category in parentheses at end +* No date in title (unlike other release types) +* Keep under 100 characters including category + +**Content structure:** +* First paragraph: What is it and why does it matter? +* Optional "What's new" section: Specific capabilities or changes +* Final element: "Learn more" link to docs + +**Keywords:** +* Include feature-specific terms +* Add category keyword (apps, ui, collection, etc.) +* Mention product names or technologies +* Keep list focused (2-5 keywords) -### Step 3: Validate +## References -- [ ] `blog-service/YYYY-MM-DD-{category}.md` -- [ ] Title: feature description + category label in parens, no date -- [ ] `hide_table_of_contents: true` -- [ ] Keywords confirmed with user -- [ ] Doc link uses `/docs/...` relative path -- [ ] No trailing whitespace +* [Service Release Notes](https://sumologic.com/help/release-notes-service) +* [Release Notes Index](/docs/release-notes) +* [Style Guide](/docs/contributing/style-guide) From eafda596e6ea482f73401f795e1699a6f9f75e9c Mon Sep 17 00:00:00 2001 From: Kim Pohas Date: Fri, 5 Jun 2026 00:54:32 -0700 Subject: [PATCH 15/22] revert --- .claude/commands/audit-doc.md | 21 ++++++ .claude/commands/doc-from-jira.md | 18 +++++ .claude/commands/doc.md | 22 +++++- .claude/commands/geo-optimize.md | 18 +++++ .claude/commands/remove-doc.md | 63 ++++++++++++++++ .claude/commands/review.md | 115 ------------------------------ .claude/commands/seo-audit.md | 17 +---- CLAUDE.md | 1 - 8 files changed, 143 insertions(+), 132 deletions(-) delete mode 100644 .claude/commands/review.md diff --git a/.claude/commands/audit-doc.md b/.claude/commands/audit-doc.md index 46312d92e4..b17f5dd32c 100644 --- a/.claude/commands/audit-doc.md +++ b/.claude/commands/audit-doc.md @@ -2,6 +2,27 @@ Performs comprehensive quality checks on documentation files to ensure adherence to Sumo Logic style guidelines, proper structure, and completeness. +## What this command does + +When you invoke `/audit-doc`, Claude will: + +1. **Read and analyze the specified doc file** +2. **Check frontmatter**. Validate required fields and format +3. **Review content structure**. Check headings, sections, and organization +4. **Validate links and images**. Check paths, alt text, and references +5. **Check style adherence**. Apply Sumo Logic style guide rules +6. **Report findings**. Provide detailed feedback with specific line numbers +7. **Suggest fixes**. Offer actionable recommendations + +## When to use this command + +* Before submitting a PR to check doc quality +* After creating a new doc to validate structure +* When updating existing docs to ensure consistency +* To identify broken links or missing images +* To verify adherence to Sumo Logic style guidelines +* When reviewing community contributions + ## Workflow ### Step 1: Identify the doc to audit diff --git a/.claude/commands/doc-from-jira.md b/.claude/commands/doc-from-jira.md index 3873aeb2bd..3e06303350 100644 --- a/.claude/commands/doc-from-jira.md +++ b/.claude/commands/doc-from-jira.md @@ -2,6 +2,24 @@ Pulls a Jira ticket from the DOCS project, extracts the content requirements, and scaffolds a fully structured documentation file ready for writing. Eliminates the blank-page problem and keeps the doc aligned with the ticket spec from the start. +## What this command does + +When you invoke `/doc-from-jira`, Claude will: + +1. **Fetch the Jira ticket**. Pull title, description, acceptance criteria, and linked resources +2. **Determine doc type**. Feature, how-to, concept, reference, or troubleshooting +3. **Infer the file path**. Based on the technical area and content type +4. **Scaffold the doc**. Generate a file with correct frontmatter, structure, and placeholder sections pre-populated from the ticket +5. **Update sidebars.ts**. Add the new doc to navigation (with user approval) +6. **Link back to Jira**. Set the Jira ticket to In Progress if not already + +## When to use this command + +* Starting a new doc for a DOCS ticket +* When a ticket has a detailed description or acceptance criteria worth preserving +* For tickets with linked specs, PRDs, or engineering docs to pull context from +* When you want to ensure the doc structure is aligned with what was requested + ## When NOT to use this command * **App integrations** — use `/app-doc` instead diff --git a/.claude/commands/doc.md b/.claude/commands/doc.md index aa72e99dc2..e5f3fb9bbc 100644 --- a/.claude/commands/doc.md +++ b/.claude/commands/doc.md @@ -2,11 +2,31 @@ Automates the creation of general Sumo Logic documentation for features, how-tos, concepts, reference pages, and troubleshooting guides. +## What this command does + +When you invoke `doc`, Claude will guide you through: + +1. **Determine doc type**. Feature, how-to, concept, reference, or troubleshooting. +2. **Gather information**. Title, description, file path, and keywords. +3. **Create markdown file**. Generate file with proper frontmatter and basic structure. +4. **Add to navigation**. Guide on adding to sidebars.ts. +5. **Add to hub page**. Suggest adding card to parent index page. +6. **Create CID mapping**. Add permanent URL if needed for UI links. +7. **Validate and preview**. Check structure and provide next steps. + +## When to use this command + +* Creating feature documentation. +* Writing how-to guides and tutorials. +* Documenting concepts and reference material. +* Creating troubleshooting guides. +* Adding general content that does not fit specialized templates (apps, sources, release notes). + ## When NOT to use this command * **App integrations**. Use `app-doc` instead. * **Cloud-to-Cloud sources**. Use `c2c-source-doc` instead. -* **Release notes**. Use `release-note` instead. +* **Release notes**. Use `release-note-cse` or `release-note-collector` instead. ## Doc types diff --git a/.claude/commands/geo-optimize.md b/.claude/commands/geo-optimize.md index 0df544be63..6710532404 100644 --- a/.claude/commands/geo-optimize.md +++ b/.claude/commands/geo-optimize.md @@ -2,6 +2,24 @@ Rewrites and restructures documentation to improve discoverability in AI-powered search tools (ChatGPT, Perplexity, Gemini, Claude, and similar) and to surface content as direct answers in traditional search results. Covers both **AEO** (Answer Engine Optimization — featured snippets, "People also ask") and **GEO** (Generative Engine Optimization — LLM citation and extraction). +## What this command does + +When you invoke `/geo-optimize`, Claude will: + +1. **Read the doc** +2. **Diagnose the current state**. Identify AEO and GEO gaps before making changes +3. **Propose specific improvements**. Show the user what will change and why +4. **Apply approved changes**. Rewrite only the sections the user approves +5. **Validate the result**. Confirm the doc is more answer- and citation-ready without breaking accuracy + +## When to use this command + +* New docs for features that are frequently searched in AI tools or voice search +* High-traffic docs that rarely appear in AI-generated answers or featured snippets +* Concept and reference docs where accuracy and citability matter most +* After `/seo-audit` flags AEO or GEO suggestions +* Before a product launch to maximize early visibility + ## What this command does NOT change * Technical accuracy — never alter facts, steps, code, or configuration values diff --git a/.claude/commands/remove-doc.md b/.claude/commands/remove-doc.md index 1755ba360f..6a2821a8fe 100644 --- a/.claude/commands/remove-doc.md +++ b/.claude/commands/remove-doc.md @@ -2,6 +2,24 @@ Automates the complete workflow for removing or moving a Sumo Logic doc while preventing broken links and maintaining SEO health. +## What this command does + +When you invoke `/remove-doc`, Claude will guide you through: + +1. **Create 301 redirect**. Add redirect mapping to `cid-redirects.json`. +2. **Update internal links**. Find and replace all references to the old URL. +3. **Remove from hub pages**. Delete card from parent `index.md` and Product List. +4. **Delete the doc file**. Remove the actual markdown file. +5. **Remove from navigation**. Delete entry from `sidebars.ts`. +6. **Optional steps**. Add deprecation notes, hide from search engines. + +## When to use this command + +* Deprecating legacy docs in favor of new versions. +* Consolidating duplicate content. +* Removing outdated documentation. +* Moving docs to new locations. + ## Workflow ### Step 1: Gather information @@ -84,6 +102,24 @@ Before finishing, verify: * [ ] JSON files valid (no syntax errors). * [ ] Build test passes (optional: `yarn build`). +## Example usage + +``` +User: "Remove the nginx-legacy.md doc and redirect to nginx.md" + +Claude: +1. Confirms old path: docs/integrations/web-servers/nginx-legacy.md +2. Confirms new path: docs/integrations/web-servers/nginx.md +3. Adds redirect: "/docs/integrations/web-servers/nginx-legacy": "/docs/integrations/web-servers/nginx" +4. Searches for all references to nginx-legacy +5. Updates links in 3 files +6. Removes from web-servers index.md hub page +7. Deletes nginx-legacy.md +8. Removes from sidebars.ts +9. Asks about deprecation note +10. Provides verification checklist +``` + ## Safety principles * **Always create the redirect first** before deleting anything. @@ -133,3 +169,30 @@ Create: Multiple redirects, all pointing to unified-doc.md * Revert the change. * Fix and retry. +## Post-completion message + +After successfully removing a doc, tell the user: + +``` +✅ Doc removal complete! + +Summary: +* Added 301 redirect: /old-path → /new-path +* Updated X internal links across Y files +* Removed from hub page and sidebar +* Deleted old doc file + +Next steps: +1. Test locally: yarn start +2. Verify redirect works +3. Submit PR with description: "DOCS-XXX - Remove deprecated [doc name]" +4. Note: Google may take weeks to update search results + +Would you like me to run a build test or create a commit? +``` + +## References + +* [Contributing guide: Move or Remove a Doc](/docs/contributing/remove-doc). +* [CID redirects documentation](/docs/contributing/create-edit-doc#step-6-create-cid-url). +* [Sidebar configuration patterns](.claude/skills/docusaurus/). diff --git a/.claude/commands/review.md b/.claude/commands/review.md deleted file mode 100644 index 4dff1db6f4..0000000000 --- a/.claude/commands/review.md +++ /dev/null @@ -1,115 +0,0 @@ -# Review Pull Request — Documentation Quality Review - -Reviews all changed `.md` files in a pull request using the same checks as `/audit-doc`, then produces a single consolidated PR review comment. - -## Workflow - -### Step 1: Get the PR - -If a PR number or URL is provided, use it. Otherwise run `gh pr list` and ask the user which PR to review. - -Extract the PR number from URLs (e.g., `https://github.com/.../pull/6707` → `6707`). - -### Step 2: Fetch PR details and diff - -Run in parallel: -- `gh pr view --json title,body,author,headRefName,baseRefName,changedFiles` -- `gh pr diff ` - -### Step 3: Identify changed doc files - -From the diff, collect all files with a `.md` extension that were added or modified (ignore deletions). Skip non-doc files (`.ts`, `.json`, `.js`, `.yml`, etc.). - -If no `.md` files changed, report: "No documentation files changed in this PR." - -### Step 4: Determine doc type for each file - -Use the file path to infer the doc type: - -| Path pattern | Doc type | -|---|---| -| `blog-service/`, `blog-collector/`, `blog-cse/`, `blog-csoar/`, `blog-developer/` | Release note | -| `docs/integrations/` or `docs/platform-services/automation-service/app-central/` | App doc | -| `docs/send-data/hosted-collectors/cloud-to-cloud-integration-framework/` | C2C source doc | -| Everything else under `docs/` | Feature / how-to / concept / reference | - -If the type is ambiguous, read the file's frontmatter `tags` field or intro paragraph to confirm. - -### Step 5: Read each changed file - -Use the Read tool to fetch the full current content of each changed `.md` file (not just the diff lines — the full file is needed to check structure, frontmatter, and links in context). - -### Step 6: Apply audit-doc checks to each file - -Apply all checks from `/audit-doc` — frontmatter, structure, links, images, style guide, doc-type-specific requirements — using the same severity levels: - -- **Critical**: must fix before merging -- **Warning**: should fix -- **Suggestion**: nice to have - -See `/audit-doc` for the full checklist. Key things to flag in a PR review: - -- Missing or invalid frontmatter fields (`id`, `title`, `description`) -- Branding violations ("Sumo" instead of "Sumo Logic", wrong app/source opener) -- Wrong heading case (sentence case required — only first word and proper nouns capitalized) -- Missing required sections for the doc type -- Negative contractions (can't, won't, don't → cannot, will not, do not) -- "the user" or "users" instead of "you" -- Bare URLs, missing alt text, missing code block language tags -- Release note format violations (date format, `[New]`/`[Updated]` tags, rule ID patterns) - -Focus on issues introduced by this PR. If the file has pre-existing issues that weren't touched by the diff, note them briefly but do not block the PR over them. - -### Step 7: Produce the review - -Output a single consolidated review covering all changed files. Format: - -``` -## PR review: {PR title} - -{N} doc file(s) changed: {list of filenames} - ---- - -### {filename} -**Type**: {doc type} - -**Critical issues** (must fix): -- {issue with line reference if possible} - -**Warnings** (should fix): -- {issue} - -**Suggestions**: -- {issue} - -✅ No issues / ⚠️ {N} warnings / ❌ {N} critical - ---- - -### {next filename} -... - ---- - -## Overall - -{Pass | Pass with warnings | Needs work} - -{1-2 sentence summary of the most important things to address} -``` - -If a file has no issues: `✅ {filename} — looks good.` - -### Step 8: Offer next steps - -After the review, offer: -- "Run `/audit-doc {file}` to get a detailed report with line numbers and fix options" -- "Run `/seo-audit {file}` to check discoverability signals" - -## Constraints - -- **Read-only**. Do not edit any files. The purpose is to surface issues, not fix them. -- **Diff-aware**. Prioritize issues in lines added or modified by the PR. Flag pre-existing issues separately as "pre-existing" if needed. -- **Concise**. This is a PR review, not a full audit report. One line per issue where possible. -- **No duplication**. The checks live in `/audit-doc`. Do not re-list every rule here — apply them, don't describe them. diff --git a/.claude/commands/seo-audit.md b/.claude/commands/seo-audit.md index 472e1e94fb..99b145871b 100644 --- a/.claude/commands/seo-audit.md +++ b/.claude/commands/seo-audit.md @@ -28,10 +28,8 @@ Use the Read tool to read the complete file content including frontmatter. **Frontmatter** -* [ ] `title` present -* [ ] `title` is under 60 characters — **Critical** if missing or over 60 +* [ ] `title` is under 60 characters — **Critical** if over 60 * [ ] `title` includes the primary keyword or product/feature name -* [ ] `description` present — **Critical** if missing * [ ] `description` is 140–160 characters — **Warning** if shorter than 100 or longer than 160 * [ ] `description` leads with an action verb or product name (not "This page" or "This doc") * [ ] `keywords` field present with 3–5 relevant terms — **Suggestion** if missing @@ -39,8 +37,6 @@ Use the Read tool to read the complete file content including frontmatter. **Headings** -* [ ] No H1 in body — title frontmatter generates H1; a second H1 breaks SEO — **Critical** if present -* [ ] H2 used for main sections; no skipped heading levels (H2 → H4 without H3) — **Warning** if skipped * [ ] At least 2 H2 headings for pages over 500 words — **Suggestion** if none * [ ] No duplicate headings at the same level — **Warning** if duplicated * [ ] Headings are under 60 characters — **Suggestion** if over @@ -49,12 +45,9 @@ Use the Read tool to read the complete file content including frontmatter. * [ ] First paragraph (after frontmatter) is substantive — tells the reader what the doc covers, why it matters, and who it is for — **Warning** if it is thin (under 50 words) or just restates the title * [ ] Page has at least one internal link to a related doc — **Warning** if none -* [ ] Internal link anchor text is descriptive (not "click here" or "here") — **Warning** if bare -* [ ] No bare external URLs — wrap in markdown link syntax — **Warning** if present **Images** -* [ ] All images have non-empty `alt` text — **Critical** if missing * [ ] Alt text describes the image content, not just "screenshot" or the filename — **Warning** if generic ### Step 4: Run AEO checks @@ -136,11 +129,8 @@ Do not modify files without explicit user approval. | Issue | Why it matters | |-------|---------------| -| Missing `description` | Search engines cannot generate a preview snippet; AI tools have no summary to cite | -| Missing `title` | Page cannot be indexed or linked properly | | `title` over 60 chars | Truncated in search results; first 60 chars carry the most weight | -| H1 in body | Duplicate H1 confuses search engines and breaks page structure | -| Missing image alt text | Accessibility failure; images are invisible to search crawlers | +| `slug` on regular page | Overrides URL derived from file path; breaks sidebar linking | ### Warnings @@ -182,10 +172,8 @@ Then ask if the user wants to drill into any specific file. ## Tips -* Run this before `/audit-doc` to prioritize discoverability fixes first * Run this after `/geo-optimize` to verify improvements were applied * For batch fixes on description length, `/seo-audit` + `/geo-optimize` together cover most GEO gaps -* Pair with `/tone-check` for comprehensive pre-PR review --- @@ -195,4 +183,3 @@ Then ask if the user wants to drill into any specific file. * **`/audit-doc`** — structure, required sections, broken links, frontmatter completeness, style guide * **`/geo-optimize`** — apply GEO improvements after this audit identifies gaps -* **`/tone-check`** — voice and tone check (standalone; not covered here) diff --git a/CLAUDE.md b/CLAUDE.md index ca0fe74ec5..30e924ff98 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -109,7 +109,6 @@ Primary commands for documentation work. Proactively suggest when context fits | `/audit-doc` | Full quality audit: structure, style, links, frontmatter, completeness | | `/seo-audit` | Discoverability audit: SEO, AEO, and GEO signals — run this before a PR | | `/geo-optimize` | Rewrite a doc to improve AI citation and generative engine visibility | -| `/review` | Review a pull request — applies audit-doc checks to all changed `.md` files | **Jira** From 29ed0e4241b420ebdfed8e9949929af06ccd1d24 Mon Sep 17 00:00:00 2001 From: Kim Pohas <56411016+kimsauce@users.noreply.github.com> Date: Fri, 5 Jun 2026 00:58:43 -0700 Subject: [PATCH 16/22] DOCS-1526 - Add Bulk Changes guardrails to CLAUDE.md (#6720) * DOCS-1634 - Fix MCP server and OAuth docs (#6710) * DOCS-1634 - Fix MCP server and OAuth docs - Remove VS Code and ChatGPT sections from MCP server doc; scope prereqs to any OAuth 2.0 Authorization Code-compatible client - Fix claude mcp add command syntax for --client-secret flag - Expand OAuth client setup steps inline for Claude Code CLI - Soften prerequisite language in both docs - Rewrite Auth Code flow Step 2 to be actionable - Replace hardcoded deployment URLs with and placeholders in Client Credentials Step 3 - Add deployment token endpoint table to FAQ - Fix /oauth/token typo to /oauth2/token throughout Co-Authored-By: Claude Sonnet 4.6 * DOCS-1634: Add Known limitations section to MCP server doc Documents that Cursor (cursor:// redirect URLs unsupported) and recent VS Code releases (auth code flow broken with explicit client credentials) are not currently supported. Includes a note to contact support. Co-Authored-By: Claude Sonnet 4.6 --------- Co-authored-by: Claude Sonnet 4.6 * Bump webpack-dev-server from 5.2.2 to 5.2.4 (#6718) Bumps [webpack-dev-server](https://github.com/webpack/webpack-dev-server) from 5.2.2 to 5.2.4. - [Release notes](https://github.com/webpack/webpack-dev-server/releases) - [Changelog](https://github.com/webpack/webpack-dev-server/blob/main/CHANGELOG.md) - [Commits](https://github.com/webpack/webpack-dev-server/compare/v5.2.2...v5.2.4) --- updated-dependencies: - dependency-name: webpack-dev-server dependency-version: 5.2.4 dependency-type: indirect ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * DOCS-1526 - Add Bulk Changes guardrails to CLAUDE.md Distill the DOCS-63 post-mortem lessons into a short CLAUDE.md section instead of a full bulk-doc-change skill. Newer models handle most of the workflow naturally; only the non-obvious institutional rules (no revert from memory, atomic commits per directory, no committed helper scripts) need to persist as durable guidance. Co-Authored-By: Claude Sonnet 4.6 --------- Signed-off-by: dependabot[bot] Co-authored-by: Claude Sonnet 4.6 Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- CLAUDE.md | 10 ++++++++++ docs/api/mcp-server.md | 6 +++++- yarn.lock | 3 +++ 3 files changed, 18 insertions(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index 30e924ff98..7219f2f3e9 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -15,6 +15,16 @@ Docs live in /docs, written in Markdown. Contributions follow the Sumo Logic sty - .claude/skills/docusaurus/SKILL.md — Docusaurus 3 syntax, frontmatter templates, and sidebar config patterns. - .claude/skills/pr-template-guide/SKILL.md — PR template structure, formatting examples, and best practices. +## Bulk Changes +For any change touching 50+ files (terminology migrations, frontmatter audits, link updates, admonition format changes), follow these rules — lessons distilled from the DOCS-63 post-mortem: + +1. **Define scope first, get sign-off.** State the exact pattern, included paths, excluded paths, and known edge cases before touching files. +2. **Dry-run before writing.** Report total file count, per-directory breakdown, and ~10 before/after samples. Wait for confirmation. +3. **Apply in batches by directory**, not all at once. Show `git diff --stat` and a few spot-checks after each batch. +4. **One commit per batch/category** — never bundle multiple directories into one commit. Atomic commits stay revertable. +5. **Never revert from memory.** If reverting, validate against actual file content — do not trust "the original had X." +6. **Never commit helper/detection scripts** to the repo. Run them ephemerally. + ## Pull Requests **CRITICAL REQUIREMENT**: Before creating ANY PR, MUST read `.github/PULL_REQUEST_TEMPLATE.md` and use EXACT checkbox labels from that file. diff --git a/docs/api/mcp-server.md b/docs/api/mcp-server.md index 09e69d5816..a2ba1fe1cc 100644 --- a/docs/api/mcp-server.md +++ b/docs/api/mcp-server.md @@ -25,7 +25,8 @@ The Sumo Logic MCP server lets MCP clients (external AI models) connect to Sumo ## Prerequisites * **Sumo Logic Administrator role**. You'll need this to create OAuth clients. If you're unsure whether you have this role, check your [Preferences](/docs/get-started/onboarding-checklists/). -* **Sumo Logic OAuth credentials**. The MCP client uses [OAuth credentials](/docs/manage/security/oauth) to authenticate with Sumo Logic. For Claude Code CLI, you'll create them during the setup steps below. + +* **Sumo Logic OAuth client credentials**. The MCP client uses [OAuth client credentials](/docs/manage/security/oauth) to authenticate with Sumo Logic. For Claude Code CLI, you'll create them during the setup steps below. * **MCP server URL for your deployment**. OAuth tokens are deployment-bound, so you must use the correct URL for your Sumo Logic deployment: | Deployment | MCP Server URL | | :--- | :--- | @@ -44,6 +45,9 @@ The Sumo Logic MCP server lets MCP clients (external AI models) connect to Sumo ## Known limitations + + +* **Cursor**. Cursor requires redirect URLs starting with `cursor://`, which is not yet supported by the Sumo Logic authorization server. * **VS Code**. Recent VS Code releases do not work with the authorization code flow when an explicit client ID and secret are provided. :::note diff --git a/yarn.lock b/yarn.lock index cdde9ac751..7b3b1562aa 100644 --- a/yarn.lock +++ b/yarn.lock @@ -14804,6 +14804,9 @@ webpack-dev-server@^5.2.2: version "5.2.5" resolved "https://registry.yarnpkg.com/webpack-dev-server/-/webpack-dev-server-5.2.5.tgz#648fceaac6a5736b0935e5c1e55d6aa1d0626119" integrity sha512-4wZtCquSuv9CKX8oybo+mqxtxZqWz47uM1Ch94lxowBztOhWCbhqvRbfC/mODOwxgV2brY+JGZpHq58/SuVFYg== + version "5.2.4" + resolved "https://registry.yarnpkg.com/webpack-dev-server/-/webpack-dev-server-5.2.4.tgz#6e6306ce59848ed322c235e48b326632b1eed6d6" + integrity sha512-GqDPGZN9bRqKBTkp4aWkobDDHMsrXKoGSdOH56smIri8qR0JG8gfL8/v/f/OZR3/OKXjG8uwJbFVhKm/FNU/UA== dependencies: "@types/bonjour" "^3.5.13" "@types/connect-history-api-fallback" "^1.5.4" From bfeaf8463b4658a5ba2d980f75763edb6a3a823e Mon Sep 17 00:00:00 2001 From: Kim Pohas Date: Mon, 8 Jun 2026 07:20:22 -0700 Subject: [PATCH 17/22] DOCS-1640 - Improve Claude command files per agentskills.io guidance MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - audit-doc, doc, seo-audit: replace generic "What this command does" steps with imperative descriptions and a Gotchas section - audit-doc: fix heading case rule (H1 Title Case, H2–H4 sentence case); restore redundant when-to-use bullet - seo-audit: restore dropped checks (anchor text, bare URLs, missing alt, Critical table rows) - CLAUDE.md: add plan mode requirement for bulk changes; clarify bulk change examples with e.g.; remove opaque DOCS-63 reference Co-Authored-By: Claude Sonnet 4.6 --- .claude/commands/audit-doc.md | 19 ++++++------------- .claude/commands/doc.md | 14 +------------- .claude/commands/seo-audit.md | 9 ++++++++- CLAUDE.md | 4 +++- 4 files changed, 18 insertions(+), 28 deletions(-) diff --git a/.claude/commands/audit-doc.md b/.claude/commands/audit-doc.md index b17f5dd32c..ec84e788ba 100644 --- a/.claude/commands/audit-doc.md +++ b/.claude/commands/audit-doc.md @@ -1,18 +1,12 @@ # Audit Doc — Documentation Quality Check -Performs comprehensive quality checks on documentation files to ensure adherence to Sumo Logic style guidelines, proper structure, and completeness. +Use this command to audit a doc for style, structure, links, and frontmatter compliance — run it before submitting any PR, after creating a new doc, or when reviewing community contributions. -## What this command does +## Gotchas -When you invoke `/audit-doc`, Claude will: - -1. **Read and analyze the specified doc file** -2. **Check frontmatter**. Validate required fields and format -3. **Review content structure**. Check headings, sections, and organization -4. **Validate links and images**. Check paths, alt text, and references -5. **Check style adherence**. Apply Sumo Logic style guide rules -6. **Report findings**. Provide detailed feedback with specific line numbers -7. **Suggest fixes**. Offer actionable recommendations +- H1 headings and the `title` frontmatter field use **Title Case**. H2, H3, H4 use **sentence case** (only first word and proper nouns capitalized). +- Skip warnings for legacy docs with an established style, docs tagged `noindex` (temporary drafts), or third-party content not meant to be modified. +- `/audit-doc` does not check SEO/AEO/GEO signals — run `/seo-audit` separately for discoverability. ## When to use this command @@ -20,7 +14,6 @@ When you invoke `/audit-doc`, Claude will: * After creating a new doc to validate structure * When updating existing docs to ensure consistency * To identify broken links or missing images -* To verify adherence to Sumo Logic style guidelines * When reviewing community contributions ## Workflow @@ -67,7 +60,7 @@ Check for required fields and proper formatting: * [ ] Only one H1 heading (the title in frontmatter) * [ ] H2 sections used for main sections * [ ] No skipped heading levels (H2 → H4 without H3) -* [ ] Headings use sentence case (only first word and proper nouns capitalized) +* [ ] H1 uses Title Case; H2, H3, H4 use sentence case (only first word and proper nouns capitalized) **Required sections (by doc type):** diff --git a/.claude/commands/doc.md b/.claude/commands/doc.md index e5f3fb9bbc..17b08c3e31 100644 --- a/.claude/commands/doc.md +++ b/.claude/commands/doc.md @@ -1,18 +1,6 @@ # Create New Doc -Automates the creation of general Sumo Logic documentation for features, how-tos, concepts, reference pages, and troubleshooting guides. - -## What this command does - -When you invoke `doc`, Claude will guide you through: - -1. **Determine doc type**. Feature, how-to, concept, reference, or troubleshooting. -2. **Gather information**. Title, description, file path, and keywords. -3. **Create markdown file**. Generate file with proper frontmatter and basic structure. -4. **Add to navigation**. Guide on adding to sidebars.ts. -5. **Add to hub page**. Suggest adding card to parent index page. -6. **Create CID mapping**. Add permanent URL if needed for UI links. -7. **Validate and preview**. Check structure and provide next steps. +Use this command to create a new feature doc, how-to, concept, reference, or troubleshooting guide — it scaffolds the file, frontmatter, structure, and sidebar entry. ## When to use this command diff --git a/.claude/commands/seo-audit.md b/.claude/commands/seo-audit.md index 99b145871b..2583017dfb 100644 --- a/.claude/commands/seo-audit.md +++ b/.claude/commands/seo-audit.md @@ -1,6 +1,6 @@ # SEO/AEO/GEO Audit — Search and AI Discoverability Check -Audits documentation for search engine optimization (SEO), answer engine optimization (AEO), and generative engine optimization (GEO) signals. Produces a prioritized report and offers to apply fixes. +Use this command to audit a doc for SEO, AEO, and GEO signals — run it before any PR on new or updated content, even if you're not focused on search optimization. ## Signal definitions @@ -45,9 +45,12 @@ Use the Read tool to read the complete file content including frontmatter. * [ ] First paragraph (after frontmatter) is substantive — tells the reader what the doc covers, why it matters, and who it is for — **Warning** if it is thin (under 50 words) or just restates the title * [ ] Page has at least one internal link to a related doc — **Warning** if none +* [ ] Internal link anchor text is descriptive (not "click here" or "here") — **Warning** if bare +* [ ] No bare external URLs — wrap in markdown link syntax — **Warning** if present **Images** +* [ ] All images have non-empty `alt` text — **Critical** if missing * [ ] Alt text describes the image content, not just "screenshot" or the filename — **Warning** if generic ### Step 4: Run AEO checks @@ -129,7 +132,11 @@ Do not modify files without explicit user approval. | Issue | Why it matters | |-------|---------------| +| Missing `description` | Search engines cannot generate a preview snippet; AI tools have no summary to cite | +| Missing `title` | Page cannot be indexed or linked properly | | `title` over 60 chars | Truncated in search results; first 60 chars carry the most weight | +| H1 in body | Duplicate H1 confuses search engines and breaks page structure | +| Missing image alt text | Accessibility failure; images are invisible to search crawlers | | `slug` on regular page | Overrides URL derived from file path; breaks sidebar linking | ### Warnings diff --git a/CLAUDE.md b/CLAUDE.md index 7219f2f3e9..557a1b28d6 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -16,7 +16,9 @@ Docs live in /docs, written in Markdown. Contributions follow the Sumo Logic sty - .claude/skills/pr-template-guide/SKILL.md — PR template structure, formatting examples, and best practices. ## Bulk Changes -For any change touching 50+ files (terminology migrations, frontmatter audits, link updates, admonition format changes), follow these rules — lessons distilled from the DOCS-63 post-mortem: +For any change touching 50+ files (e.g. terminology migrations, frontmatter audits, link updates, admonition format changes), follow these rules: + +**Enter plan mode** (`/plan`) at the start of any bulk change. Present scope, file count, directory breakdown, and before/after samples — then wait for explicit approval before touching any files. 1. **Define scope first, get sign-off.** State the exact pattern, included paths, excluded paths, and known edge cases before touching files. 2. **Dry-run before writing.** Report total file count, per-directory breakdown, and ~10 before/after samples. Wait for confirmation. From 3a3096117a8777dc7ffdebdf1e43eacc30c159c4 Mon Sep 17 00:00:00 2001 From: Kim Pohas Date: Mon, 8 Jun 2026 11:05:05 -0700 Subject: [PATCH 18/22] DOCS-1640 - Add Doc Reviews section with integrations directory example Co-Authored-By: Claude Sonnet 4.6 --- CLAUDE.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 557a1b28d6..219708e2d0 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -27,6 +27,12 @@ For any change touching 50+ files (e.g. terminology migrations, frontmatter audi 5. **Never revert from memory.** If reverting, validate against actual file content — do not trust "the original had X." 6. **Never commit helper/detection scripts** to the repo. Run them ephemerally. +## Doc Reviews + +When reviewing any PR or doc, always check existing docs of the same type in the same directory before flagging issues. A pattern consistent with neighboring docs is not a bug — it is the established convention. Only flag it if it's a deviation from the pattern or a net-new problem introduced by the PR. + +Some directories have conventions that differ significantly from standard docs. For example, `docs/platform-services/automation-service/app-central/integrations/` intentionally uses `description: ''`, omits `id`, opens with a logo image, and includes a `***Version / Updated***` block — all correct for that directory. When in doubt, read two or three neighboring files before forming an opinion. + ## Pull Requests **CRITICAL REQUIREMENT**: Before creating ANY PR, MUST read `.github/PULL_REQUEST_TEMPLATE.md` and use EXACT checkbox labels from that file. From 371190dec811c4fc475327def023eb4284aef441 Mon Sep 17 00:00:00 2001 From: Kim Pohas Date: Wed, 24 Jun 2026 19:14:46 -0700 Subject: [PATCH 19/22] Fix duplicate webpack-dev-server entry in yarn.lock and restore mcp-server.md to main Co-Authored-By: Claude Sonnet 4.6 --- docs/api/mcp-server.md | 6 +----- yarn.lock | 3 --- 2 files changed, 1 insertion(+), 8 deletions(-) diff --git a/docs/api/mcp-server.md b/docs/api/mcp-server.md index a2ba1fe1cc..09e69d5816 100644 --- a/docs/api/mcp-server.md +++ b/docs/api/mcp-server.md @@ -25,8 +25,7 @@ The Sumo Logic MCP server lets MCP clients (external AI models) connect to Sumo ## Prerequisites * **Sumo Logic Administrator role**. You'll need this to create OAuth clients. If you're unsure whether you have this role, check your [Preferences](/docs/get-started/onboarding-checklists/). - -* **Sumo Logic OAuth client credentials**. The MCP client uses [OAuth client credentials](/docs/manage/security/oauth) to authenticate with Sumo Logic. For Claude Code CLI, you'll create them during the setup steps below. +* **Sumo Logic OAuth credentials**. The MCP client uses [OAuth credentials](/docs/manage/security/oauth) to authenticate with Sumo Logic. For Claude Code CLI, you'll create them during the setup steps below. * **MCP server URL for your deployment**. OAuth tokens are deployment-bound, so you must use the correct URL for your Sumo Logic deployment: | Deployment | MCP Server URL | | :--- | :--- | @@ -45,9 +44,6 @@ The Sumo Logic MCP server lets MCP clients (external AI models) connect to Sumo ## Known limitations - - -* **Cursor**. Cursor requires redirect URLs starting with `cursor://`, which is not yet supported by the Sumo Logic authorization server. * **VS Code**. Recent VS Code releases do not work with the authorization code flow when an explicit client ID and secret are provided. :::note diff --git a/yarn.lock b/yarn.lock index 7b3b1562aa..cdde9ac751 100644 --- a/yarn.lock +++ b/yarn.lock @@ -14804,9 +14804,6 @@ webpack-dev-server@^5.2.2: version "5.2.5" resolved "https://registry.yarnpkg.com/webpack-dev-server/-/webpack-dev-server-5.2.5.tgz#648fceaac6a5736b0935e5c1e55d6aa1d0626119" integrity sha512-4wZtCquSuv9CKX8oybo+mqxtxZqWz47uM1Ch94lxowBztOhWCbhqvRbfC/mODOwxgV2brY+JGZpHq58/SuVFYg== - version "5.2.4" - resolved "https://registry.yarnpkg.com/webpack-dev-server/-/webpack-dev-server-5.2.4.tgz#6e6306ce59848ed322c235e48b326632b1eed6d6" - integrity sha512-GqDPGZN9bRqKBTkp4aWkobDDHMsrXKoGSdOH56smIri8qR0JG8gfL8/v/f/OZR3/OKXjG8uwJbFVhKm/FNU/UA== dependencies: "@types/bonjour" "^3.5.13" "@types/connect-history-api-fallback" "^1.5.4" From 486c58a8483f4c78bab1ad93ca1a973bb6200837 Mon Sep 17 00:00:00 2001 From: Kim <56411016+kimsauce@users.noreply.github.com> Date: Wed, 24 Jun 2026 19:15:22 -0700 Subject: [PATCH 20/22] Apply suggestion from @kimsauce --- CLAUDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index dd2f5cc81b..24e25a6c97 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -64,7 +64,7 @@ Before pushing any commit that changes docs content: ### Field Requirements - **Assignee**: Do not set manually — Jira Automation assigns based on Technical Area. - **Technical Area**: REQUIRED field. Must be set from allowed values. Use file paths and content keywords to determine the correct area (see `.claude/commands/jira.md` for mappings). -- **Existing Tech Docs Link** (`customfield_10750`): +- **Existing Tech Docs Link** (`customfield_10750`): - REQUIRED when transitioning to Published status - MUST be populated when creating or updating tickets that touch existing articles - Use full production URL (e.g., `https://www.sumologic.com/help/docs/get-started/training-certification-faq`) From 40918571c43b479bc1a43a20381c81d1d5875ab8 Mon Sep 17 00:00:00 2001 From: Kim Pohas Date: Wed, 24 Jun 2026 22:45:04 -0700 Subject: [PATCH 21/22] DOCS-1640 - Fix seo-audit checklist regressions and remove stale command references Restore Critical SEO checks dropped during deduplication (title present, description present, No H1 in body) and remove stale references to deleted commands (/tone-check, /rewrite-intro, /simplify) from CLAUDE.md and geo-optimize.md. Co-Authored-By: Claude Sonnet 4.6 --- .claude/commands/geo-optimize.md | 5 ++--- .claude/commands/seo-audit.md | 5 ++++- CLAUDE.md | 2 +- 3 files changed, 7 insertions(+), 5 deletions(-) diff --git a/.claude/commands/geo-optimize.md b/.claude/commands/geo-optimize.md index 6710532404..1b28d98764 100644 --- a/.claude/commands/geo-optimize.md +++ b/.claude/commands/geo-optimize.md @@ -125,8 +125,7 @@ After the user confirms which changes to make: After applying changes, tell the user: - Which checks in `/seo-audit` this resolves -- Whether any remaining GEO suggestions need a larger rewrite (offer `/rewrite-intro` if the opening paragraph needed major work) -- Whether the doc would benefit from a `/tone-check` pass afterward +- Whether any remaining GEO suggestions need a larger rewrite (offer to rewrite the opening paragraph if it needed major work) --- @@ -227,4 +226,4 @@ After the first use, the abbreviation alone is fine. * Preserve technical accuracy above all else — if a rewrite would require fact-checking, flag it and ask the user to verify * Do not alter frontmatter except `description` if explicitly requested * Keep the Sumo Logic voice — do not make the doc sound like a Wikipedia article -* If a section is very long and difficult to restructure safely, recommend `/rewrite-intro` or `/simplify` instead of attempting a full rewrite here +* If a section is very long and difficult to restructure safely, flag it and ask the user how they'd like to proceed instead of attempting a full rewrite here diff --git a/.claude/commands/seo-audit.md b/.claude/commands/seo-audit.md index 2583017dfb..4aed35f5ec 100644 --- a/.claude/commands/seo-audit.md +++ b/.claude/commands/seo-audit.md @@ -28,8 +28,10 @@ Use the Read tool to read the complete file content including frontmatter. **Frontmatter** -* [ ] `title` is under 60 characters — **Critical** if over 60 +* [ ] `title` present +* [ ] `title` is under 60 characters — **Critical** if missing or over 60 * [ ] `title` includes the primary keyword or product/feature name +* [ ] `description` present — **Critical** if missing * [ ] `description` is 140–160 characters — **Warning** if shorter than 100 or longer than 160 * [ ] `description` leads with an action verb or product name (not "This page" or "This doc") * [ ] `keywords` field present with 3–5 relevant terms — **Suggestion** if missing @@ -37,6 +39,7 @@ Use the Read tool to read the complete file content including frontmatter. **Headings** +* [ ] No H1 in body — title frontmatter generates H1; a second H1 breaks SEO — **Critical** if present * [ ] At least 2 H2 headings for pages over 500 words — **Suggestion** if none * [ ] No duplicate headings at the same level — **Warning** if duplicated * [ ] Headings are under 60 characters — **Suggestion** if over diff --git a/CLAUDE.md b/CLAUDE.md index 24e25a6c97..12ed92aa87 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -92,7 +92,7 @@ Primary commands for documentation work. Proactively suggest when context fits **Content:** `/doc`, `/doc-from-jira`, `/app-doc`, `/c2c-source-doc`, `/remove-doc` **Release notes:** `/release-note-service`, `/release-note-collector`, `/release-note-cse`, `/release-note-csoar`, `/release-note-developer` -**Quality:** `/audit-doc`, `/seo-audit`, `/geo-optimize`, `/tone-check`, `/rewrite-intro`, `/simplify` +**Quality:** `/audit-doc`, `/seo-audit`, `/geo-optimize` **Workflow:** `/jira`, `/review` **When to proactively suggest:** From d35c926a791080b3d16f9c5c7380eb5fd41e7ab1 Mon Sep 17 00:00:00 2001 From: Kim Pohas Date: Wed, 24 Jun 2026 23:02:27 -0700 Subject: [PATCH 22/22] DOCS-1640 - Minor cleanup to audit-doc.md intro and related commands section Co-Authored-By: Claude Sonnet 4.6 --- .claude/commands/audit-doc.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/.claude/commands/audit-doc.md b/.claude/commands/audit-doc.md index ec84e788ba..ebdc0288ad 100644 --- a/.claude/commands/audit-doc.md +++ b/.claude/commands/audit-doc.md @@ -1,6 +1,6 @@ # Audit Doc — Documentation Quality Check -Use this command to audit a doc for style, structure, links, and frontmatter compliance — run it before submitting any PR, after creating a new doc, or when reviewing community contributions. +Use this command to audit a doc for Sumo Logic style, structure, links, and frontmatter compliance — run it before submitting any PR, after creating a new doc, or when reviewing community contributions. ## Gotchas @@ -368,8 +368,7 @@ Track common issues across multiple audits to identify systemic problems. ## Related commands -`/audit-doc` covers structure, style, links, frontmatter, and required sections. It does not -check SEO/AEO/GEO signals. For discoverability, run both: +`/audit-doc` covers structure, style, links, frontmatter, and required sections. It does not check SEO/AEO/GEO signals. For discoverability, run both: * **`/seo-audit`** — checks title length, description quality, question headings, GEO patterns * **`/geo-optimize`** — rewrites content to improve AI citation and search visibility