-
Notifications
You must be signed in to change notification settings - Fork 2.2k
Description
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
- File names.
- Receiver names.
- Request option types.
- Response types.
- Method and variable naming.
- Common variable names such as
owner,repo,org. - Naming for enterprise & organization scoped, see Consistent naming for enterprise & organization scoped functions #3761.
- Common structs such as
ListOptions.
-
JSON tags for structs that represent a request body:
- When using
omitempty, the field type should be a pointer. - Use
omitzerofor structs and slices where appropriate.
- When using
-
URL tags for structs that represent query parameters:
- When using
omitempty, the field type should be non-pointer.
- When using
-
Pagination:
- Proper use of
ListOptionsandListCursorOptions.
- Proper use of
-
Common types:
- For example,
IDshould consistently useint64.
- For example,
-
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.