Sync open source content 🐝 (from 845bef37211a5ab95c35642c3365ae328c2bffd3)

Author: beezythebot

api-design/versioning.mdx

@@ -1,16 +1,17 @@
 ---
-title: Configuring module format
+title: Configuring Module Format
+description: "Learn to configure module formats for SDKs."
 ---
 
 import { Callout } from "@/mdx/components";
 
-# Configuring Module Format
+# Configuring module format
 
 Modern SDKs need to balance compatibility with performance. The `moduleFormat` option in the SDK generator allows developers to control whether an SDK is built for CommonJS (CJS), ECMAScript Modules (ESM), or both. This choice impacts bundle size, tree-shaking performance, and compatibility with Node.js and modern bundlers.
 
-## How to Configure Module Format
+## How to configure module format
 
-To configure the module format, update `gen.yaml` (which is often located in the SDK's `.speakeasy` directory) file under the `typescript` section:
+To configure the module format, update the `typescript` section of your `gen.yaml` file (which is often located in the SDK's `.speakeasy` directory):
 
 ```yaml <sdk-root>/.speakeasy/gen.yaml
 typescript:
@@ -19,26 +20,30 @@ typescript:
   # other Typescript configuration options...
 ```
 
-### Supported Options
+### Supported options
 
-- **`"commonjs"` (default)**: Builds SDK for CommonJS. Widely supported across Node.js environments but less optimized for modern bundlers and tree-shaking.
-- **`"esm"`**: Builds SDK for ECMAScript Modules, the modern standard for JavaScript modules. Provides optimal tree-shaking and significantly smaller bundles when used with bundlers like Webpack, Rollup, or Vite.
-- **`"dual"`**: Builds SDK for both CJS and ESM formats. Provides the best of both worlds - ESM's superior tree-shaking and bundle optimization while maintaining compatibility with older CommonJS environments. The slight build time increase is often worth the flexibility and performance benefits.
+Select one of the supported module formats:
 
-## Module Format Overview
+- `"commonjs"` is the default option. It builds SDKs for CommonJS. CJS is widely supported across Node.js environments, but it's less optimized for modern bundlers and tree-shaking.
+- `"esm"` is the modern standard for JavaScript modules. It builds SDKs for ECMAScript Modules. ESM provides optimal tree-shaking and significantly smaller bundles when used with bundlers like Webpack, Rollup, or Vite.
+- `"dual"` provides the best of both worlds. By building SDKs for both CJS and ESM formats, it offers  ESM's superior tree-shaking and bundle optimization while maintaining compatibility with older CJS environments. The slight build time increase is often worth the flexibility and performance benefits.
 
-`moduleFormat` determines the module system targeted during SDK build. It impacts:
+## Module format overview
 
-- Node.js project compatibility,
-- Bundler tree-shaking capabilities,
-- SDK bundle size, and
-- Build performance.
+The `moduleFormat` determines the module system targeted during SDK building. It impacts:
 
-### Example Outputs for Each Option
+- Node.js project compatibility
+- Bundler tree-shaking capabilities
+- SDK bundle size
+- Build performance
 
-#### CommonJS (Default)
+### Example outputs
 
-When configured with `commonjs`:
+Review the different outputs generated for each module format.
+
+#### CJS
+
+The `commonjs` module format outputs the following:
 
 ```javascript example.js
 // CommonJS import in consumer code
@@ -50,7 +55,7 @@ import { ApiError } from "petstore/errors/apierror.js";
 
 #### ESM
 
-When configured with `esm`:
+The `esm` module format outputs the following:
 
 ```javascript example.js
 // Native ESM import in consumer code
@@ -61,7 +66,7 @@ import { ApiError } from "petstore/errors/apierror.js";
 
 #### Dual
 
-When configured with `dual`:
+The `dual` module format outputs the following:
 
 ```javascript example.js
 // ESM import (no interop code)
@@ -71,33 +76,33 @@ import { ApiError } from "petstore/errors/apierror.js";
 const { ApiError } = require("petstore/errors/apierror.js");
 ```
 
-## How to Decide Which Format to Use
+## How to decide which format to use
 
-**Use CommonJS (`commonjs`) if...**
+We recommend using CJS (`commonjs`) if:
 
 - The SDK is used primarily in Node.js environments or older projects.
 - Bundle size optimization is not a critical requirement.
-- Maximum compatibility with legacy systems is required.
+- You require maximum compatibility with legacy systems.
 
-**Use ESM (`esm`) if...**
+We recommend using ESM (`esm`) if:
 
-- SDK consumers use modern bundlers like Vite, Webpack, or Rollup.
+- The SDK consumers use modern bundlers like Vite, Webpack, or Rollup.
 - Tree-shaking and bundle size optimization are top priorities.
 - The project already uses ESM throughout.
 - Leveraging the latest JavaScript features and tooling is important.
 
-**Use Dual Mode (`dual`) if...**
+We recommend using both (`dual`) if:
 
-- Support for both modern and legacy environments is required.
-- ESM's superior tree-shaking while maintaining CommonJS compatibility is desired.
-- The SDK will be used in diverse environments with different module requirements.
+- You require support for both modern and legacy environments.
+- You need ESM's superior tree-shaking while maintaining CJS compatibility.
+- The SDK is used in diverse environments with different module requirements.
 - Developer experience and maximum flexibility are priorities.
 
 <Callout title="Recommendation" type="info">
-For most modern projects, the `dual` format is recommended. This ensures the SDK works seamlessly in any environment while still providing the performance benefits of ESM when used with modern bundlers.
+For most modern projects, the `dual` format is best. It ensures the SDK works smoothly in any environment, while still providing the performance benefits of ESM when used with modern bundlers.
 </Callout>
 
-## Additional Reading
+## Additional reading
 
-- [Typescript Configuration Options](/docs/gen-reference/ts-config)
-- [Lean SDKs with Standalone Functions](/post/standalone-functions)
+- [TypeScript configuration options](/docs/gen-reference/ts-config)
+- [Lean SDKs with standalone functions](/post/standalone-functions)

docs/customize/typescript/configuring-module-format.mdx

@@ -1,21 +1,30 @@
+---
+title: Populate Code Samples Without GitHub Actions
+description: "Learn to use the CLI to populate code samples without GitHub Actions."
+---
+
 # Using the CLI to populate code samples without GitHub Actions
 
 This guide explains how to use the Speakeasy CLI to generate and publish code samples for your API documentation when you're not using GitHub Actions.
 
 ## Overview
 
-Speakeasy can automatically generate code samples for your OpenAPI specification and make them available via a public URL that can be integrated with documentation platforms like Scalar. While this process is typically automated with GitHub Actions, you can achieve the same result using just the CLI in your own custom workflows.
+Speakeasy automatically generates code samples for your OpenAPI document and makes them available via a public URL that can be integrated with documentation platforms like Scalar. While this process is typically automated with GitHub Actions, you can achieve the same result using just the Speakeasy CLI in your own custom workflow.
 
 ## Prerequisites
 
-- Speakeasy CLI installed
-- An OpenAPI specification
-- A Speakeasy account and API key
-- **CI environment**: The generation must run from a CI environment or with the `CI_ENABLED` environment variable set to `true`
+To follow this guide, you need:
+
+- **The Speakeasy CLI:** Install the CLI on your computer.
+- **An OpenAPI document:** Speakeasy generates your SDKs based on your OpenAPI document
+- **A Speakeasy account and API key:** Ensure you have access to the Speakeasy workspace.
+- **A CI environment:** The generation must run from a CI environment or with the `CI_ENABLED` environment variable set to `true`.
 
-## Step-by-step process
+## Generating code samples with the Speakeasy CLI
 
-### 1. Configure your workflow
+Follow these steps to populate your OpenAPI document and make it available for use with documentation platforms:
+
+### Configure your workflow
 
 First, set up your workflow configuration file:
 
@@ -25,7 +34,7 @@ speakeasy configure
 
 This creates a `.speakeasy/workflow.yaml` file that defines your SDK generation targets and code samples configuration.
 
-### 2. Generate SDKs and code samples
+### Generate SDKs and code samples
 
 Run the Speakeasy CLI to generate your SDKs and code samples:
 
@@ -34,55 +43,56 @@ speakeasy run
 ```
 
 This command:
+
 - Downloads or loads your OpenAPI document
 - Validates the OpenAPI document
 - Generates SDKs for your configured languages
 - Creates code samples for each operation in your API
 
-### 3. Promote code samples to main
+### Promote code samples to main
 
-The critical step for enabling automated code samples is to tag both your source specification and generated code samples with the `main` tag:
+The critical step for enabling automated code samples is to tag both your source specification (OpenAPI document) and generated code samples with the `main` tag:
 
 ```bash
 speakeasy tag promote -s my-source-name -c my-target-name -t main
 ```
 
-This command tags both the source specification (`-s my-source-name`) and the generated code samples (`-c my-target-name`) as "official" so they can be incorporated into the public URL. Similar to how the `main` branch in GitHub represents the production-ready version of your code, the `main` tag in Speakeasy indicates these are the production-ready specifications and code samples that should be publicly available. Replace `my-source-name` and `my-target-name` with the names as defined in your workflow configuration.
+This command tags both the source OpenAPI document (`-s my-source-name`) and the generated code samples (`-c my-target-name`) as "official" so they can be incorporated into the public URL. Similar to how the `main` branch in GitHub represents the production-ready version of your code, the `main` tag in Speakeasy indicates these are the production-ready specifications and code samples that should be publicly available. Replace `my-source-name` and `my-target-name` with the names defined in your workflow configuration.
 
-### 4. Access the public URL
+### Access the public URL
 
-Once you've tagged your code samples with `main`, Speakeasy will automatically start building a combined spec in the background. The combined spec will be available at a public URL that you can use with documentation platforms like Scalar.
+Once you've tagged your code samples with `main`, Speakeasy automatically starts building a combined OpenAPI document in the background. The combined document is available at a public URL that you can use with documentation platforms like Scalar.
 
-To find this URL, you'll need to visit the Speakeasy dashboard and navigate to the **Docs** tab. Click on **Integrate with Docs Provider** to see the URL to the OpenAPI with code samples combined. Currently, there's no CLI command to retrieve this URL programmatically.
+To find this URL, open the Speakeasy workspace and navigate to the **Docs** tab. Click **Integrate with Docs Provider** to see the URL to the combined OpenAPI document with populated code samples. Currently, there's no CLI command to retrieve this URL programmatically.
 
-### 5. Integrate with docs providers
+### Integrate with docs providers
 
 Once you have the public URL, you can integrate it with various documentation providers. Speakeasy offers detailed integration guides for several popular docs platforms:
 
-- [Scalar](/docs/sdk-docs/integrations/scalar) - A modern API documentation platform
-- [ReadMe](/docs/sdk-docs/integrations/readme) - Interactive API explorer and documentation
-- [Mintlify](/docs/sdk-docs/integrations/mintlify) - Developer documentation with an interactive playground
-- [Bump.sh](/docs/sdk-docs/integrations/bump) - Hosted API documentation and catalogs
+- [Scalar](/docs/sdk-docs/integrations/scalar) is a modern API documentation platform.
+- [ReadMe](/docs/sdk-docs/integrations/readme) offers an interactive API explorer and documentation.
+- [Mintlify](/docs/sdk-docs/integrations/mintlify) provides developer documentation with an interactive playground.
+- [Bump.sh](/docs/sdk-docs/integrations/bump) hosts API documentation and catalogs.
 
 ## Automating the process
 
-For a fully automated workflow without GitHub Actions:
+Use the following steps to create a fully automated workflow without GitHub Actions:
 
-1. Create a script or CI pipeline that runs `speakeasy run` to generate SDKs and code samples
-2. Add `speakeasy tag promote -s my-source-name -c my-target-name -t main` to tag both the source specification and generated code samples
-3. The public URL will automatically update with the latest code samples
+- Create a script or CI pipeline that runs `speakeasy run` to generate SDKs and code samples.
+- Add `speakeasy tag promote -s my-source-name -c my-target-name -t main` to tag both the source OpenAPI document and generated code samples.
+- The public URL automatically updates the OpenAPI document with the latest code samples.
 
 ### Why use CLI tagging instead of GitHub Actions?
 
 While GitHub Actions provides a convenient way to automate code sample generation and tagging, the CLI approach offers several advantages for teams:
 
-- **Platform independence**: Use any CI/CD system (Jenkins, GitLab CI, CircleCI, Azure DevOps) instead of being limited to GitHub Actions
-- **Custom workflows**: Integrate code sample generation into existing build processes or deployment pipelines
-- **Local development**: Generate and test code samples locally before pushing changes
-- **Private repositories**: Work with code that isn't hosted on GitHub or is in private repositories with restricted access
-- **Enterprise environments**: Support for organizations with specific security or compliance requirements that prevent using GitHub Actions
+- **Platform independence:** Use any CI/CD system (such as Jenkins, GitLab CI, CircleCI, or Azure DevOps) instead of being limited to GitHub Actions.
+- **Custom workflows:** Integrate code sample generation into existing build processes or deployment pipelines.
+- **Local development:** Generate and test code samples locally before pushing changes.
+- **Private repositories:** Work with code that isn't hosted on GitHub or is hosted in private repositories with restricted access.
+- **Enterprise environments:** Provide support for organizations with specific security or compliance requirements that prevent them from using GitHub Actions.
 
-## Example workflow script
+### Example workflow script
 
 Here's a simple bash script example that could be used in a custom CI pipeline:
 

docs/guides/code-samples-without-github-actions.md

@@ -1,61 +1,48 @@
 ---
-title: Handling breaking changes in SDKs
-description: > 
-  Learn how to handle breaking changes in APIs when using
-  Speakeasy-generated SDKs.
+title: Handling Breaking Changes in SDKs
+description: "Learn how to handle breaking changes in APIs when using Speakeasy-generated SDKs."
 ---
 
 import { Callout } from "@/mdx/components";
 
 # Handling breaking changes in SDKs
 
-This guide explains how to handle breaking changes in APIs when using
-Speakeasy-generated SDKs. Following these guidelines helps maintain backward
-compatibility and ensures a smooth experience for SDK users.
+This guide explains how to handle breaking changes in APIs when using Speakeasy-generated SDKs. Follow these guidelines to maintain backward compatibility and ensure a smooth experience for your SDK users.
 
 ## Safe changes
 
 The following API changes are safe and won't break existing SDKs:
 
 ### Adding new fields
 
-Adding new fields to API responses is safe because older SDK versions ignore
-these fields. New response fields can be added without breaking existing
-integrations.
+You can safely add new fields to API responses because older SDK versions ignore these fields. Adding new response fields doesn't break existing integrations.
 
 ### Adding new enum values
 
-Adding new enum values is safe when enums are marked with
-`x-speakeasy-unknown-values` ([see enums customization doc](/docs/customize/data-model/enums#open-enums)). Older SDKs handle
-these new values gracefully according to the behavior specified in the
-extension configuration.
-
+You can safely add new enum values when enums are marked with `x-speakeasy-unknown-values` (see our [Customize enums](/docs/customize/data-model/enums#open-enums) documentation). Older SDKs handle these new values gracefully according to the behavior specified in the extension configuration.
 
 ## Changes requiring caution
 
-Some API changes require careful consideration to avoid breaking existing SDK
-implementations. Use the [OpenAPI diff tool](/docs/speakeasy-reference/cli/openapi/diff) to identify potential breaking
-changes in the API specification:
-
-
+Some API changes require careful consideration to avoid breaking existing SDK implementations. Use the [OpenAPI diff tool](/docs/speakeasy-reference/cli/openapi/diff) to identify potential breaking changes in your API specification.
 
 ### Deprecating required fields
 
-When deprecating fields marked as required in the API specification:
-- Older SDKs throw validation errors if the field is missing
-- Make the field optional before removing it
-- Plan a deprecation period for implementation updates
+Take care when deprecating fields marked as required in the API specification. Older SDKs may throw validation errors if required fields are missing:
+
+- Make the field optional before removing it.
+- Plan a deprecation period for implementation updates.
 
 ### Modifying oneOf schemas
 
-Make changes to `oneOf` schemas carefully:
-- Adding new variants may cause type mismatch errors in older SDKs
-- Maintain backward compatibility with existing schema variants
-- Test changes thoroughly with older SDK versions
+Make changes to `oneOf` schemas carefully, as adding new variants may cause type mismatch errors in older SDKs:
+
+- Maintain backward compatibility with existing schema variants.
+- Test changes thoroughly with older SDK versions.
 
 ## Future improvements
 
-Speakeasy is developing additional features to help manage breaking changes:
+Speakeasy is developing additional features to help you manage breaking changes, including:
+
 - SDK version upgrade prompts
 - Improved tooling for breaking changes
 - Enhanced version management capabilities

docs/manage/breaking-changes.mdx

@@ -1,5 +1,5 @@
 ---
-title: SDK contract testing
+title: SDK Contract Testing
 description: "Learn how to generate and run automated testing for APIs and SDKs."
 ---