Docs Release and Contribution Guide

[sharadregoti]

User description

Preview Link

Checklist

• Added a preview link
• Reviewed AI PR Agent suggestions
• For Tyk Members - Added Jira DX PR ticket to the subject
• For Tyk Members - Added the appropriate release labels (for fixes add the latest release)

New Contributors

• Make sure you have started your change off our latest master.
• I have reviewed the guidelines for contributing to this repository.
• I have read the technical guidelines for contributing to this repository.

---

PR Type

Documentation

---

Description

• Added comprehensive release guide for Tyk documentation

• Introduced content management guide for documentation

• Updated navigation menu to include new guides

• Improved documentation process visibility for contributors

---

Changes walkthrough 📝

Relevant files

Documentation

release-guide.md Add comprehensive release workflow guide for documentation tyk-docs/content/developer-support/release-guide.md Added a detailed guide on Tyk documentation release workflow Explained patch, major, and minor release processes Included step-by-step instructions and automation details Provided notes for maintaining LTS and previous releases +186/-0  content-guide.md Add content management guide for documentation                      tyk-docs/content/developer-support/content-guide.md Introduced a new content guide for documentation management Outlined steps for creating, updating, and deleting content Provided placeholders for versioning guidance +15/-0    menu.yaml Update navigation to include new documentation guides        tyk-docs/data/menu.yaml Updated menu to add "Release Tyk Docs" and "Content Guide" under Docs Contribution Ensured new guides are visible in the navigation structure +8/-0

---

Need help?

Type /help how to ... in the comments thread for any questions about PR-Agent usage.

Check out the documentation for more information.

[github-actions]

⚠️ Deploy preview for PR #6519 did not become live after 3 attempts.
Please check Netlify or try manually: Preview URL

[github-actions]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 2 🔵🔵⚪⚪⚪

🧪 No relevant tests

🔒 No security concerns identified

