diff --git a/.github/release-drafter.yml b/.github/release-drafter.yml index 2f545a9..34559ec 100644 --- a/.github/release-drafter.yml +++ b/.github/release-drafter.yml @@ -1,16 +1,16 @@ name-template: 'v$RESOLVED_VERSION' tag-template: 'v$RESOLVED_VERSION' categories: - - title: '🚀 Features' + - title: 'Features' labels: - 'feature' - 'enhancement' - - title: '🐛 Bug Fixes' + - title: 'Bug Fixes' labels: - 'fix' - 'bugfix' - 'bug' - - title: '🧰 Maintenance' + - title: 'Maintenance' labels: - 'chore' - 'ci' @@ -31,4 +31,4 @@ version-resolver: template: | ## Changes - $CHANGES \ No newline at end of file + $CHANGES diff --git a/CHANGELOG.md b/CHANGELOG.md index c9233e1..8b0e3ce 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -81,11 +81,11 @@ ## v0.3.0 - 2024-01-19 -### 🚀 Features +### Features - feat: changelog resource and data source @joshbeard (#100) -### 🐛 Bug Fixes +### Bug Fixes - fix: doc attribute inconsistencies @joshbeard (#101) @@ -131,7 +131,7 @@ ## v0.1.12 - 2023-04-18 -### 🚀 Features +### Features - feat: Custom Pages data sources and resource @joshbeard (#27) @@ -142,7 +142,7 @@ ## v0.1.11 - 2023-03-31 -### 🐛 Bug Fixes +### Bug Fixes - fix: Trim leading/trailing whitespace from docs @joshbeard (#23) @@ -154,13 +154,13 @@ ## v0.1.10 - 2023-03-27 -### 🚀 Features +### Features - feat: Sort api_specifications data source @joshbeard (#20) ## v0.1.9 - 2023-03-24 -### 🚀 Features +### Features - feat: Add api_specifications data source @joshbeard (#19) @@ -168,13 +168,13 @@ ### Changes -### 🚀 Features +### Features - feat: API spec data source filtering @joshbeard (#18) ## v0.1.7 - 2023-03-16 -### 🐛 Bug Fixes +### Bug Fixes - fix: api spec data source - lookup by title @joshbeard (#17) @@ -182,13 +182,13 @@ ### Changes -### 🐛 Bug Fixes +### Bug Fixes - fix: Don't send conflicting request params @joshbeard (#14) ## v0.1.5 - 2023-03-06 -### 🐛 Bug Fixes +### Bug Fixes - fix: image path validation @joshbeard (#11) @@ -196,7 +196,7 @@ ### Changes -### 🚀 Features +### Features - feature: image upload @joshbeard (#10) @@ -204,7 +204,7 @@ ### Changes -### 🐛 Bug Fixes +### Bug Fixes - fix: re-create deleted resources @joshbeard (#9) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 215d6ab..981491b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,26 +1,41 @@ # Contributing -Merge requests should be opened to merge into the `main` branch. +Live Oak Bank welcomes your interest in contributing to this project in any way +you find meaningful, be it through code contributions, documentation, or bug +reporting. We greatly value and appreciate your involvement. ## Workflow 1. Fork and branch from `main`. 2. Make changes. -3. Run `pre-commit` (`pre-commit run -a`) before committing. -4. Run `make test` before committing. -5. Commit, push, and open a pull request into `main`. -6. Ensure GitHub workflow checks pass. -7. Set a GitHub label on the pull request if you know what fits best. +3. Run `make lint test` before committing. +4. Commit, push, and open a pull request into `main`. +5. Ensure GitHub workflow checks pass. + +## Common Development Tasks + +Refer to the [`Makefile`](Makefile) for helpful development tasks. + +* `make` - Show list of available tasks. +* `make lint` - Run linters and formatters. +* `make test` - Run all tests. +* `make test-coverage` - Run tests, generate coverage report, and open in a browser. +* `make mocks` - Generate mocks for interfaces (used by external tests). ## GitHub Labels +Issues and pull requests are labeled to help organize and version changes. Feel +free to apply labels to your contributions, or project maintainers will do so. + * Use `patch`, `minor`, or `major` to indicate the [semantic version](https://semver.org/) for a change. If unsure, a project maintainer will set it. * Use `feature` or `enhancement` for added features. * Use `fix`, `bugfix` or `bug` for fixed bugs. * Use `chore`, `ci`, and `docs` for maintenance tasks. -## Releases +## For Project Maintainers + +### Releases This project uses the [Release Drafter](https://github.com/marketplace/actions/release-drafter) action for managing releases and tags. @@ -29,14 +44,5 @@ The [Changelog Updater](https://github.com/marketplace/actions/changelog-updater [`CHANGELOG.md`](https://github.com/marketplace/actions/changelog-updater) file when releases are published. -## Tools and Tests - -This project uses a few [tools](readme/tools.go) for validating code quality and functionality: - -* [pre-commit](https://pre-commit.com/) for ensuring consistency and code quality before committing (external dependency). -* [golangci-lint](https://golangci-lint.run/) for linting and formatting. -* [gofumpt](https://github.com/mvdan/gofumpt) (is included with golangci-lint). -* [gocover-cobertura](https://github.com/boumenot/gocover-cobertura) for code test coverage reporting. -* [govulncheck](https://github.com/golang/vuln) for detecting vulnerabilities in Go packages. - -Refer to the [`Makefile`](Makefile) for helpful development tasks. +Project maintainers can publish a new release by editing the queued draft +release, making adjustments to the release notes, and publishing. diff --git a/LICENSE b/LICENSE index 6b9bb94..e330e88 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ The MIT License -Copyright (c) 2023 Live Oak Banking Company +Copyright (c) 2023-2024 Live Oak Banking Company Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal @@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN -THE SOFTWARE. \ No newline at end of file +THE SOFTWARE. diff --git a/Makefile b/Makefile index babb10f..160ac2e 100644 --- a/Makefile +++ b/Makefile @@ -1,7 +1,6 @@ # Run 'make help' for a list of targets. .DEFAULT_GOAL := help -GO_MODULE := $(shell go list -m) PKG_PATH := readme .PHONY: help @@ -41,7 +40,7 @@ lint: modverify vet gofumpt lines golangci-lint ## Run all linters .PHONY: test test: ## Run unit and race tests with 'go test' go test -v -count=1 -parallel=4 -coverprofile=coverage.txt -covermode count ./$(PKG_PATH)/... - #go test -race -short ./$(PKG_PATH)/... + go test -race -short ./$(PKG_PATH)/... ## Coverage ## .PHONY: coverage @@ -49,12 +48,21 @@ coverage: test ## Generate a code test coverage report using 'gocover-cobertura' go run github.com/boumenot/gocover-cobertura < coverage.txt > coverage.xml rm -f coverage.txt +.PHONY: test-coverage +test-coverage: test ## Open the HTML test coverage report + @go tool cover -html=coverage.txt + ## Vulnerability checks ## .PHONY: check-vuln check-vuln: ## Check for vulnerabilities using 'govulncheck' @echo "Checking for vulnerabilities..." go run golang.org/x/vuln/cmd/govulncheck ./... +.PHONY: clean +clean: ## Clean test files + rm -f dist/* + rm -f coverage.txt coverage.xml coverage.html checkstyle-report.xml + .PHONY: docs docs: ## Run 'go generate' to create documentation go generate ./... @@ -62,8 +70,3 @@ docs: ## Run 'go generate' to create documentation .PHONY: install install: ## Run 'go install' to install package go install . - -.PHONY: clean -clean: ## Clean test files - rm -f dist/* - rm -f coverage.txt coverage.xml coverage.html checkstyle-report.xml diff --git a/README.md b/README.md index 3a14821..8d18924 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ 📖 Refer to for the latest provider documentation. -☁️ Also see our [Go Client for the ReadMe.com API](https://github.com/liveoaklabs/readme-api-go-client). +☁️ Also see our [Go Client for the ReadMe.com API](https://github.com/liveoaklabs/readme-api-go-client) that this provider uses. _This provider is developed by [Live Oak Bank](https://liveoakbank.com) and is @@ -15,21 +15,21 @@ not officially associated with ReadMe.com._ ## Getting Started -__Terraform >= 1.0+ is required.__ +__Terraform >= 1.0 is required.__ ### Configure the Provider ```terraform provider "readme" { # Set the API token here or with the README_API_TOKEN env var. - # api_token = "" + api_token = "YOUR_API_TOKEN" } terraform { required_providers { readme = { source = "liveoaklabs/readme" - version = "~> 0.1" + version = "0.5.0" # Check for the latest version on the Terraform Registry. } } } @@ -51,9 +51,8 @@ Create an API specification: ```terraform resource "readme_api_specification" "example" { - # 'definition' accepts a string of an OpenAPI specification definition JSON. definition = file("petstore.json") - semver = readme_version.example.version + semver = readme_version.example.version_clean } ``` @@ -63,7 +62,7 @@ Create a category: resource "readme_category" "example" { title = "My example category" type = "guide" - version = readme_version.example.version + version = readme_version.example.version_clean } ``` @@ -89,7 +88,7 @@ resource "readme_doc" "example" { # body can be read from a file using Terraform's `file()` function. body = file("mydoc.md") - version = readme_version.example.version + version = readme_version.example.version_clean } ``` @@ -102,11 +101,30 @@ for a full list with examples. ## Disclaimer About Versioning and Development Status ⚠️ This project is currently under active development and is versioned using -the `0.x.x` scheme. Breaking changes are likely and will result in an -increment to the minor version (e.g., `0.2.0` to `0.3.0).` Users are strongly -advised not to automatically update to new minor or major versions without -thoroughly testing, as the API and functionality may change significantly -between releases. +the `0.x.x` scheme. + +Breaking changes will likely occur and will trigger a minor version increment +(e.g., `0.2.0->0.3.0`). + +Users are encouraged to pin the provider to a specific patch version for +maximum stability throughout the `0.x.x` series. + +For examplea: + +```hcl +terraform { + required_providers { + readme = { + source = "liveoaklabs/readme" + # Pinning to a specific patch version. + version = "0.5.0" + + # Alternatively, allow for patch updates. + # version = "~> 0.5.0" + } + } +} +``` A stable `1.x` release is planned for the future once the project meets certain criteria for feature completeness and stability. diff --git a/docs/resources/doc.md b/docs/resources/doc.md index 02a4994..a55b599 100644 --- a/docs/resources/doc.md +++ b/docs/resources/doc.md @@ -22,23 +22,24 @@ description: |- 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. - ⚠️ Experimental: The 'use_slug' attribute is experimental and may result in unexpected behavior. + ⚠️ Experimental: The use_slug attribute is experimental and may result in unexpected + behavior. Destroying Docs with Children 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. However, when managing docs with children, the provider may not be able to infer the relationship - between parent and child docs, particularly in edge cases such as using the use_slug attribute - to manage an API reference's parent doc. + between parent and child docs, particularly in edge cases such as using the use_slug + attribute to manage an API reference's parent doc. When destroying a doc, the provider will check for child docs and prevent deletion if they exist. - This behavior can be controlled with the config.destroy_child_docs attribute. When set to true, - the provider will destroy child docs prior to deleting the parent doc. Setting this as a provider + This behavior can be controlled with the config.destroy_child_docs attribute. When set to + true, the provider will destroy child docs prior to deleting the parent doc. Setting this as a provider configuration attribute allows for it to be toggled without requiring changes to the resource. - When 'config.destroy_child_docs' is set to true, the provider will log a warning when child docs are - deleted before the parent doc. + When config.destroy_child_docs is set to true, the provider will log a + warning when child docs are deleted before the parent doc. For best results, manage docs with Terraform and set their relationship by referencing the resource - address of the parent doc in the child doc's parent_doc_slug or depends_on attributes. This - ensures they are deleted in the correct order. + address of the parent doc in the child doc's parent_doc_slug or depends_on + attributes. This ensures they are deleted in the correct order. --- # readme_doc (Resource) @@ -63,8 +64,8 @@ The slug cannot be altered using the API or the Terraform Provider, but can be e ReadMe web UI. 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. +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* @@ -72,29 +73,30 @@ the doc has been created. Note that doc slugs are shared between Guides and API Specification References. -⚠️ **Experimental:** The 'use_slug' attribute is experimental and may result in unexpected behavior. +⚠️ **Experimental:** The `use_slug` attribute is experimental and may result in unexpected +behavior. ## Destroying Docs with Children 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**. +in the proper order as normal when referenced appropriately or when using `depends_on`. However, when managing docs with children, the provider may not be able to infer the relationship -between parent and child docs, particularly in edge cases such as using the **use_slug** attribute -to manage an API reference's parent doc. +between parent and child docs, particularly in edge cases such as using the `use_slug` +attribute to manage an API reference's parent doc. When destroying a doc, the provider will check for child docs and prevent deletion if they exist. -This behavior can be controlled with the **config.destroy_child_docs** attribute. When set to true, -the provider will destroy child docs prior to deleting the parent doc. Setting this as a provider +This behavior can be controlled with the `config.destroy_child_docs` attribute. When set to +true, the provider will destroy child docs prior to deleting the parent doc. Setting this as a provider configuration attribute allows for it to be toggled without requiring changes to the resource. -When 'config.destroy_child_docs' is set to true, the provider will log a warning when child docs are -deleted before the parent doc. +When `config.destroy_child_docs` is set to `true`, the provider will log a +warning when child docs are deleted before the parent doc. For best results, manage docs with Terraform and set their relationship by referencing the resource -address of the parent doc in the child doc's **parent_doc_slug** or **depends_on** attributes. This -ensures they are deleted in the correct order. +address of the parent doc in the child doc's `parent_doc_slug` or `depends_on` +attributes. This ensures they are deleted in the correct order. ## Example Usage @@ -151,11 +153,7 @@ resource "readme_doc" "example" { - `parent_doc_slug` (String) For a subpage, specify the parent doc slug instead of the ID.This attribute may be set in the body front matter with the `parentDocSlug` key.If a value isn't specified but `parent_doc` is, the provider will attempt to populate this value using the `parent_doc` ID unless `verify_parent_doc` is set to `false`. - `title` (String) **Required.** The title of the doc.This attribute may optionally be set in the body front matter. - `type` (String) **Required.** Type of the doc. The available types all show up under the /docs/ URL path of your docs project (also known as the "guides" section). Can be "basic" (most common), "error" (page describing an API error), or "link" (page that redirects to an external link).This attribute may optionally be set in the body front matter. -- `use_slug` (String) **Use with caution!** Create the doc resource by importing an existing doc by its slug. This is non-conventional and should only be used when the slug is known and the doc is not managed by Terraform or when the slug is changed in the web UI. This is useful for managing an API specification's doc that gets created automatically by ReadMe. When set, the specified doc will be replaced with the Terraform-managed doc. - -If this is set and then unset, a new doc will be created but the existing doc will not be deleted. The existing doc will be orphaned and will not be managed by Terraform. If this is unset and then set, the existing doc will be deleted and the resource will be pointed to the specified doc. In the case of API specification docs, the doc is implicitly deleted when the API specification is deleted. - -This attribute may be set in the body front matter with the `slug` key. +- `use_slug` (String) **Use with caution!** Create the doc resource by importing an existing doc by its slug. This is non-conventional and should only be used when the slug is known and the doc is not managed by Terraform or when the slug is changed in the web UI. This is useful for managing an API specification's doc that gets created automatically by ReadMe. When set, the specified doc will be replaced with the Terraform-managed doc. If this is set and then unset, a new doc will be created but the existing doc will not be deleted. The existing doc will be orphaned and will not be managed by Terraform. If this is unset and then set, the existing doc will be deleted and the resource will be pointed to the specified doc. In the case of API specification docs, the doc is implicitly deleted when the API specification is deleted. This attribute may be set in the body front matter with the `slug` key. - `verify_parent_doc` (Boolean) Enables or disables the provider verifying the `parent_doc` exists. When using the `parent_doc` attribute with a hidden parent, the provider is unable to verify if the parent exists. Setting this to `false` will disable this behavior. When `false`, the `parent_doc_slug` value will not be resolved by the provider unless explicitly set. The `parent_doc_slug` attribute may be used as an alternative. Verifying a `parent_doc` by ID does not work if the parent is hidden. - `version` (String) The version to create the doc under. diff --git a/readme/doc_resource.go b/readme/doc_resource.go index 889cd43..22868ab 100644 --- a/readme/doc_resource.go +++ b/readme/doc_resource.go @@ -44,8 +44,8 @@ The slug cannot be altered using the API or the Terraform Provider, but can be e ReadMe web UI. 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. +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* @@ -53,29 +53,30 @@ the doc has been created. Note that doc slugs are shared between Guides and API Specification References. -⚠️ **Experimental:** The 'use_slug' attribute is experimental and may result in unexpected behavior. +⚠️ **Experimental:** The ` + "`use_slug`" + ` attribute is experimental and may result in unexpected +behavior. ## Destroying Docs with Children 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**. +in the proper order as normal when referenced appropriately or when using ` + "`depends_on`." + ` However, when managing docs with children, the provider may not be able to infer the relationship -between parent and child docs, particularly in edge cases such as using the **use_slug** attribute -to manage an API reference's parent doc. +between parent and child docs, particularly in edge cases such as using the ` + "`use_slug`" + ` +attribute to manage an API reference's parent doc. When destroying a doc, the provider will check for child docs and prevent deletion if they exist. -This behavior can be controlled with the **config.destroy_child_docs** attribute. When set to true, -the provider will destroy child docs prior to deleting the parent doc. Setting this as a provider +This behavior can be controlled with the ` + "`config.destroy_child_docs`" + ` attribute. When set to +true, the provider will destroy child docs prior to deleting the parent doc. Setting this as a provider configuration attribute allows for it to be toggled without requiring changes to the resource. -When 'config.destroy_child_docs' is set to true, the provider will log a warning when child docs are -deleted before the parent doc. +When ` + "`config.destroy_child_docs`" + ` is set to ` + "`true`" + `, the provider will log a +warning when child docs are deleted before the parent doc. For best results, manage docs with Terraform and set their relationship by referencing the resource -address of the parent doc in the child doc's **parent_doc_slug** or **depends_on** attributes. This -ensures they are deleted in the correct order. +address of the parent doc in the child doc's ` + "`parent_doc_slug`" + ` or ` + "`depends_on`" + ` +attributes. This ensures they are deleted in the correct order. ` // Ensure the implementation satisfies the expected interfaces. @@ -1180,18 +1181,18 @@ func (r *docResource) Schema( Computed: true, }, "use_slug": schema.StringAttribute{ - Description: "**Use with caution!** Create the doc resource by importing an existing doc by its slug. " + + MarkdownDescription: "**Use with caution!** Create the doc resource by importing an existing doc by its slug. " + "This is non-conventional and should only be used when the slug is known and " + "the doc is not managed by Terraform or when the slug is changed in the web UI. " + "This is useful for managing an API specification's doc that gets created " + "automatically by ReadMe. When set, the specified doc will be replaced " + - "with the Terraform-managed doc.\n\n" + + "with the Terraform-managed doc. " + "If this is set and then unset, a new doc will be created but the existing doc will not be " + "deleted. The existing doc will be orphaned and will not be managed by Terraform. " + "If this is unset and then set, the existing doc will be deleted and the resource will be " + "pointed to the specified doc. " + "In the case of API specification docs, the doc is implicitly deleted when the " + - "API specification is deleted.\n\n" + + "API specification is deleted. " + "This attribute may be set in the body front matter with the `slug` key.", Optional: true, Computed: true,