Skip to content

@team: annotations with colons don't work (but look like they should) #131

@technicalpickles

Description

@technicalpickles

@team: annotations with colons don't work (but look like they should)

What's happening

If you write @team: SomeTeam (with a colon), the gem just ignores it completely. The file shows up as "unowned" even though it looks like it has a perfectly valid team annotation. There's no error or warning - it just silently doesn't work.

What works vs what doesn't

This works ✅:

# @team Developer Productivity Async

This doesn't work ❌:

# @team: Developer Productivity Async

The difference? Just that colon after @team.

Why this is annoying

  1. Silent failures - Your file just shows up as "unowned" with zero indication why
  2. Confusing build errors - You get "missing ownership" errors even though the file clearly has a team annotation
  3. Feels broken - The annotation looks totally fine but just doesn't work
  4. Hard to debug - Nothing tells you the colon is the problem
  5. Inconsistent codebases - Some people figure out the no-colon rule, others don't

Real example that bit us

We had a file with # @team: Developer Productivity Async at the top. Looked fine, right?

  • bin/codeownership for_file spec/support/kafka_migration_validation.rb → "Unowned" 🤔
  • bin/codeownership validate --skip-autocorrect → "Some files are missing ownership" 😤
  • The error gave us no clue what was wrong
  • Had to manually compare against other files to figure out the colon was the problem

Why this happens

The regex in lib/code_ownership/private/ownership_mappers/file_annotations.rb looks for this exact pattern:

TEAM_PATTERN = T.let(%r{\A(?:#|//|-#) @team (?<team>.*)\Z}.freeze, Regexp)

It expects exactly @team (with a space) but doesn't handle @team: (with a colon). So the regex just doesn't match.

Environment

  • code_ownership version: 1.39.0
  • Ruby version: 3.4.5
  • Repository: Large monorepo with ~600+ team annotations

Why people expect colons to work

Every other Ruby magic comment uses colons:

# frozen_string_literal: true
# typed: strict  
# encoding: UTF-8
# rubocop:disable Style/StringLiterals

So when you're writing a file header, this feels totally natural:

# @team: Developer Productivity Async
# typed: strict
# frozen_string_literal: true

But only the @team line gets ignored while the others work fine. It's just inconsistent with how the rest of the Ruby ecosystem works.

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't workingenhancementNew feature or requesttriageA new issue that needs review by the core team

    Type

    No type

    Projects

    Status

    Triage

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions