diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 9377889..3c1af47 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -87,6 +87,9 @@ jobs: - '1.4.*' - '1.5.*' - '1.6.*' + - '1.7.*' + - '1.8.*' + - '1.9.*' steps: - uses: actions/checkout@v4 # v3.3.0 - uses: actions/setup-go@0a12ed9d6a96ab950c8f026ed9f722fe0da7ef32 # v5.0.2 diff --git a/CHANGELOG.md b/CHANGELOG.md index 2271c85..1633f10 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,7 +14,7 @@ - A new `config` parameter is added to the provider's configuration that contains a single `destroy_child_docs` attribute now that can toggle the behavior of the provider when deleting a doc with children. Previously, the provider would simply fail. With this change, a user can enable the provider to delete nested docs as they're encountered or fail with more helpful output. This fix was to address certain edge cases with managing docs for an API reference that had implicit child docs. - Deleting a doc that doesn't exist (slug not found) will now remove the resource from state and emit a warning. Previously, the provider would throw an error and the only recourse was to manually remove the resource from state. - Update the behavior of `use_slug` - previously, the provider would mark the resource for re-creation if `use_slug` as modified. This wasn't necessary and could lead to unintended side-effects. The provider will now remove the resource from state if the doc is not found remotely and emit a warning. - + ### Changes diff --git a/docs/resources/api_specification.md b/docs/resources/api_specification.md index c4f7ee3..3ceca79 100644 --- a/docs/resources/api_specification.md +++ b/docs/resources/api_specification.md @@ -21,21 +21,21 @@ description: |- # readme_api_specification (Resource) -Manages API specifications on ReadMe.com by uploading the definition to the API registry and associating it with the -specification using the returned UUID. This association is necessary for managing the API specification and its +Manages API specifications on ReadMe.com by uploading the definition to the API registry and associating it with the +specification using the returned UUID. This association is necessary for managing the API specification and its definition. The behavior is similar to the official rdme CLI but is undocumented in the ReadMe API. ## External Changes -External changes to API specifications managed by Terraform are not automatically detected. The UUID changes when a -definition is updated, and the new UUID is only available when published to the registry. To synchronize, force an +External changes to API specifications managed by Terraform are not automatically detected. The UUID changes when a +definition is updated, and the new UUID is only available when published to the registry. To synchronize, force an update via Terraform (e.g., taint or manual change). ## Importing Existing Specifications -Importing is limited due to how the API registry associates specifications with definitions. Terraform will overwrite +Importing is limited due to how the API registry associates specifications with definitions. Terraform will overwrite the remote definition on the next run, replacing the UUID. ## Managing Documentation -API specifications on ReadMe automatically create a documentation page, but it isn't managed by Terraform. Use the +API specifications on ReadMe automatically create a documentation page, but it isn't managed by Terraform. Use the readme_doc resource with use_slug to manage the documentation page. See the ReadMe API documentation at https://docs.readme.com/main/reference/uploadapispecification for more information. diff --git a/docs/resources/doc.md b/docs/resources/doc.md index a55b599..76cd8ed 100644 --- a/docs/resources/doc.md +++ b/docs/resources/doc.md @@ -50,25 +50,25 @@ See for more information about t ## Front Matter -Docs on ReadMe support setting some attributes using front matter. +Docs on ReadMe support setting some attributes using front matter. Resource attributes take precedence over front matter attributes in the provider. -Refer to for more information about using front matter +Refer to for more information about using front matter in ReadMe docs and custom pages. ## Doc Slugs -Docs in ReadMe are uniquely identified by their slugs. The slug is a URL-friendly string that -is generated upon doc creation. By default, this is a normalized version of the doc title. -The slug cannot be altered using the API or the Terraform Provider, but can be edited in the +Docs in ReadMe are uniquely identified by their slugs. The slug is a URL-friendly string that +is generated upon doc creation. By default, this is a normalized version of the doc title. +The slug cannot be altered using the API or the Terraform Provider, but can be edited in the ReadMe web UI. -This creates challenges when managing docs with Terraform. To address this, the provider supports +This creates challenges when managing docs with Terraform. To address this, the provider supports the `use_slug` attribute. When set, the provider will attempt to manage an existing doc by its slug. This can also be set in front matter using the `slug` key. -If this attribute is set and the doc does not exist, an error will be returned. This is intended -to be set when inheriting management of an existing doc or when customizing the slug *after* +If this attribute is set and the doc does not exist, an error will be returned. This is intended +to be set when inheriting management of an existing doc or when customizing the slug *after* the doc has been created. Note that doc slugs are shared between Guides and API Specification References. @@ -78,7 +78,7 @@ behavior. ## Destroying Docs with Children -Docs in ReadMe can have child docs. +Docs in ReadMe can have child docs. Terraform can infer a doc's relationship when they are all managed by the provider and delete them in the proper order as normal when referenced appropriately or when using `depends_on`. diff --git a/readme/api_specification_resource.go b/readme/api_specification_resource.go index 03a0613..701e2cd 100644 --- a/readme/api_specification_resource.go +++ b/readme/api_specification_resource.go @@ -20,21 +20,21 @@ import ( ) const apiSpecResourceDesc = ` -Manages API specifications on ReadMe.com by uploading the definition to the API registry and associating it with the -specification using the returned UUID. This association is necessary for managing the API specification and its +Manages API specifications on ReadMe.com by uploading the definition to the API registry and associating it with the +specification using the returned UUID. This association is necessary for managing the API specification and its definition. The behavior is similar to the official rdme CLI but is undocumented in the ReadMe API. ## External Changes -External changes to API specifications managed by Terraform are not automatically detected. The UUID changes when a -definition is updated, and the new UUID is only available when published to the registry. To synchronize, force an +External changes to API specifications managed by Terraform are not automatically detected. The UUID changes when a +definition is updated, and the new UUID is only available when published to the registry. To synchronize, force an update via Terraform (e.g., taint or manual change). ## Importing Existing Specifications -Importing is limited due to how the API registry associates specifications with definitions. Terraform will overwrite +Importing is limited due to how the API registry associates specifications with definitions. Terraform will overwrite the remote definition on the next run, replacing the UUID. ## Managing Documentation -API specifications on ReadMe automatically create a documentation page, but it isn't managed by Terraform. Use the +API specifications on ReadMe automatically create a documentation page, but it isn't managed by Terraform. Use the readme_doc resource with use_slug to manage the documentation page. See the ReadMe API documentation at https://docs.readme.com/main/reference/uploadapispecification for more information. diff --git a/readme/doc_resource.go b/readme/doc_resource.go index 22868ab..567e243 100644 --- a/readme/doc_resource.go +++ b/readme/doc_resource.go @@ -30,25 +30,25 @@ See for more information about t ## Front Matter -Docs on ReadMe support setting some attributes using front matter. +Docs on ReadMe support setting some attributes using front matter. Resource attributes take precedence over front matter attributes in the provider. -Refer to for more information about using front matter +Refer to for more information about using front matter in ReadMe docs and custom pages. ## Doc Slugs -Docs in ReadMe are uniquely identified by their slugs. The slug is a URL-friendly string that -is generated upon doc creation. By default, this is a normalized version of the doc title. -The slug cannot be altered using the API or the Terraform Provider, but can be edited in the +Docs in ReadMe are uniquely identified by their slugs. The slug is a URL-friendly string that +is generated upon doc creation. By default, this is a normalized version of the doc title. +The slug cannot be altered using the API or the Terraform Provider, but can be edited in the ReadMe web UI. -This creates challenges when managing docs with Terraform. To address this, the provider supports +This creates challenges when managing docs with Terraform. To address this, the provider supports the ` + "`use_slug`" + ` attribute. When set, the provider will attempt to manage an existing doc by its slug. This can also be set in front matter using the ` + "`slug`" + ` key. -If this attribute is set and the doc does not exist, an error will be returned. This is intended -to be set when inheriting management of an existing doc or when customizing the slug *after* +If this attribute is set and the doc does not exist, an error will be returned. This is intended +to be set when inheriting management of an existing doc or when customizing the slug *after* the doc has been created. Note that doc slugs are shared between Guides and API Specification References. @@ -58,7 +58,7 @@ behavior. ## Destroying Docs with Children -Docs in ReadMe can have child docs. +Docs in ReadMe can have child docs. Terraform can infer a doc's relationship when they are all managed by the provider and delete them in the proper order as normal when referenced appropriately or when using ` + "`depends_on`." + ` @@ -466,7 +466,7 @@ func (r *docResource) Read( } hint := "Hint: If you changed the doc slug using the web UI, set the `use_slug` " + "attribute or the `slug` frontmatter key to the new slug.\n" - resp.Diagnostics.AddError("Unable to search for doc.", hint+clientError(err, apiResponse)) + resp.Diagnostics.AddWarning("Unable to search for doc.", hint+clientError(err, apiResponse)) return } @@ -593,8 +593,7 @@ func (r *docResource) Delete( // Check the category's docs to find the doc and its children. docs, _, err := r.client.Category.GetDocs(state.CategorySlug.ValueString(), requestOpts) if err != nil { - resp.Diagnostics.AddError("Unable to retrieve category docs.", clientError(err, nil)) - return + resp.Diagnostics.AddWarning("Unable to retrieve category docs.", clientError(err, nil)) } // Gather the slugs of the docs to delete, including the parent and its children. @@ -640,7 +639,7 @@ func (r *docResource) identifyDocsToDelete( } if parentDoc == nil { - resp.Diagnostics.AddError( + resp.Diagnostics.AddWarning( "Doc not found", fmt.Sprintf("The doc with slug '%s' was not found in the retrieved category docs.", slug), )