During reviews, I often find myself repeating the same comments and explanations. Many of these points have already been discussed numerous times. To help new contributors better understand the codebase and reduce the review burden, I propose extending the CONTRIBUTING.md document with a concise section on style and code guidelines.
The following topics could be documented:
-
Naming conventions
-
JSON tags for structs that represent a request body:
- When using
omitempty, the field type should be a pointer.
- Use
omitzero for structs and slices where appropriate.
-
URL tags for structs that represent query parameters:
- When using
omitempty, the field type should be non-pointer.
-
Pagination:
- Proper use of
ListOptions and ListCursorOptions.
-
Common types:
- For example,
ID should consistently use int64.
-
Generation patterns.
Some of these rules could eventually be enforced by linters (we already have sliceofpointers, structfield), but documenting them first would make expectations explicit and help contributors avoid common mistakes.
Additionally, we could analyze the repository to identify recurring review comments and common mistakes. Based on that analysis, we could expand CONTRIBUTING.md to address frequently misunderstood patterns and conventions.
This would make expectations clearer for contributors and help maintain consistency across the project.
During reviews, I often find myself repeating the same comments and explanations. Many of these points have already been discussed numerous times. To help new contributors better understand the codebase and reduce the review burden, I propose extending the CONTRIBUTING.md document with a concise section on style and code guidelines.
The following topics could be documented:
Naming conventions
owner,repo,org.ListOptions.JSON tags for structs that represent a request body:
omitempty, the field type should be a pointer.omitzerofor structs and slices where appropriate.URL tags for structs that represent query parameters:
omitempty, the field type should be non-pointer.Pagination:
ListOptionsandListCursorOptions.Common types:
IDshould consistently useint64.Generation patterns.
Some of these rules could eventually be enforced by linters (we already have
sliceofpointers,structfield), but documenting them first would make expectations explicit and help contributors avoid common mistakes.Additionally, we could analyze the repository to identify recurring review comments and common mistakes. Based on that analysis, we could expand
CONTRIBUTING.mdto address frequently misunderstood patterns and conventions.This would make expectations clearer for contributors and help maintain consistency across the project.