docs(goerr-error-handling): add comprehensive guide for error handling using the goerr library to enhance Go error management practices

[m-mizutani]

No description provided.

[gemini-code-assist]

Summary of Changes

Hello @m-mizutani, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a new documentation file that serves as a comprehensive guide for Go developers on effectively handling errors using the goerr library. The aim is to standardize and enhance error management practices by providing clear instructions, function comparisons, and best practices for leveraging goerr's advanced features like stack traces, contextual values, and structured logging support.

Highlights

• New Documentation Guide: A comprehensive guide for error handling using the goerr library has been added, detailing its features and best practices for Go developers.
• Goerr Function Usage: The guide provides a clear table outlining when to use specific goerr functions for creating, wrapping, and adding context to errors, contrasting them with standard Go error handling.
• Best Practices: Detailed best practices are included, covering structured error messages, using context values for data, defining typed keys and tags, utilizing the Builder for shared context, and integrating with slog for structured logging.
• Quick Reference: A quick reference section summarizes key goerr functions for error creation, options, extraction, multiple error handling, builder patterns, type-safe keys, tags, and stack control.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request adds a comprehensive guide for using the goerr library. The documentation is well-structured and covers the main features of the library effectively. I've provided a few suggestions to enhance clarity and provide more complete examples, particularly around error categorization and the usage of tags and sentinel errors. I also suggested a minor formatting improvement for better readability.

[gemini-code-assist]

The 'NOT' column for 'Categorize errors' could be clearer. While sentinel errors can be used for categorization, a more common anti-pattern that tags help avoid is embedding category information as strings within the error message. This aligns better with the guide's general advice to use structured context over string manipulation.

Suggested change

	| Categorize errors | `goerr.T(tagValue)` | Sentinel errors for categories |
	| Categorize errors | `goerr.T(tagValue)` | Ad-hoc strings in error messages |

[gemini-code-assist]

The example for defining tags and sentinel errors is good, but it would be more helpful to also show how to apply and check for them. This provides a more complete picture of the pattern.

Suggested change

	var (
	TagNotFound = goerr.NewTag("not_found")
	TagValidation = goerr.NewTag("validation")
	)
	var (
	ErrNotFound = goerr.New("not found", goerr.ID("ERR_NOT_FOUND"))
	ErrInvalid = goerr.New("invalid input", goerr.ID("ERR_INVALID"))
	)
	var (
	TagNotFound = goerr.NewTag("not_found")
	TagValidation = goerr.NewTag("validation")
	)
	var (
	ErrNotFound = goerr.New("not found", goerr.ID("ERR_NOT_FOUND"))
	ErrInvalid = goerr.New("invalid input", goerr.ID("ERR_INVALID"))
	)
	// Example usage:
	//
	// To apply a tag:
	// err := goerr.New("user not found", goerr.T(TagNotFound))
	//
	// To check for a tag:
	// if goerr.HasTag(err, TagNotFound) { /* ... */ }
	//
	// To check for a sentinel error (even if wrapped):
	// if errors.Is(err, ErrNotFound) { /* ... */ }

[gemini-code-assist]

For better readability and structure, it's recommended to format the Quick Reference section as a bulleted list. This makes the different categories of functions easier to scan.

Suggested change

	**Error creation**: `goerr.New`, `goerr.Wrap`, `goerr.With`
	**Options**: `goerr.Value` / `goerr.V`, `goerr.TypedValue` / `goerr.TV`, `goerr.Tag` / `goerr.T`, `goerr.ID`
	**Extraction**: `goerr.Unwrap`, `goerr.AsErrors`, `goerr.Values`, `goerr.TypedValues`, `goerr.Tags`, `goerr.HasTag`, `goerr.GetTypedValue`
	**Multiple errors**: `goerr.Join`, `goerr.Append`, `(*Errors).ErrorOrNil`, `(*Errors).IsEmpty`, `(*Errors).Len`
	**Builder**: `goerr.NewBuilder`, `(*Builder).With`, `(*Builder).New`, `(*Builder).Wrap`
	**Type-safe keys**: `goerr.NewTypedKey[T]`, `goerr.TV`, `goerr.GetTypedValue`
	**Tags**: `goerr.NewTag`, `goerr.T`, `goerr.HasTag`, `(*Error).HasTag`
	**Stack control**: `(*Error).Unstack`, `(*Error).UnstackN`
	- **Error creation**: `goerr.New`, `goerr.Wrap`, `goerr.With`
	- **Options**: `goerr.Value` / `goerr.V`, `goerr.TypedValue` / `goerr.TV`, `goerr.Tag` / `goerr.T`, `goerr.ID`
	- **Extraction**: `goerr.Unwrap`, `goerr.AsErrors`, `goerr.Values`, `goerr.TypedValues`, `goerr.Tags`, `goerr.HasTag`, `goerr.GetTypedValue`
	- **Multiple errors**: `goerr.Join`, `goerr.Append`, `(*Errors).ErrorOrNil`, `(*Errors).IsEmpty`, `(*Errors).Len`
	- **Builder**: `goerr.NewBuilder`, `(*Builder).With`, `(*Builder).New`, `(*Builder).Wrap`
	- **Type-safe keys**: `goerr.NewTypedKey[T]`, `goerr.TV`, `goerr.GetTypedValue`
	- **Tags**: `goerr.NewTag`, `goerr.T`, `goerr.HasTag`, `(*Error).HasTag`
	- **Stack control**: `(*Error).Unstack`, `(*Error).UnstackN`