⚡ Recommended focus areas for review Broken or Incomplete Links There are placeholder or incomplete links (e.g., [Release Notes]() and [tyk.io/docs/nighlty](https://tyk.io/docs/nighlty)) that may confuse readers or lead to 404 errors. These should be validated and updated with correct URLs before merging. 1. [Docs](https://github.com/TykTechnologies/tyk-docs/pull/6076) Typos and Formatting There are several typos (e.g., "nighlty" instead of "nightly", "Componets" instead of "Components", "Datashource" instead of "Datasource", "LIsts" instead of "Lists") and inconsistent formatting that could reduce the professionalism and clarity of the documentation. These should be corrected. | `master` | Holds docs for nightly build. | [tyk.io/docs/nighlty](https://tyk.io/docs/nighlty) | | `release-x.y` | Holds docs for that specific version. For example, `release-5.7` holds docs for 5.7 and its patch versions (5.7.1, 5.7.2, etc.). | [tyk.io/docs/5.7](https://tyk.io/docs/5.7) | | `stable` | Holds the latest release. | [tyk.io/docs](https://tyk.io/docs) | Documentation content is always merged into the `master` branch first, and then the changes are made to the `release-x.y` branches as needed. The `stable` branch is updated with the latest release. Note: The stable branch automatically replicates changes from the latest release branch (e.g., `release-5.7`) to ensure that the live site always reflects the most recent stable version. So at tyk.io/docs and tyk.io/docs/5.7, you will see the same content. ## Patch Release To release a patch version, we follow a simple process that involves merging the release notes and documentation PRs into the master and the specific release branch (e.g., `release-5.7`). ### Pre-Requisites: Ensure you have PRs for documentation and release notes that have already been approved. At most, two PRs should be available for each release 5.7, 5.3.5. Sometimes, you may not have a docs PR and only have release notes. Check the example PRs below: 1. [Docs](https://github.com/TykTechnologies/tyk-docs/pull/6076) 2. [Release Notes]()This step ensures we have updated the Tyk component version on the [release summary page](https://tyk.io/docs/developer-support/release-notes/overview/). This should already be taken care of in the pre-requisite PRs. If not, then create a PR for the same. ### Instructions 1. **Deploy release: Merge RNs and Docs PRs**\ **Description:** The PRs mentioned in the prerequisites can now be merged in master and release branch (release-5.7) 2. **Verify**\ **Description:** After merging the PRs on the version branch (release-5.7), it usually takes 5 minutes to reflect the same on the live website. Verify these changes after release. Note: We can also have patch release for previous versions. For example, if the latest version is 5.7.2 and the new patch is 5.7.3, and a patch for LTS version 5.3.3 is also releases, then you will have to merge the PRs for both versions. The process is the same as above, but you will have to create a separate PR for the LTS version. ## Major/Minor Release ### Instructions To release a major or minor version, we follow a series of steps to ensure that the documentation is updated, the latest version is deployed, and the previous versions are maintained correctly. The following steps outline the process: 1. **Add the latest version in Python Script:**\ **Description:** Over time, the content of pages is moved to new pages and deleted. This script is used to maintain a one-to-one mapping of which page is compatible with which version.\ **Automation:** This [Github Action](https://github.com/TykTechnologies/tyk-docs/actions/workflows/release.yml) generates this page.\ **Example**: <https://github.com/TykTechnologies/tyk-docs/pull/5376>\ **Steps:** 1. Invoke this [Github Action](https://github.com/TykTechnologies/tyk-docs/actions/workflows/release.yml) with the following values. Ensure you follow the naming convention of release branches (release-x.y) 2. This will create 3 PRs. The one we are interested in will be named Update version.json 3. Merge the PR into master 2. **Update stable branch updater**\ **Description:** We are updating a GitHub Action here. This action ensures that anything we merge into the version branch (release-5.7) is also merged into the stable branch, which directly reflects our live site.\ **Automation:** This [Github](https://github.com/TykTechnologies/tyk-docs/actions/workflows/release.yml) Action generates this page.\ **Example**: <https://github.com/TykTechnologies/tyk-docs/pull/5377>\ **Steps:** 1. Invoke this [Github Action](https://github.com/TykTechnologies/tyk-docs/actions/workflows/release.yml) with the following values. Ensure you follow the naming convention of release branches (release-x.y) 2. This will create 3 PRs. The one we are interested in will be named Update stable-updater.yaml to use release-5.8 3. Merge the PR into master, current latest till release-5. **We need to merge the PR to all the way to previous branches.** 3. **TODO: Create release 5.8 branch with _redirects and baseURL in config.toml** Description:\ **Automation:** This [Github](https://github.com/TykTechnologies/tyk-docs/actions/workflows/release.yml) Action generates this page.\ **Example**: <https://github.com/TykTechnologies/tyk-docs/pull/5544>\ **Steps:** 1. Invoke this [Github Action](https://github.com/TykTechnologies/tyk-docs/actions/workflows/release.yml) with the following values. Ensure you follow the naming convention of release branches (release-x.y) 2. Merge the PR into release-5.7 **Note:** Ensure that Netlify has release-5.8 (latest branch) as a deploy branch and then push the branch, validating that the URL can be browsed to correctly 4. **Add GitHub Branch Protection to** release-5.8 **branch**\ **Description:**\ **Automation:** Not Available\ **Steps:** 1. Go to Github settings. 2. Copy branch protection rules of the previous release branch to this release. 5. **Update the previous version URL to be versioned once 5.8. released**\ Description: This change ensure that our current latest version is now available at the URL prefix /5.7\ **Steps:** 1. Invoke this [Github Action](https://github.com/TykTechnologies/tyk-docs/actions/workflows/release.yml) with the following values. Ensure you follow the naming convention of release branches (release-x.y) 2. This will create 3 PRs. The one we are interested in will be named Update baseURL to //tyk.io/docs/5.7/ this needs to be merged in current version. 6. **Deploy release: Merge all RNs, Docs & Config PRs**\ Description: The PRs mentioned in the prerequisites can now be merged in master and latest branch that was created in the previous steps. 7. **Update release notes landing page for 5.8.0 release**\ **Description:** This step ensures we have updated the Tyk component version on the [release summary page](https://tyk.io/docs/developer-support/release-notes/overview/). This should already be taken care of in the pre-requisite PRs. If not, then create a PR for the same. 8. **Deploy versions Drop Down LIsts**\ **Description:** This step updates the version dropdown on the docs site.\ **Automation:** This [Github Action](https://github.com/TykTechnologies/tyk-docs/actions/workflows/page_available_since.yml) will generate the required PR.\ **Example:** <https://github.com/TykTechnologies/tyk-docs/pull/5545>\ Clarity of Manual Steps Some manual steps (e.g., updating HubSpot banners, Postman collections, branch protection rules) are described at a high level but may lack sufficient detail for new contributors. Consider clarifying or linking to more detailed internal guides if available. 4. **Add GitHub Branch Protection to** release-5.8 **branch**\ **Description:**\ **Automation:** Not Available\ **Steps:** 1. Go to Github settings. 2. Copy branch protection rules of the previous release branch to this release. 5. **Update the previous version URL to be versioned once 5.8. released**\ Description: This change ensure that our current latest version is now available at the URL prefix /5.7\ **Steps:** 1. Invoke this [Github Action](https://github.com/TykTechnologies/tyk-docs/actions/workflows/release.yml) with the following values. Ensure you follow the naming convention of release branches (release-x.y) 2. This will create 3 PRs. The one we are interested in will be named Update baseURL to //tyk.io/docs/5.7/ this needs to be merged in current version. 6. **Deploy release: Merge all RNs, Docs & Config PRs**\ Description: The PRs mentioned in the prerequisites can now be merged in master and latest branch that was created in the previous steps. 7. **Update release notes landing page for 5.8.0 release**\ **Description:** This step ensures we have updated the Tyk component version on the [release summary page](https://tyk.io/docs/developer-support/release-notes/overview/). This should already be taken care of in the pre-requisite PRs. If not, then create a PR for the same. 8. **Deploy versions Drop Down LIsts**\ **Description:** This step updates the version dropdown on the docs site.\ **Automation:** This [Github Action](https://github.com/TykTechnologies/tyk-docs/actions/workflows/page_available_since.yml) will generate the required PR.\ **Example:** <https://github.com/TykTechnologies/tyk-docs/pull/5545>\ **Steps:** 1. Run the Github action from master, this will generate a PR. **Github Action:** <https://github.com/TykTechnologies/tyk-docs/actions/workflows/page_available_since.yml> 2. This PR has to be merged to master all previous versions till you get a merge conflict. 9. **Verify that Everything is working**\ **Steps:** 1. Go to the latest [https://tyk.io/docs](https://tyk.io/docs/) URL and navigate through the docs to ensure it is not redirecting to some other URL. 2. Go to the previous URL, <https://tyk.io/docs/5.7>, and navigate through the docs to ensure it is not redirected to some other URL. 10. **Rerun Algolia Search Index**\ **Description:** To enable instant search on the latest documents without relying on the CRON job, we need to manually index the new pages.\ **Automation:** We have a CRON job that runs daily to update the index.\ **Steps:** 1. Login to algolia 2. Select the latest project 3. Click on Datashource → crawler → select tyk- crawler 4. Click on Resume Crawling 11. **Update Postman Collections**\ **Description:** We maintain a postman collection for the following Tyk Componets. After a\ **Automation:** Not Available\ **Steps:**\ These instructions are for a single Tyk component and must be repeated for others. 1. Download the swagger from the docs website or the respective Github repository of the component. 2. In Postman, select the import option and drop the file you downloaded in the first step. 3. After the import, change the name. Refer to our previous collection name. 4. In the Postman documentation for a collection, you need to add an image. Copy it from the previous Postman collection. 5. Add the latest prefix and remove the previous one. This ensures that the latest version is always displayed at the top. 12. **Update the HubSpot Banner to indicate the release of 5.8 on old docs pages.**\ **Description:** We use HubSpot to display a banner at the top of our docs page, which indicates that you are viewing old documentation and points to the latest version.\ Here is a sample banner you can view on this [page](https://tyk.io/docs/4.0/getting-started/key-concepts/graphql-subscriptions/). **Automation:** Not Available\ **Steps:** Inform @Jennifer Craig to release the new banner. 13. **Add a reference to release notes in Github Releases.**\ **Description:** Developers usually refer to the release tags to view the changelog. These release tags should point to the release notes in the docs.\ **Automation:** Not Available\ **Steps:** Modify the release tags of all components modified in a release.\

[github-actions]

PR Code Suggestions ✨

No code suggestions found for the PR.

[netlify]

✅ PS. Add to the end of url /docs/nightly

Name	Link
🔨 Latest commit	6165b61
🔍 Latest deploy log	https://app.netlify.com/projects/tyk-docs/deploys/6875468c41ea680008ab7d5b
😎 Deploy Preview	https://deploy-preview-6519--tyk-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[sharadregoti]

/writer "Do you have any suggestions on the structure and content of contributing.md, contribution-guides.md, release-guide.md"