Adding Flow programming language (.flow) — popularity + naming check before PR

[godofecht]

Intent

We would like to add Flow (https://github.com/flooooooooooow/flow) as a Linguist language:

• Extension: .flow
• Grammar (MIT): https://github.com/flooooooooooow/flow-tmLanguage (source.flow)
• Type: programming (effects, autodiff, portable C backend)

Before opening a full PR, we want maintainers’ guidance on popularity and naming, because the .flow extension is noisy on GitHub.

Popularity / collision

Raw extension:flow search is dominated by Facebook Flow type-checker libdefs (*.js.flow, declare module, // @flow) — not this language. Those files currently classify as JavaScript and are not a separate Linguist language entry.

Useful queries:

• This language (org): https://github.com/search?type=code&q=org%3Aflooooooooooow+extension%3Aflow+NOT+is%3Afork (~1.7k files, single org)
• Distinctive tokens: https://github.com/search?type=code&q=extension%3Aflow+%22let+mut%22+NOT+is%3Afork
• Distinctive tokens: https://github.com/search?type=code&q=extension%3Aflow+%22evolves+as%22+NOT+is%3Afork
• Noise (Facebook): https://github.com/search?type=code&q=extension%3Aflow+%22declare+module%22+NOT+is%3Afork

We do not currently claim to clear the ~2000-file third-party bar once flooooooooooow is filtered out. Happy to wait and grow usage.

Questions for maintainers

1. Prefer waiting until third-party .flow usage clears the bar, vs opening a PR marked pending-popularity now?
2. Language display name: Flow vs Flow Lang (to avoid confusion with Facebook’s checker)?
3. Is a heuristic on .flow (Flow-lang vs JavaScript libdefs) the right approach when we do PR?

Ready artifacts

• Grammar repo: https://github.com/flooooooooooow/flow-tmLanguage
• Sample sources (MIT):
  • https://github.com/flooooooooooow/flow/blob/main/examples/effects/showcase.flow
  • https://github.com/flooooooooooow/flow/blob/main/examples/linalg/lu_decomposition.flow
  • https://github.com/flooooooooooow/flow/blob/main/examples/concurrency/channels.flow
  • https://github.com/flooooooooooow/flow/blob/main/compiler/src/lexer.flow

Thanks for any guidance — we would rather do this cleanly once than burn a premature PR.

[paulodearaujo]

Based on the current contribution rules, I would wait rather than open a pending-popularity PR.

Linguist explicitly says it does not accept very new or hobby languages and will close PRs that do not meet the usage threshold. For an extension expected to appear multiple times per repository, the bar is at least 2,000 files indexed in the last year, excluding forks, with a reasonable spread across unrelated users and repositories. Results dominated by the language owner's organization are filtered out during that assessment (requirements). By the numbers in the question, Flow does not clear that bar yet.

For the display name, Flow is the canonical project name and there is no current Flow entry or .flow extension in languages.yml. I would keep Flow as the display name unless the language project itself adopts “Flow Lang.” An alias such as flow-lang can help users select it without changing the displayed name. Calling it Flow Lang would not solve the actual .js.flow detection collision.

That collision still needs to be resolved, but a heuristic is not the mechanism here. As lildude points out below, if the new language were the only language registered for .flow, extension detection would return that single candidate before the heuristic strategy runs. The heuristic would therefore never be reached and would be rejected.

Before opening a PR, I would ask the maintainers which supported detection or metadata approach can exclude existing .js.flow libdefs. If there is no suitable approach, the collision itself may prevent .flow from being registered safely.

So my recommendation is: keep growing independent usage, save the search queries and licensed samples, and open the PR only after the owner-filtered search clears 2,000 with real repository diversity. Keep Flow as the name, and settle the .js.flow collision with the maintainers before proposing the language entry.

[lildude]

This AI response pretty much hits the nail on the head, except the heuristic would be pointless (and rejected) if this is the only language with this extension as linguist would never get through to the heuristic strategy as the extension strategy would return only one result.

[paulodearaujo]

You're right. I missed that the extension strategy returns immediately when .flow has only one candidate, so the heuristic never gets a chance to run. I corrected the recommendation above. Thanks for catching that.