From 0cbdb98fe65daf2822de97f2378f501d517b7436 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mateusz=20W=C3=B3jcik?= Date: Wed, 16 Sep 2026 12:09:10 +0200 Subject: [PATCH] docs: document Fern API reference flow --- README.md | 30 +++++++++++++++++++++++++++++- 1 file changed, 29 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 04b157e11..40e5e8899 100644 --- a/README.md +++ b/README.md @@ -60,7 +60,7 @@ Some translation values are references to other files, like so: The matching file can be found at [markdown/en/tags/account-tag-description.md](markdown/en/tags/account-tag-description.md) and any changes should be made directly against that file's contents. -To apply changes made against the translation file(s), simply run the [build](build) script. You will see the changes reflected on the [openapi.yaml](openapi.yaml) and [openapi-sdk.yaml](openapi-sdk.yaml) files. +To apply changes made against the translation file(s), simply run the [build](build) script. You will see the changes reflected on the [openapi.yaml](openapi.yaml), [openapi-fern.yaml](openapi-fern.yaml), and [openapi-sdk.yaml](openapi-sdk.yaml) files. Translation changes will affect all SDKs so you must rebuild them. See the [Rebuilding SDKs](#rebuilding-sdks) section for more information. @@ -74,6 +74,34 @@ If you make changes to any of the code samples you should also rebuild the SDKs If you make a change to only a single language you only need to rebuild that SDK, otherwise it is best to rebuild all SDKs. See the [Rebuilding SDKs](#rebuilding-sdks) section for more information. +### Updating the Fern API Reference + +The [build](build) script generates the self-contained +[openapi-fern.yaml](openapi-fern.yaml) consumed by the +[sign-api-documentation](https://github.com/hellosign/sign-api-documentation) +repository. When an OpenAPI change should be published in the Fern API +reference, copy that generated file into the documentation repository: + +Do not publish the API reference change until the corresponding API +functionality and all affected SDK versions are available to customers. Confirm +the SDK packages are published in their public registries before merging the +documentation change. + +```bash +# In a sibling sign-api-documentation clone +cp ../hellosign-openapi/openapi-fern.yaml fern/openapi.yaml +fern check +``` + +The documentation repository also provides an equivalent guarded copy helper: + +```bash +npm run sync:openapi -- --write --check +``` + +Commit the updated `fern/openapi.yaml` in the documentation pull request. This +step is unnecessary when the generated file has not changed. + ### Rebuilding SDKs Any changes to translations/copy, or code samples, will require rebuilding the SDKs. Run the [generate-sdks](generate-sdks) script to get started.