docs: Update CONVENTIONS.md file

[mrrajan]

• Expands CONVENTIONS.md with comprehensive anti-pattern conventions identified in ADR-00018, covering: N+1 queries, unbounded queries, in-memory filtering, application-side counting, missing batch operations, recursive traversal, missing indexes, swallowed errors, stringly-typed APIs, code duplication, oversized functions, public API documentation, magic numbers, and raw SQL parameterization
  • Adds database resource conventions (table/column naming, column types, enums, indexes, foreign keys, migrations)
  • Refines existing tracing/instrumentation guidance with clearer scoping rules and logging framework migration policy (log:: → tracing::)

Reference PR - #2358

JIRA - https://redhat.atlassian.net/browse/TC-4289

Preview - https://github.com/mrrajan/trustify/blob/TC-4289-convention/CONVENTIONS.md

Summary by Sourcery

Expand and refine engineering conventions around observability and database usage, incorporating anti-pattern guidance and schema best practices into CONVENTIONS.md.

Documentation:

• Clarify tracing span usage, instrumentation scope, and logging framework migration from log:: to tracing:: for new and existing code.
• Document additional engineering conventions covering N+1 and unbounded queries, batching, counting, error handling, enums, magic numbers, and raw SQL safety requirements.
• Add database schema conventions for table/column naming, types, enums, indexes, foreign keys, and migrations, complementing existing migration and entity model patterns.

[sourcery-ai]

Reviewer's Guide

Updates CONVENTIONS.md to add detailed performance, database, and API design anti-pattern conventions derived from ADR-00018, and refines observability guidance including tracing scope and migration from log:: to tracing::.

Flow diagram for instrumentation scope conventions

flowchart TD
    A[Function_or_call_site] --> B{Performs_external_IO?}
    B -- No --> C[Do_not_instrument]
    B -- Yes --> D{Callee_has_instrument_attribute?}
    D -- Yes --> E[Do_not_add_dot_instrument_at_call_site]
    D -- No --> F[Wrap_await_with_dot_instrument_info_span]
    F --> G{Multiple_distinct_external_steps?}
    G -- Yes --> H[Use_nested_spans_for_each_external_step]
    G -- No --> I[Single_span_covers_operation]
    A --> J{Pure_in_memory_trivial_work?}
    J -- Yes --> C
    J -- No --> B

Loading

Flow diagram for logging framework migration conventions

flowchart TD
    A[Editing_Rust_source_file] --> B{File_uses_log_macros?}
    B -- Yes --> C[Migrate_log_macros_to_tracing_macros_in_same_change]
    B -- No --> D{Adding_new_logging?}
    D -- Yes --> E[Use_tracing_macros_only]
    D -- No --> F[No_logging_changes]
    C --> G[All_logging_now_uses_tracing]
    E --> G

Loading

File-Level Changes

Change	Details	Files
Refine tracing/instrumentation guidance and add logging framework migration policy.	Tightens guidance on when to add sub-operation spans, restricting them to external I/O steps and avoiding double instrumentation when callees are already instrumented. Introduces an explicit "Instrumentation scope" section defining what to instrument, when not to, and how to avoid redundant spans. Adds a "Logging framework" section requiring all new code to use tracing macros, and instructing developers to migrate existing log:: usage to tracing:: when modifying files.	CONVENTIONS.md
Add comprehensive anti-pattern conventions for performance, API design, and error handling derived from ADR-00018.	Defines conventions for N+1 queries, unbounded queries, in-memory filtering, application-side counting, batch/bulk operations, and recursive traversal limits. Adds guidance on missing database indexes, swallowed errors, stringly-typed APIs, code duplication, oversized functions, public API documentation, magic numbers, and raw SQL that bypasses parameterization, including examples of approved and avoided patterns. Clarifies how and when to push logic into SQL vs Rust, when to use enums instead of strings, and how to log or propagate errors instead of silently discarding them.	CONVENTIONS.md
Introduce database resource conventions for schema design, indexes, foreign keys, and migrations.	Adds conventions for table and column naming, preferred PostgreSQL column types, and enum storage strategies (PostgreSQL ENUM, integer-backed enums, and lookup tables). Documents index selection and naming guidance, foreign key and constraint usage (including ON DELETE semantics and NOT NULL defaults), and expectations for UNIQUE constraints. Extends migration conventions with numbering, reversibility, and schema-vs-data migration separation, referencing existing migration and entity model pattern sections.	CONVENTIONS.md

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey - I've reviewed your changes and they look great!

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[mrizzi]

I can see nothing about the *Creator pattern for data management as the one to be used and implemented.
For example the PurlStatusCreator I had to introduce in #2080.

The "forbidden" pattern is the *Context one that, if and where still used, should be, at this point, replaced by the *Creator pattern to fix the tech debt.
For example ProductContext.

@mrrajan I think it could be useful if you could run an agent against code and discussion in #2080 itself to derive the appropriate code conventions.

[ctron]

A few minor things. In general it's ok to merge. But I'll leave that button for someone else to press.

[mrrajan]

@ctron @mrizzi Updated the PR with the changes requested.

[mrizzi]

@mrrajan thanks for the changes, they reflect my expectations, especially in the race conditions generated by the SELECT-then-INSERT not atomic workflow implemented in the *Context pattern.