From f79a34eee0ed5f82850951a4a3b73e21d4b69c71 Mon Sep 17 00:00:00 2001 From: Jon Freer Date: Tue, 20 Sep 2022 23:13:50 -0700 Subject: [PATCH] Update documentation. (#69) --- README.md | 57 +++++++++++++++++++++++++++++++++++++++++++++------- v4/README.md | 36 +++++++++++++++++++++++++++++---- 2 files changed, 82 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 80e3c58..9b1b8de 100644 --- a/README.md +++ b/README.md @@ -40,7 +40,35 @@ For SQL datastores, also enjoy: ## Release information -### [4.0.0-beta][v4.0.0-beta] +| Version | Supported | Documentation | +|---------|-----------|-------------------------------| +| `V4` | ✅ | [See][v4-docs] `v4/README.md` | +| `V3` | ✅ | None | +| `V2` | ❌ | None | +| `V1` | ❌ | None | + +### V4 + +#### [4.0.0-beta.3][v4.0.0-beta.3] + +- Various dependency upgrades to address vulnerability [alerts][dependabot-alerts]. + - Upgraded `github.com/uber-go/tally` dependency to version `v3.4.2`. + - Upgraded `github.com/stretchr/testify` dependency to version `v1.8.0`. + - Upgraded `go.uber.org/zap` dependency to version `v1.21.1`. + +#### [4.0.0-beta.2][v4.0.0-beta.2] + +- Introduce initial round of benchmarks. +- Introduce support for 4 more additional metrics. + - `unit.retry.attempt` + - `unit.insert` + - `unit.update` + - `unit.delete` +- Improve documentation & switch to pkg.go.dev. +- Introduce metric demo. + - `make demo` + +#### [4.0.0-beta][v4.0.0-beta] - Introduce `unit` package for aliasing. - Reduces API footprint. @@ -53,22 +81,31 @@ For SQL datastores, also enjoy: create based on provided options. - Reconsolidate uniter functionality. -### [3.2.0][v3.2.0] +### V3 + +#### [3.2.1][v3.2.1] + +- Various dependency upgrades to address vulnerability [alerts][dependabot-alerts]. + - Upgraded `github.com/uber-go/tally` dependency to version `v3.4.2`. + - Upgraded `github.com/stretchr/testify` dependency to version `v1.8.0`. + - Upgraded `go.uber.org/zap` dependency to version `v1.21.1`. + +#### [3.2.0][v3.2.0] - Introduce [lifecycle actions][actions-pr]. - Introduce [concurrency support][concurrency-pr]. -### [3.0.0][v3.0.0] +#### [3.0.0][v3.0.0] - Introduce support for Go modules. -### 2.x.x +### V2 -- NO LONGER SUPPORTED. CODE REMOVED. +- NO LONGER SUPPORTED. CODE REMOVED. SEE `v2.x.x` [TAGS][tags]. -### 1.x.x +### V1 -- NO LONGER SUPPORTED. CODE REMOVED. +- NO LONGER SUPPORTED. CODE REMOVED. SEE `v1.x.x` [TAGS][tags]. > Versions `1.x.x` and `2.x.x` are no longer supported. Please upgrade to `3.x.x+` to receive the latest and greatest features, such as @@ -118,6 +155,12 @@ how we do things. [release-img]: https://img.shields.io/github/tag/freerware/work.svg?label=version [blog]: https://medium.com/@freerjm/work-units-ec2da48cf574 [blog-img]: https://img.shields.io/badge/blog-medium-lightgrey +[v4-docs]: https://github.com/freerware/work/blob/master/v4/README.md [v3.2.0]: https://github.com/freerware/work/releases/tag/v3.2.0 +[v3.2.1]: https://github.com/freerware/work/releases/tag/v3.2.1 [v3.0.0]: https://github.com/freerware/work/releases/tag/v3.0.0 [v4.0.0-beta]: https://github.com/freerware/work/releases/tag/v4.0.0-beta +[v4.0.0-beta.2]: https://github.com/freerware/work/releases/tag/v4.0.0-beta.2 +[v4.0.0-beta.3]: https://github.com/freerware/work/releases/tag/v4.0.0-beta.3 +[tags]: https://github.com/freerware/work/tags +[dependabot-alerts]: https://github.com/freerware/work/security/dependabot?q=is%3Aclosed diff --git a/v4/README.md b/v4/README.md index e50685f..e97d864 100644 --- a/v4/README.md +++ b/v4/README.md @@ -130,6 +130,32 @@ uniter := unit.NewUniter(opts...) u, err := uniter.Unit() ``` +## Frequently Asked Questions (FAQ) + +### Are batch data mapper operations supported? + +In short, yes. + +A work unit can accommodate an arbitrary number of entity types. When creating +the work unit, you indicate the data mappers that it should use when persisting +the desired state. These data mappers are organized by entity type. As such, +batching occurs for each operation and entity type pair. + +For example, assume we have a single work unit and have performed a myriad +of unit operations for entities with either a type of `Foo` or `Bar`. All inserts +for entities of type `Foo` will be [passed][insert-method-ref] to the corresponding data mapper in +one shot via the `Insert` [method][insert-method]. This essentially then relinquishes control to you, +the author of the data mapper, to handle all of those entities to be inserted +in however you see fit. You could choose to insert them all into a relational +database using a single `INSERT` query, or perhaps issue an HTTP request to +an API to create all of those entities. However, inserts for entities of type +`Bar` will be batched separately. In fact, it's most likely the data mapper to handle +inserts for `Foo` and `Bar` are completely different types (and maybe even +completely different data stores). + +The same applies for other operations such as updates and deletions. All +supported data mapper operations follow this paradigm. + [uow]: https://martinfowler.com/eaaCatalog/unitOfWork.html [sql-data-mapper-doc]: https://godoc.org/github.com/freerware/work#SQLDataMapper [data-mapper-doc]: https://godoc.org/github.com/freerware/work#DataMapper @@ -151,13 +177,15 @@ u, err := uniter.Unit() [code-of-conduct]: https://github.com/freerware/work/blob/master/CODE_OF_CONDUCT.md [doc-img]: https://pkg.go.dev/badge/github.com/freerware/work/v4.svg [doc]: https://pkg.go.dev/github.com/freerware/work/v4 -[ci-img]: https://travis-ci.org/freerware/work.svg?branch=master -[ci]: https://travis-ci.org/freerware/work -[coverage-img]: https://coveralls.io/repos/github/freerware/work/badge.svg?branch=master -[coverage]: https://coveralls.io/github/freerware/work?branch=master +[ci-img]: https://github.com/freerware/work/actions/workflows/ci.yaml/badge.svg?branch=master +[ci]: https://github.com/freerware/work/actions/workflows/ci.yaml +[coverage-img]: https://codecov.io/gh/freerware/work/branch/master/graph/badge.svg?token=W5YH9TPP3C +[coverage]: https://codecov.io/gh/freerware/work [license]: https://opensource.org/licenses/Apache-2.0 [license-img]: https://img.shields.io/badge/License-Apache%202.0-blue.svg [release]: https://github.com/freerware/work/releases [release-img]: https://img.shields.io/github/tag/freerware/work.svg?label=version [blog]: https://medium.com/@freerjm/work-units-ec2da48cf574 [blog-img]: https://img.shields.io/badge/blog-medium-lightgrey +[insert-method]: https://github.com/freerware/work/blob/v4.0.0-beta.2/v4/data_mapper.go#L22 +[insert-method-ref]: https://github.com/freerware/work/blob/v4.0.0-beta.2/v4/best_effort_unit.go#L137