diff --git a/examples/typescript-sdk/generators.yml b/examples/typescript-sdk/generators.yml index 3b0f1fbe3..d66d8397a 100644 --- a/examples/typescript-sdk/generators.yml +++ b/examples/typescript-sdk/generators.yml @@ -1,5 +1,5 @@ # This file configures all of your SDKs. It should be located at: -# your-parent-repo/fern/generators.yml. +# your-source-repo/fern/generators.yml. default-group: local groups: local: diff --git a/examples/typescript-sdk/typescript-publish.yml b/examples/typescript-sdk/typescript-publish.yml index 50fe9f79c..2a8f87675 100644 --- a/examples/typescript-sdk/typescript-publish.yml +++ b/examples/typescript-sdk/typescript-publish.yml @@ -1,4 +1,4 @@ -# Add this file as: your-parent-repo/.github/workflows/typescript-publish.yml +# Add this file as: your-source-repo/.github/workflows/typescript-publish.yml # This workflow should be in the same repository as your generators.yml, which # should point to the repository containing your TypeScript SDK code. diff --git a/fern/docs.yml b/fern/docs.yml index b82be41df..630394d1f 100644 --- a/fern/docs.yml +++ b/fern/docs.yml @@ -240,6 +240,9 @@ redirects: - source: /learn/sdks/fern-folder destination: /learn/sdks/overview/quickstart permanent: true + - source: /learn/sdks/overview/github + destination: /learn/sdks/overview/project-structure + permanent: true - source: /learn/sdks/introduction/customer-showcase destination: /learn/sdks/customer-showcase permanent: true diff --git a/fern/products/api-def/pages/project-structure.mdx b/fern/products/api-def/pages/project-structure.mdx index 09cfb5ad2..a79cc5214 100644 --- a/fern/products/api-def/pages/project-structure.mdx +++ b/fern/products/api-def/pages/project-structure.mdx @@ -3,9 +3,11 @@ title: Project structure description: Describes the Fern folder structure --- -Configuring fern starts with the `fern` folder. The fern folder contains your API definitions, +Configuring fern starts with the `fern` folder, which contains your API definitions, SDK generators, and your CLI version. +Fern recommends a multi-repository structure with your fern folder in a source repository (containing your API definitions and generation configuration) and [each generated SDK in its own separate repository](/sdks/overview/project-structure). + ## Directory structure When you run `fern init` (for the Fern Definition) or `fern init --spec-type path/to/spec` (for other specs), your fern folder is initialized with the following files: @@ -39,7 +41,7 @@ determinism. ### `generators.yml` -The `generators.yml` file includes information about where your API definition file is located. It also [configures the SDKs](/sdks/overview/github) you're generating for your API. +The `generators.yml` file includes information about where your API definition file is located. It also [configures the SDKs](/sdks/overview/project-structure) you're generating for your API. ```yaml title="generators.yml" api: diff --git a/fern/products/docs/pages/getting-started/project-structure.mdx b/fern/products/docs/pages/getting-started/project-structure.mdx index e7690fa7a..3b54e33ea 100644 --- a/fern/products/docs/pages/getting-started/project-structure.mdx +++ b/fern/products/docs/pages/getting-started/project-structure.mdx @@ -166,7 +166,7 @@ title: Fern's Documentation - If you're using Fern for both API Reference documentation and SDKs, you'll use both `docs.yml` (the Docs configuration file) and `generators.yml` ([the SDK configuration file](/sdks/overview/github#generatorsyml)) to configure [how SDK code snippets appear](/docs/api-references/sdk-snippets) in your API reference documentation. + If you're using Fern for both API Reference documentation and SDKs, you'll use both `docs.yml` (the Docs configuration file) and `generators.yml` ([the SDK configuration file](/sdks/overview/project-structure#generatorsyml)) to configure [how SDK code snippets appear](/docs/api-references/sdk-snippets) in your API reference documentation. If you're only using Fern for API Reference docs, not SDKs, your `generators.yml` should simply link to your spec: diff --git a/fern/products/docs/pages/integrations/postman.mdx b/fern/products/docs/pages/integrations/postman.mdx index b60270097..efe30e898 100644 --- a/fern/products/docs/pages/integrations/postman.mdx +++ b/fern/products/docs/pages/integrations/postman.mdx @@ -6,7 +6,7 @@ description: "Generate a postman collection full of example requests and respons You can generate a Postman collection full of example requests and responses and publish your collection to Postman. The configuration for the postman generator lives in your fern folder, in a file called -[`generators.yml`](/sdks/overview/github#generatorsyml). +[`generators.yml`](/sdks/overview/project-structure#generatorsyml). ## Showcase diff --git a/fern/products/sdks/fern-folder.mdx b/fern/products/sdks/fern-folder.mdx index 2074a8abc..feaf0b927 100644 --- a/fern/products/sdks/fern-folder.mdx +++ b/fern/products/sdks/fern-folder.mdx @@ -29,6 +29,6 @@ your API definitions, generators, and your CLI version. ### Next: Set up your repository structure - Now that you have your `fern` folder initialized, [learn how to organize your repositories for SDK generation](/sdks/overview/github). + Now that you have your `fern` folder initialized, [learn how to organize your repositories for SDK generation](/sdks/overview/project-structure). diff --git a/fern/products/sdks/overview/typescript/publishing-to-npm.mdx b/fern/products/sdks/overview/typescript/publishing-to-npm.mdx index 323427f2d..b93e88f37 100644 --- a/fern/products/sdks/overview/typescript/publishing-to-npm.mdx +++ b/fern/products/sdks/overview/typescript/publishing-to-npm.mdx @@ -16,7 +16,7 @@ you'll have a versioned package published on npm. * An initialized `fern` folder. See [Set up the `fern` folder](/sdks/overview/quickstart). - * A GitHub repository for your TypeScript SDK. See [Project structure](/sdks/overview/github). + * A GitHub repository for your TypeScript SDK. See [Project structure](/sdks/overview/project-structure). * A TypeScript generator group in `generators.yml`. See [TypeScript Quickstart](quickstart#add-the-sdk-generator). @@ -24,7 +24,7 @@ you'll have a versioned package published on npm. ## Configure `generators.yml` -Your `generators.yml` [should live in your parent repository](/sdks/overview/github) (or on your local machine), not the repository that contains your TypeScript SDK code. +Your `generators.yml` [should live in your source repository](/sdks/overview/project-structure) (or on your local machine), not the repository that contains your TypeScript SDK code. @@ -168,7 +168,7 @@ Choose how you want to authenticate and publish your SDK to npm. You can use Git -Set up a release workflow via [GitHub Actions](https://docs.github.com/en/actions/get-started/quickstart) so you can trigger new SDK releases directly from your parent repository. +Set up a release workflow via [GitHub Actions](https://docs.github.com/en/actions/get-started/quickstart) so you can trigger new SDK releases directly from your source repository. diff --git a/fern/products/sdks/github-setup.mdx b/fern/products/sdks/project-structure.mdx similarity index 78% rename from fern/products/sdks/github-setup.mdx rename to fern/products/sdks/project-structure.mdx index 36684578c..283e406f6 100644 --- a/fern/products/sdks/github-setup.mdx +++ b/fern/products/sdks/project-structure.mdx @@ -7,34 +7,34 @@ Before generating SDKs with Fern, set up the proper GitHub repository structure ## Repository architecture -Fern recommends a parent-child repository structure containing: +Fern recommends a multi-repository structure containing: -- **Parent repository**: Contains your API definitions and SDK generation configuration -- **Child repositories**: Separate repositories for each SDK (TypeScript, Python, Go, etc.) +- **Source repository**: Contains your API definitions and SDK generation configuration +- **SDK repositories**: Separate repositories for each SDK (TypeScript, Python, Go, etc.) ```bash -├─ company-repo # Parent repository +├─ company-repo # Source repository │ ├─ .github.workflows # Contains publishing workflows for all SDKs │ └─ fern/ │ ├─ fern.config.json # Root-level config -│ ├─ generators.yml # References child repos +│ ├─ generators.yml # References SDK repos │ └─ definition/ ├─ overrides.yml # Optional overrides file │ └─ api.yml # Your API definition -├─ typescript-sdk-repo # Child repository -├─ python-sdk-repo # Child repository -└─ go-sdk-repo # Child repository +├─ typescript-sdk-repo # SDK repository +├─ python-sdk-repo # SDK repository +└─ go-sdk-repo # SDK repository ``` This separation allows you to manage API definitions centrally while keeping each SDK in its own repository for independent versioning and distribution. - See Cohere's [fern folder](https://github.com/cohere-ai/cohere-developer-experience/tree/23d6c541a01eb6b54dd9bb3588c805bb0e307713/fern) and [TypeScript](https://github.com/cohere-ai/cohere-typescript) and [Python](https://github.com/cohere-ai/cohere-python) child repositories. + See Cohere's [fern folder](https://github.com/cohere-ai/cohere-developer-experience/tree/23d6c541a01eb6b54dd9bb3588c805bb0e307713/fern) and [TypeScript](https://github.com/cohere-ai/cohere-typescript) and [Python](https://github.com/cohere-ai/cohere-python) SDK repositories. ## Core configuration files -The parent repository contains a `fern/` folder that is initialized with your API definitions and a top-level `generators.yml` file. +The source repository contains a `fern/` folder that is initialized with your API definitions and a top-level `generators.yml` file. ### `fern.config.json` @@ -51,7 +51,7 @@ Every time you run a fern CLI command, the CLI downloads itself at the correct v ### `generators.yml` -The `generators.yml` file specifies which SDKs to generate and where to publish them. It acts as the bridge between your API definitions and your SDK repositories. For SDK generation, it contains a group for each SDK and points to the corresponding child repository: +The `generators.yml` file specifies which SDKs to generate and where to publish them. It acts as the bridge between your API definitions and your SDK repositories. It contains a group for each SDK generator and points to the corresponding SDK's repository: ```yaml groups: @@ -84,7 +84,7 @@ For information on how to structure your API definition files, see [Project stru You can optionally add an `overrides.yml` file to customize your API definition without modifying the original spec file. For more information, see [Overrides](/api-definitions/overview/overrides). -## Child repository structure +## SDK repository structure Each SDK has its own repository with the following structure: @@ -101,9 +101,9 @@ Fern generates most of these files automatically, including preserving any custo ## Setup instructions -1. **Create repositories**: Set up your parent repository and one child repository for each SDK -2. **Install Fern GitHub App**: Install the [Fern GitHub App](https://github.com/apps/fern-api) on all repositories (parent and children) -3. **Configure generators.yml**: Add each child repository to your `generators.yml` file +1. **Create repositories**: Set up your source repository, plus one repository for each SDK +2. **Install Fern GitHub App**: Install the [Fern GitHub App](https://github.com/apps/fern-api) on all repositories +3. **Configure `generators.yml`**: In your `generators.yml`, add a reference to each SDK repository. ## Multiple API definitions diff --git a/fern/products/sdks/sdks.yml b/fern/products/sdks/sdks.yml index b4cf4638a..20087f696 100644 --- a/fern/products/sdks/sdks.yml +++ b/fern/products/sdks/sdks.yml @@ -8,8 +8,8 @@ navigation: path: ./fern-folder.mdx slug: quickstart - page: Project structure - path: ./github-setup.mdx - slug: github + path: ./project-structure.mdx + slug: project-structure - page: Adding custom code path: ./custom-code.mdx slug: custom-code diff --git a/fern/products/sdks/snippets/setup-fern-folder-callout.mdx b/fern/products/sdks/snippets/setup-fern-folder-callout.mdx index d4bc1c293..29b8f5464 100644 --- a/fern/products/sdks/snippets/setup-fern-folder-callout.mdx +++ b/fern/products/sdks/snippets/setup-fern-folder-callout.mdx @@ -1,7 +1,7 @@ This page assumes that you have: - * An initialized `fern` folder on your local machine. See [Set up the `fern` + * An initialized `fern` folder. See [Set up the `fern` folder](/sdks/overview/quickstart). - * A GitHub repository for your SDK. See [Project Structure](/sdks/overview/github). + * A GitHub repository for your SDK. See [Project Structure](/sdks/overview/project-structure). \ No newline at end of file