Comprehensive plan: argument renames for 3.0.0

[krlmlr]

The argument-migration machinery built for 3.0.0
(#2757 rationale, #2779 registry, generated ARG_HANDLE recovery blocks)
makes argument renames feasible for the first time
without breaking user code:
a registry entry maps an old name to a new one,
legacy callers — positional, abbreviated, or using the old name —
are recovered, and a single lifecycle::deprecate_soft("3.0.0", …)
warns once per call while returning the correct result.
A rename is now a registry entry plus a signature/docs change.

This issue consolidates every open rename discussion
so the naming decisions can be made once, coherently,
and then executed mechanically through the registry.

Closes #691.
Closes #853.
Closes #692.
Closes #526.

State of play (counts over the 529 exported, non-deprecated functions)

family	spellings in use today	proposed direction
vertex selector	v 15 (betweenness, degree, distances, …) · vids 13 (closeness, strength, page_rank, …) · nodes 9 (ego family, constraint, alpha/power_centrality) · vertex 1 (cluster_spinglass) · index 11 (attribute accessors)	decide: v vs vids vs vertices — all three are on record (see below)
edge selector	eids 6 · es 4 · e 1 (edge_betweenness)	must mirror the vertex decision (#853: "If we go with vids, this should be eids. If we go with v this should be e.")
vertex count in generators	nodes-as-count 14 (sample_grg, sample_pref, sample_forestfire, centr_*_tmax, graph_from_graphdb, …)	n (62 functions already use it; #692 scheme, essentially uncontested)
weights	weights 52 · weight 1 (graph_from_graphnel) · w 2 (make_chordal_ring) · vertex.weights 3 vs vertex_weights 1	weights (no existing issue; new finding)
algorithm selection	method 15 · algorithm 6 · algo 3 (page_rank, feedback_arc_set, feedback_vertex_set) · implementation 2 · impl 1	algorithm for algorithm choice (#526); open: does method stay for comparison/isomorphism methods?
iterations	maxiter 7 · niter 6 · steps 5 (walk lengths) · n_iterations 1 (cluster_leiden); layout_with_fr/kk carry both niter and maxiter	maxiter (per #1107), keep steps where it means walk length
normalized	normalized 9 · scale 1 (hits_scores) · rescale 1 (power_centrality) · norm 1 (tk_coords)	normalized (new finding)
mode	mode 76 (settled by #495); legacy neimode/father still sit as trailing formals in bfs()/dfs()	purge the legacy trailing aliases via the registry
case policy	dotted argument names: 211 occurrences (120 unique, e.g. cut.prob, out.deg, vertex.weights) vs snake_case 8	decide — largest single decision, see questions

(Underlying data: full signature inventory in the migration tooling;
types(vector) vs type/which(variant switch) were checked and are
mostly different semantics — only the variant-switch spellings are
unification candidates.)

The selector decision — three documented positions

• v — szhorvat in Align v/vids argument name? #853: "I propose using v … generic (does not
  imply integers) and simple."
• vids — Inconsistent naming of vertex selector parameters #691's lean; draft PR Standardize vertex selector parameter name to vids #2458 implements it.
• vertices — schochastics' scheme in Inconsistent naming: "vertex" vs "node" #692 (June 2025): "n for
  number of nodes (scalar); vertices for subset …; v (or vertex)
  for a specific vertex. This would eliminate vids and nodes" —
  szhorvat: "Sounds good", ntamas agreed; maelle and krlmlr leaned the
  same way in Align v/vids argument name? #853. Draft PR Standardize API parameter naming: nodes → n, vids → vertices #2450 implements it.

The #692 scheme is the most recent point of near-consensus and also
settles nodes → n and the scalar-vertex case; it implies
eids → edges? No — the edge side needs an explicit pick too
(edges is taken by constructor input in 14 functions).

Open PRs superseded by this issue

• Standardize vertex selector parameter name to vids #2458 (draft, Copilot): everything → vids. Contradicts Standardize API parameter naming: nodes → n, vids → vertices #2450.
• Standardize API parameter naming: nodes → n, vids → vertices #2450 (draft, Copilot): nodes → n, selectors → vertices.
• Standardize algorithm parameter names from algo/method to algorithm #2456 (draft, Copilot): algo/method → algorithm via
  deprecate_warn(), predates the registry.

All three hard-code mutually inconsistent conventions, predate the
migration machinery, and have merge conflicts —
recommend closing them once this issue lands, and reimplementing the
agreed scheme through tools/migrations/ registries.
#2742 (attr-comb snake_case renames, schochastics) is already built on
the registry and proceeds independently as the live precedent.

Execution mechanics (once names are agreed)

1. One registry entry per function
   (old = function(graph, nodes, …), new = function(graph, vertices = NULL, …)) —
   the rename rides the same ARG_HANDLE block as the keyword-only move,
   so users see one deprecation per call, not two waves.
2. Old names are recovered by name and by unambiguous abbreviation;
   prefix hazards are checked by the generator
   (renamed-away names that prefix a head arg are rejected — feat(migrations): allow head/recoverable prefix overlaps, guarded at run time #2787).
3. Hard deprecation no earlier than the release after 3.0.0;
   discuss: protocol for renaming/deprecating functions #2086 documents the CRAN fallout of moving faster.

Questions for maintainers

• Case policy: snake_case for renamed/new argument names
  (the Use snake_case in arguments to _impl functions. #2461/refactor: snake_case attr-comb options & arguments, soft-deprecate dotted names #2742 direction) or keep dot.case?
  If snake: rename all ~120 dotted names, or only names touched
  for other reasons?
• Vertex selector: v, vids, or vertices
  (with v reserved for scalar-vertex functions per Inconsistent naming: "vertex" vs "node" #692)?
  Krlmlr's survey precondition in Align v/vids argument name? #853 is satisfied by the table
  above.
• Edge mirror: e, eids, or spell it out — and what, given
  edges is taken by constructors?
• Does index in the attribute accessors
  (vertex_attr(), set_vertex_attr(), …) join the selector
  rename?
• Context-specific names: keep/extend from/to
  (szhorvat suggested distances(v =) → from eventually;
  krlmlr floated from_vertices/to_vertices)?
• Generators: any objection to nodes → n everywhere,
  including centr_*_tmax() and graph_from_graphdb()?
• Algorithm family: everything → algorithm, or keep method
  for comparison/isomorphism (the Standardize algorithm parameter names from algo/method to algorithm #2456 split)?
  Fold in impl/implementation?
• Iterations: maxiter per Decide on niter vs maxiter for layout_with_fr() #1107? Keep steps for walk
  lengths? Fold in cluster_leiden's n_iterations?
• Rollout: one 3.0.0 wave (single deprecation per call) vs
  staged per-family waves?
• C-interface sync: Inconsistent naming: "vertex" vs "node" #692 recorded agreement to sync names with
  C/igraph's interfaces/functions.yaml "for the release that is
  based on C/igraph 1.0" — should the R wave wait for, align with,
  or lead that?
• Name-reuse policy: propose never reusing a hard-deprecated
  old name for a different meaning — the recovery machinery would
  silently reinterpret old code.
• Migrate the existing hand-rolled alias formals
  (neimode/father in bfs/dfs, maxiter in layout_with_fr/kk,
  resolution_parameter in cluster_leiden) into the registry so
  the signatures shrink to canonical names?

Related, deliberately not closed here:
#622 (mode defaults — companion defaults issue),
#188 (selector input semantics),
#1121 (deprecation-advancement tooling),
#2780 (@param … docs standardization),
#994 (remaining item is a function rename;
its circular → periodic argument rename already shipped via #1352),
#495 / #1107 / #2461 / #2086 (background, already closed).

[krlmlr]

Also: no.sim -> no_sim (and underscores everywhere).

[krlmlr]

And column.wise -> column_wise .

[krlmlr]

Think about Mu -> big_mu or similar. Should we do case-sensitive argument names in the future?

[krlmlr]

cut.prob

[krlmlr]

sample.size (and clash with sample in the original pre-ellipsis implementation)?

[krlmlr]

min.weight and max.weight

[krlmlr]

vertex.weights

[krlmlr]

neighbors(): v argument?

[krlmlr]

What about underscores in positional arguments? How to get rid of them? Can the compat code handle this too?

[maelle]

I'd vote for explicit names, for instance "vertices" is in my opinion better than "v" or even "vids".

[maelle]

maxiter -> max_iterations? max_iter?