Skip to content

Extend CONTRIBUTING.md with common code guidelines #4023

@alexandear

Description

@alexandear

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:

  1. Naming conventions

  2. 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.
  3. URL tags for structs that represent query parameters:

    • When using omitempty, the field type should be non-pointer.
  4. Pagination:

    • Proper use of ListOptions and ListCursorOptions.
  5. Common types:

    • For example, ID should consistently use int64.
  6. 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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions