Merge pull request #154 from joshbeard/doc-touchups

docs: minor touchups

.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
+  $CHANGES

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,57 +154,57 @@
 
 ## 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)
 
 ## v0.1.8 - 2023-03-20
 
 ### 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)
 
 ## v0.1.6 - 2023-03-07
 
 ### 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)
 
 ## v0.1.4 - 2023-03-02
 
 ### Changes
 
-### 🚀 Features
+### Features
 
 - feature: image upload @joshbeard (#10)
 
 ## v0.1.3 - 2023-02-28
 
 ### Changes
 
-### 🐛 Bug Fixes
+### Bug Fixes
 
 - fix: re-create deleted resources @joshbeard (#9)
 

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.

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.
+THE SOFTWARE.

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,29 +40,33 @@ 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
 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 ./...
 
 .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

README.md

@@ -7,29 +7,29 @@
 📖 Refer to <https://registry.terraform.io/providers/LiveOakLabs/readme/latest/docs>
 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
 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.