Note: This is applicable only to existing integrations. Refer to the Update docs for a new SaaS version tutorial for instructions on adding brand new documentation.

This tutorial covers the steps required to update a SaaS integration’s base (setup, replication, schema details) documentation as part of a new major version release.

While major version bumps are typically thought of as, say, going from version 1 to 2, these instructions also apply when an existing integration is tapified.

Step 1: Create a new branch

If you haven’t already, create a new branch off of the Stitch Docs master branch. Name it something descriptive to ensure it’s easy to find and tell what you’re working on.

Note: Do not fork the Stitch Docs repo and create a branch. Please clone the repo locally, and then create a new branch.

Step 2: Set up your folders

Each SaaS integration has its own folder in two places:

• _saas-integrations, which is where the main documentation (setup, replication, etc.) is kept
• _integration-schemas, which is where the documentation for tables included in the integration are kept

Step 2.1: In the _saas-integrations folder

The main documentation for SaaS integrations is kept in the _saas-integrations folder.

1. Navigate to this folder.
2. In the integration’s folder, create a folder that corresponds to the version of the integration. For example: If the version is 2, the folder would be named v2.

The final file structure should be: _saas-integrations/<integration-name>/v<version>

For example: _saas-integrations/facebook-ads/v2

Step 2.2: In the _integration-schemas folder

Navigate to the _integration-schemas folder, and repeat the steps in the previous section.

Step 3: Save a copy of the existing documentation

In this step, you’ll save a copy of the existing documentation into the integration’s new version folder. This will give you content to start with instead of having to start from scratch.

1. In the _saas-integrations folder, locate the existing documentation for the integration.

2. Save a copy of the existing documentation into the new folder you created in Step 2.1, using this naming convention: [integration-name]-v[version].md

   For example: facebook-ads-v2.md would be saved in the _saas-integrations/facebook-ads/v2 folder.

Step 4: Update the this-version parameter

After you’ve saved a copy of the existing documentation, you can start updating it to fit the new version. The first step is to update the doc’s this-version parameter, located in the Tap Details section:

# -------------------------- #
#         Tap Details        #
# -------------------------- #

name: "facebook-ads"
display_name: "Facebook Ads"
singer: true
repo-url: https://github.com/singer-io/tap-facebook

this-version: "1"

Update this value to reflect the version of the integration, using this convention: [major-version]. This must match what was entered in the integration’s version file.

Minor version and patch numbers should not be included, as the docs will quickly become outdated based on the speediness of development.

Step 5: Update the permalink and the input parameter

After you’ve updated the new version, update the permalink and the input parameter for each version. For the latest version:

• The permalink must end by /<integration-name>.
• The input: false parameter must be inactive.

For the previous versions:

• The permalink must end by /<integration-name>/v<version>.
• The input: false parameter must be active.

Here is an example with Google Sheets v2 and v3:

# -------------------------- #
#      Page & Formatting     #
# -------------------------- #

title: Google Sheets (v2)
permalink: /integrations/saas/google-sheets/v2
keywords: google-sheeets, integration, schema, etl google-sheeets, google-sheeets etl, google-sheeets schema
layout: singer
input: false

# -------------------------- #
#      Page & Formatting     #
# -------------------------- #

title: Google Sheets (v3)
permalink: /integrations/saas/google-sheets
keywords: google-sheeets, integration, schema, etl google-sheeets, google-sheeets etl, google-sheeets schema
layout: singer
# input: false

If you do not update:

• The permalink, the switch to change the doc version does not work.
• The input parameter, each version of the integration has an entry in the TOC.

Step 6: Make updates as needed

Be sure to deprecate old or non-tapified versions of integration documentation when adding a new version. Refer to the Deprecate an integration version guide for steps on how to do that.

Rather than start content from scratch, only make updates to content where needed. This includes the integration’s details, Stitch details, setup requirements, and so on.

Refer to the SaaS integration template reference for more info and examples.

Step 7: Refer to your release checklist

If you’re working on a release, refer to the release checklist you’re using to wrap up the remaining steps for launch:

• New SaaS version release checklist
• All release checklists

Last updated: 15 October 2024