bump to v3.1.0

- v3.1.0
  - added `Join()` to compliant with go1.20 errors.Join
  - reviewed all of testcases

CHANGELOG

@@ -0,0 +1,60 @@
+# CHANGELOG
+
+- v3.1.0
+  - added `Join()` to compliant with go1.20 errors.Join
+  - reviewed all of testcases
+
+- v3.0.21 ..
+    - add: `RegisterCode()` at top level for initialize user-defined Coded decl
+    - godoc and fix/imp Attach() to copy inner errors' StackTrace
+    - fix Is(): Is(err, errors.BadRequest) might be dead lock or cannot return the test result probably
+    - new lint + fmr
+    - imp: remove redundant codes
+    - update withStackInfo.Stack with WithData() - specially for defer recover codes
+
+- v3.0.15
+  - fix: make Is() work for go1.12 and below
+
+- v3.0.13
+  - fea: IsDescended for error template test
+  - fix: code and causes are present at same time
+
+- v3.0.11
+  - changed the `FormatWith` interface to support error template feature.
+
+- v3.0.10
+  - support go1.11-17,18+
+
+- v3.0.9
+  - fix: WithErrors will check IsEmpty on an error container and avoid adding it if empty.
+
+- v3.0.8
+  - restore error message template
+  - all features in v2 are restored with a new fluent style
+
+- v3.0.7
+  - fix coverall upload
+  - godoc
+  - better sites/taggedsites output
+
+- v3.0.6
+  - back to master branch
+
+- v3.0.5
+  - break out `New(...).Attach(...)`, instead of `New(...).WithErrors(...)`, so that we can make the type architecture clearly and concisely.
+  - `Builable` and `Error` interface are the abstract representations about our error objects.
+  - bugs fixed
+  - more godoc
+
+- v3.0.3
+  - review the backward compatibilities
+
+- v3.0.0
+  - rewrite most codes and cleanup multiple small types
+  - use `New(...)` or `NewBuilder()` to make an error with code, message, inner error(s) and customizable stacktrace info.
+
+- v2.x
+
+- v1.x
+
+- v0.x

README.md

