feat: Improve development docs and SliceUnique, remove gomarkdoc (#11)

## Motivation

- Added development instructions and contributing guidelines to the
project.
- Removed `gomarkdoc` usage as it turns out that `pkg.go.dev` can render
testable examples comments well.
- Improved `SliceUnique` error messages.
- Added testable example for `SliceUnique`.

## Release Notes

`SliceUnique` now reports more readable error messages using ordinal
slice index form (e.g. 1st, 2nd, 11th) instead of 0-based slice index.

## Breaking changes

`SliceUnique` error message has been changed.
Before: *elements are not unique, index 0 collides with index 2*.
After: *elements are not unique, 1st and 3rd elements collide*.

Makefile

@@ -37,6 +37,13 @@ test:
 	$(call _print_step,Running unit tests)
 	go test -race -cover ./...
 
+.PHONY: test/coverage
+## Produce test coverage report and inspect it in browser.
+test/coverage:
+	$(call _print_step,Running test coverage report)
+	go test -coverprofile=coverage.out ./...
+	go tool cover -html=coverage.out
+
 .PHONY: check check/vet check/lint check/gosec check/spell check/trailing check/markdown check/format check/generate check/vulns
 ## Run all checks.
 check: check/vet check/lint check/gosec check/spell check/trailing check/markdown check/format check/generate check/vulns
@@ -87,9 +94,9 @@ check/format:
 	$(call _print_check_step,Checking if files are formatted)
 	./scripts/check-formatting.sh
 
-.PHONY: generate generate/code generate/readme generate/gomarkdoc
+.PHONY: generate generate/code generate/readme
 ## Auto generate files.
-generate: generate/code generate/readme generate/gomarkdoc
+generate: generate/code generate/readme
 
 ## Generate Golang code.
 generate/code:
@@ -101,16 +108,6 @@ generate/readme:
 	echo "Generating README.md embedded examples..."
 	./scripts/embed-example-in-readme.bash README.md
 
-## Generate Markdown docs from Go docs.
-generate/gomarkdoc:
-	echo "Generating Markdown docs from Go docs..."
-	gomarkdoc \
-		--output docs/DOCUMENTATION.md \
-		--format github \
-		--repository.default-branch main \
-		--repository.url https://github.com/nobl9/govy \
-		./pkg/...
-
 .PHONY: format format/go format/cspell
 ## Format files.
 format: format/go format/cspell

README.md

@@ -15,6 +15,26 @@ to change, breaking changes may be introduced with new versions until v1
 is released. Checkout [roadmap](./docs/ROADMAP.md) for upcoming,
 planned features.
 
+## Legend
+
+1. [Getting started](#getting-started)
+    1. [Use cases](#use-cases)
+2. [Building blocks](#building-blocks)
+    1. [Errors](#errors)
+3. [Features](#features)
+    1. [Type safety](#type-safety)
+    2. [Immutability](#immutability)
+    3. [Verbose error messages](#verbose-error-messages)
+    4. [Predefined rules](#predefined-rules)
+    5. [Custom rules](#custom-rules)
+    6. [Validation plan](#validation-plan)
+    7. [Properties name inference](#properties-name-inference)
+4. [Rationale](#rationale)
+    1. [Reflection](#reflection)
+    2. [Trivia](#trivia)
+5. [Development](#development)
+6. [Acknowledgments](#acknowledgments)
+
 ## Getting started
 
 In order to add the library to your project, run:
@@ -28,8 +48,8 @@ powered by Go's [testable examples](https://go.dev/blog/examples),
 to access it visit [pkg.go.dev](https://pkg.go.dev/github.com/nobl9/govy)
 or locally at [example_test.go](./pkg/govy/example_test.go).
 
-Govy's code documentation is available at [pkg.go.dev](https://pkg.go.dev/github.com/nobl9/govy)
-as well as in generated [Markdown format](./docs/DOCUMENTATION.md).
+Govy's code documentation is available at
+[pkg.go.dev](https://pkg.go.dev/github.com/nobl9/govy).
 
 Here's a quick example of `govy` in action:
 
@@ -133,7 +153,7 @@ func Example_basicUsage() {
 	//     - must be one of [Jake, George]
 	//   - 'students' with value '[{"index":"918230014"},{"index":"9182300123"},{"index":"918230014"}]':
 	//     - length must be less than or equal to 2
-	//     - elements are not unique, index 0 collides with index 2
+	//     - elements are not unique, 1st and 3rd elements collide
 	//   - 'students[1].index' with value '9182300123':
 	//     - length must be between 9 and 9
 	//   - 'university.name':
@@ -565,6 +585,11 @@ were associated with given property was tedious to say the least.
 Around the same time, Go 1.18 was released with generics support, we started playing
 with them, and the idea for `govy` was born.
 
+## Development
+
+Checkout both [contributing guidelines](./docs/CONTRIBUTING.md) and
+[development instructions](./docs/DEVELOPMENT.md).
+
 ## Acknowledgments
 
 The API along with the accompanying nomenclature was heavily inspired by the

cspell.yaml

@@ -38,7 +38,6 @@ words:
   - goimports
   - golangci
   - golines
-  - gomarkdoc
   - goroot
   - gosec
   - govulncheck
@@ -47,7 +46,6 @@ words:
   - ldflags
   - nobl
   - pkgs
-  - plantuml
   - println
   - rtmp
   - sloctl

devbox.json

@@ -8,8 +8,7 @@
     "golangci-lint@1.60",
     "gosec@latest",
     "go@1.22",
-    "gotools@0.22",
-    "gomarkdoc@1.1"
+    "gotools@0.22"
   ],
   "shell": {
     "init_hook": [

devbox.lock

@@ -189,53 +189,6 @@
         }
       }
     },
-    "gomarkdoc@1.1": {
-      "last_modified": "2024-08-14T11:41:26Z",
-      "resolved": "github:NixOS/nixpkgs/0cb2fd7c59fed0cd82ef858cbcbdb552b9a33465#gomarkdoc",
-      "source": "devbox-search",
-      "version": "1.1.0",
-      "systems": {
-        "aarch64-darwin": {
-          "outputs": [
-            {
-              "name": "out",
-              "path": "/nix/store/yyfwkknqpmighcdhd7mpgs7j0wacyn9m-gomarkdoc-1.1.0",
-              "default": true
-            }
-          ],
-          "store_path": "/nix/store/yyfwkknqpmighcdhd7mpgs7j0wacyn9m-gomarkdoc-1.1.0"
-        },
-        "aarch64-linux": {
-          "outputs": [
-            {
-              "name": "out",
-              "path": "/nix/store/0c1717ixhs89vpc8qc3dlraj89w09p27-gomarkdoc-1.1.0",
-              "default": true
-            }
-          ],
-          "store_path": "/nix/store/0c1717ixhs89vpc8qc3dlraj89w09p27-gomarkdoc-1.1.0"
-        },
-        "x86_64-darwin": {
-          "outputs": [
-            {
-              "name": "out",
-              "path": "/nix/store/w8ywczb794fvh2fwrb9906fdnwkax1si-gomarkdoc-1.1.0",
-              "default": true
-            }
-          ],
-          "store_path": "/nix/store/w8ywczb794fvh2fwrb9906fdnwkax1si-gomarkdoc-1.1.0"
-        },
-        "x86_64-linux": {
-          "outputs": [
-            {
-              "path": "/nix/store/ggpkp2n14pk7f4m3niwks5dpyxpxj9dx-gomarkdoc-1.1.0",
-              "default": true
-            }
-          ],
-          "store_path": "/nix/store/ggpkp2n14pk7f4m3niwks5dpyxpxj9dx-gomarkdoc-1.1.0"
-        }
-      }
-    },
     "gosec@latest": {
       "last_modified": "2024-08-14T11:41:26Z",
       "resolved": "github:NixOS/nixpkgs/0cb2fd7c59fed0cd82ef858cbcbdb552b9a33465#gosec",

docs/CONTRIBUTING.md

@@ -0,0 +1,32 @@
+# Contributing to govy
+
+If you're here, chances are you want to contribute ;)
+Thanks a lot for that!
+
+Your pull request will be reviewed by one of the maintainers.
+We encourage and welcome any and all feedback.
+
+## Before you contribute
+
+The goal of this project is to develop a validation library with
+functional interface which is strongly-typed, produces information rich errors
+and has API that is easy to understand and use.
+
+Make sure you're familiarized with
+[development instructions](./DEVELOPMENT.md).
+
+## Making a pull request
+
+Please make a fork of this repo and submit a PR from there.
+More information can be found
+[here](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request).
+
+## Merge Request title
+
+Try to be as descriptive as you can in your PR title.
+Note that the title must adhere to the rules defined in
+[this workflow](./.github/workflows/pr-title.yml).
+
+## License
+
+Govy is licensed under Mozilla Public License Version 2.0, see [LICENSE](../LICENSE).

docs/DEVELOPMENT.md

@@ -0,0 +1,76 @@
+# Development
+
+This document describes the intricacies of govy development workflow.
+If you see anything missing, feel free to contribute to this document :)
+
+## Pull requests
+
+[Pull request template](../.github/pull_request_template.md)
+is provided when you create new PR.
+Section worth noting and getting familiar with is located under
+`## Release Notes` header.
+
+## Makefile
+
+Govy ships with a Makefile which is well documented and should cover most if
+not all development cycle needs.
+Run `make help` to display short description for each target.
+
+## CI
+
+Continuous integration pipelines utilize the same Makefile commands which
+you run locally within reproducible `devbox` environment.
+This ensures consistent behavior of the executed checks
+and makes local debugging easier.
+
+## Testing
+
+You can run all unit tests with `make test`.
+We also encourage inspecting test coverage during development, you can verify
+if the paths you're interested in are covered with `make test/coverage`.
+
+## Releases
+
+Govy adheres to the Go's official release workflow recommendations and
+requirements. Refer to the official
+[Go docs](https://go.dev/doc/modules/release-workflow) for more details.
+
+### Release automation
+
+We're using [Release Drafter](https://github.com/release-drafter/release-drafter)
+to automate release notes creation. Drafter also does its best to propose
+the next release version based on commit messages from `main` branch.
+
+Release Drafter is also responsible for auto-labeling pull requests.
+It checks both title and body of the pull request and adds appropriate labels. \
+**NOTE:** The auto-labeling mechanism will not remove labels once they're
+created. For example, If you end up changing PR title from `sec:` to `fix:`
+you'll have to manually remove `security` label.
+
+On each commit to `main` branch, Release Drafter will update the next release
+draft.
+
+In addition to Release Drafter, we're also running a script which extracts
+explicitly listed release notes and breaking changes which are optionally
+defined in `## Release Notes` and `## Breaking Changes` headers.
+It also performs a cleanup of the PR draft mitigating Release Drafter
+shortcomings.
+
+## Code generation
+
+Some parts of the codebase are automatically generated.
+We use the following tools to do that:
+
+- [embed-example-in-readme.bash](../scripts/embed-example-in-readme.bash)
+  for embedding tested examples in [README.md](../README.md).
+
+## Validation
+
+We're using our own validation library to write validation for all objects.
+Refer to this [README.md](../internal/validation/README.md) for more information.
+
+## Dependencies
+
+Renovate is configured to automatically merge minor and patch updates.
+For major versions, which sadly includes GitHub Actions, manual approval
+is required.