@@ -7,20 +7,34 @@
 [![Coverage Status](https://coveralls.io/repos/github/hedzr/errors/badge.svg)](https://coveralls.io/github/hedzr/errors)
 [![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fhedzr%2Ferrors.svg?type=shield)](https://app.fossa.com/projects/git%2Bgithub.com%2Fhedzr%2Ferrors?ref=badge_shield)
 
-Wrapped errors and more for golang developing (not just for go1.13+).
+Wrapped errors and more for golang developing (not just for go1.13+, go1.20+).
 
-`hedzr/errors` provides the compatbilities to your old project up to go 1.13.
+`hedzr/errors` provides the compatibilities to your old project up to go 1.20.
 
 `hedzr/errors` provides some extra enhancements for better context environment saving on error occurred.
 
-## Import
+## Features
 
-```go
-import "gopkg.in/hedzr/errors.v3"
-```
+- Simple migrating way from std errors: all of standard functions have been copied to
+- Better `New()`:
+  - format message inline: `err := errors.New("hello %s", "world")`
+  - format with `Opt`: `err := errors.New(errors.WithErrors(errs...))`
+  - cascade format: `err := errors.New().WithErrors(errs...)`
+  - Stacktrace awareness
+  - Container for canning errors: [Error Container (Inner/Nested)](#error-container-innernested)
+  - error template: [Format message instantly but the text template can be given at beginning](#error-template) 
+- Codes: treat a number as an error object
+- Unwrap inner canned errors one by one
+- No mental burden
+
+### Others
 
 ## History
 
+- v3.1.0
+  - added `Join()` to compliant with go1.20 errors.Join
+  - reviewed all of testcases
+
 - v3.0.21 ..
     - add: `RegisterCode()` at top level for initialize user-defined Coded decl
     - godoc and fix/imp Attach() to copy inner errors' StackTrace
@@ -29,48 +43,9 @@ import "gopkg.in/hedzr/errors.v3"
     - imp: remove redundant codes
     - update withStackInfo.Stack with WithData() - specially for defer recover codes
 
-- v3.0.15
-  - fix: make Is() work for go1.12 and below
-
-- v3.0.13
-  - fea: IsDescended for error template test
-  - fix: code and causes are present at same time
-
-- v3.0.11
-  - changed the `FormatWith` interface to support error template feature.
-
-- v3.0.10
-  - support go1.11-17,18+
-
-- v3.0.9
-  - fix: WithErrors will check IsEmpty on an error container and avoid adding it if empty.
+- OLDER in [CHANGELOG](https://github.com/hedzr/errors/blob/master/CHANGELOG)
 
-- v3.0.8
-  - restore error message template
-  - all features in v2 are restored with a new fluent style
-
-- v3.0.7
-  - fix coverall upload
-  - godoc
-  - better sites/taggedsites output
-
-- v3.0.6
-  - back to master branch
-
-- v3.0.5
-  - break out `New(...).Attach(...)`, instead of `New(...).WithErrors(...)`, so that we can make the type architecture clearly and concisely.
-  - `Builable` and `Error` interface are the abstract representations about our error objects.
-  - bugs fixed
-  - more godoc
-
-- v3.0.3
-  - review the backward compatibilities
-
-- v3.0.0
-  - rewrite most codes and cleanup multiple small types
-  - use `New(...)` or `NewBuilder()` to make an error with code, message, inner error(s) and customizable stacktrace info.
-
-## Features
+## Compatibilities
 
 These features are supported for compatibilities.
 
@@ -80,6 +55,7 @@ These features are supported for compatibilities.
 - `func Is(err, target error) bool`
 - `func New(text string) error`
 - `func Unwrap(err error) error`
+- `func Join(errs ...error) error`
 
 #### `pkg/errors` compatibilities
 
@@ -91,14 +67,6 @@ These features are supported for compatibilities.
   - in an error by `Wrap()`, stacktrace wrapped;
   - for your error, attached by `WithStack(cause error)`;
 
-#### Others
-
-- Codes
-- Inner errors  
-  We like the flatter inner errors more than the cascade chain, so the `Format("%w)` is a so-so approach to collect the errors. We believe the error slice is a better choice.
-- Unwrap inner errors one by one
-- Error Template
-
 ## Best Practices
 
 ### Basics
@@ -188,11 +156,11 @@ func TestForExample(t *testing.T) {
 func TestContainer(t *testing.T) {
   // as a inner errors container
   child := func() (err error) {
-    errContainer := errors.New("multiple tasks have errors")
+    var ec = errors.New("multiple tasks have errors")
+    defer ec.Defer(&err) // package the attached errors as a new one and return it as `err`
 
-    defer errContainer.Defer(&err)
     for _, r := range []error{io.EOF, io.ErrShortWrite, io.ErrClosedPipe, errors.Internal} {
-      errContainer.Attach(r)
+      ec.Attach(r)
     }
 
     doWithItem := func(item Item) (err error) {
@@ -201,13 +169,13 @@ func TestContainer(t *testing.T) {
     }
     for _, item := range SomeItems {
       // nil will be ignored safely, do'nt worry about invalid attaches.
-      errContainer.Attach(doWithItem(item))
+      ec.Attach(doWithItem(item))
     }
 
     return
   }
 
-  err := child()
+  err := child() // get the canned errors as a packaged one
   t.Logf("failed: %+v", err)
 }
 ```

doc.go

@@ -10,7 +10,7 @@ const (
 	// AppName const
 	AppName = "errors"
 	// Version const
-	Version = "3.0.23"
+	Version = "3.1.0"
 	// VersionInt const
-	VersionInt = 0x030017
+	VersionInt = 0x030100
 )