Merge branch 'main' into cran-2.3.4

Brings the 2.3.4 hotfix to `main` once this branch is merged with a merge commit,
which makes the `v2.3.4` tag reachable from `main`.

Conflicts resolved:
- `.github/`, `.Rbuildignore`, `.gitignore`, `DESCRIPTION` and `tests/testthat/test-other.R` from `main`.
  `main` keeps its development version, and its `test-other.R` fixture lives in a helper
  and already uses `names =` in `structure()`.
- Rd files from `main`, which has the newer roxygen2.
  `man/pipe.Rd` merges cleanly and keeps `\usage` from the hotfix.
- `CITATION.cff` from the hotfix, which names the released 2.3.4.
- `NEWS.md` with `main`'s development sections on top,
  then the 2.3.4 section as in the tag message, then 2.3.3.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019iwyUfQ6pFAhL3jUUocHFm

Author: claude

.Rbuildignore

@@ -67,6 +67,9 @@
 ^scripts$
 ^\.claude$
 ^\.build$
+^lifecycle$
+^jarl\.toml$
+^touchstone$
 ^man/dot-igraph.progress\.Rd$
 ^man/dot-igraph.status\.Rd$
 ^man/dot-extract_constructor_and_modifiers\.Rd$

.github/workflows/custom/after-install/action.yml

@@ -17,11 +17,6 @@ runs:
     # automatically via tests/testthat/helper-migrations.R.
     - name: Regenerate argument-migration blocks and check for drift
       run: |
-        # Release branches cut from a tag that predates the registry have no generator.
-        if [ ! -f tools/generate-migrations.R ]; then
-          echo "tools/generate-migrations.R not found, nothing to check."
-          exit 0
-        fi
         Rscript tools/generate-migrations.R
         if ! git diff --exit-code -- R; then
           echo "::error::Generated ARG_HANDLE blocks are out of sync with the registry (tools/migrations/)."

.github/workflows/touchstone-comment.yaml

@@ -1,7 +1,10 @@
 name: Continuous Benchmarks (Comment)
 
 concurrency:
-  group: ${{ github.workflow }}-${{ github.head_ref }}
+  # `github.head_ref` is empty for `workflow_run` events,
+  # which put every PR into one shared group,
+  # so a comment job for one PR cancelled the one for another.
+  group: ${{ github.workflow }}-${{ github.event.workflow_run.head_branch }}
   cancel-in-progress: true
 
 on:

.gitignore

@@ -31,3 +31,4 @@ cran
 /tests/testthat/_problems/
 /.build/
 .ccache/
+lifecycle

AGENTS.md

@@ -78,11 +78,13 @@ pak::pak(dependencies = "Config/Needs/build")
 - Document all arguments and return values
 - Document internal functions using devtag (work in progress)
 - Link to C documentation using `@cdocs` tag: `#' @cdocs igraph_function_name`
+- Write "ID"/"IDs" (not "id"/"ids") when referring to vertex/edge IDs in documentation *prose*. Lowercase stays only where the token is code: argument names, runnable `@examples`, and spans in `` `...` `` or `\code{}`. Run `Rscript tools/check-id-casing.R` to find violations in roxygen prose.
 - Always run `devtools::document()` after updating documentation
 
 ### Naming Conventions
 
 - Use `max` for maximal (graph theory term: a vertex is maximal if no other vertex dominates it) and `largest` for maximum (the biggest value in a set)
+- Use `make_xxx()` for functions creating graphs in a deterministic way, and `sample_xxx()` for functions sampling graphs from some ensemble
 
 ### New functions
 
@@ -94,7 +96,7 @@ All new functions must include:
 - A concept so that it exists in the pkgdown reference index
 - An "experimental" badge via `r lifecycle::badge("experimental")`
 - All arguments in `snake_case`, with documentation and suitable defaults
-- An ellipsis guarded with `check_dots_empty()` separating mandatory and optional arguments
+- An ellipsis guarded with `check_dots_empty()` separating the head (required and defining arguments) from keyword-only options, following the zoning rules in [CONTRIBUTING.md](CONTRIBUTING.md#argument-order-and-the-ellipsis)
 - Argument validation using built-in `check_*()` functions or `igraph_arg_match()`
 
 **For callback functions:**

CONTRIBUTING.md

@@ -141,6 +141,93 @@ style to the code (see also the [lintr package](https://lintr.r-lib.org/)).
 Look at the style (indentation, braces, etc.) of some recently committed bigger
 change, and try to mimic that.
 
+### Argument Order and the Ellipsis
+
+Every exported function separates its arguments into two zones
+with an ellipsis (`...`):
+arguments *before* the ellipsis may be passed by position,
+arguments *after* it are keyword-only.
+This lets us add, reorder, and rename keyword-only arguments
+in later releases without breaking user code,
+and it keeps user code readable
+because rarely-used options must be spelled out.
+
+Which arguments go before the ellipsis (the "head")?
+
+1. **All required arguments** (arguments without a default),
+   with the graph or other primary data first.
+   This holds even when a function has three or more required arguments:
+   a required argument after `...` could still only be passed by name,
+   which hides it from the signature-reading eye
+   and produces worse error messages when it is forgotten.
+2. **Defining optional arguments** may follow —
+   but only when they answer *what* is computed rather than *how*:
+   - the vertices, edges, or other objects the function operates on,
+     such as `v` in `degree()` or `nodes` in `ego()`;
+   - the parameters of a model or generator,
+     such as `power` and `m` in `sample_pa()`;
+   - an enum that selects the essential variant of the operation,
+     such as `type` in `as_adjacency_matrix()`.
+
+   As a rule of thumb, the head should not exceed three or four arguments;
+   when in doubt, put an argument after the ellipsis.
+   The head must never be empty, though:
+   at least the function's primary argument stays positional,
+   and a signature whose arguments *all* sit behind the ellipsis
+   is a sign that the function should not carry an ellipsis at all.
+
+Everything else goes after the ellipsis (the "tail"),
+roughly in this order:
+
+1. interpretation modifiers, such as `mode`, `directed`, `weights`, `loops`;
+2. output shape and format, such as `normalized`, `names`, `sparse`;
+3. algorithm selection and tuning, such as `algorithm`, `options`, callbacks;
+4. deprecated arguments, always last.
+
+This follows the tidyverse design guide
+([required args before `...`, optional after](https://design.tidyverse.org/dots-after-required.html),
+[important args first](https://design.tidyverse.org/important-args-first.html),
+[required args have no defaults](https://design.tidyverse.org/required-no-defaults.html))
+with one deliberate deviation:
+the tidyverse places `...` directly after the *required* arguments,
+whereas we allow a small number of *defining optional* arguments
+to stay ahead of it (rule 2 above).
+igraph's API predates these conventions by two decades,
+and idiomatic calls like `degree(g, 1:3)` or `sample_pa(100, 1.5)`
+are pervasive in scripts, books, and teaching material.
+Deprecating the idiomatic form of a function
+would generate warning noise without a safety benefit;
+the value of keyword-only arguments lies in the long tail of options,
+not in the one or two arguments everyone knows by heart.
+
+Defaults on either side of the ellipsis
+must be *constant expressions* --
+literals, `NULL`/`TRUE`/`FALSE`/`NA`,
+`c()` or `list()` of constants,
+or the `deprecated()` sentinel.
+A complex default -- an option lookup, `V(graph)`,
+a reference to another argument, a random draw --
+is evaluated lazily at an unpredictable time
+and hides the real behavior from the signature:
+declare the formal as `NULL`
+and resolve it in the body
+after all arguments are available.
+The migration generator enforces this rule for migrated signatures.
+
+New functions follow the same zoning,
+with `rlang::check_dots_empty()` guarding the ellipsis
+(no migration machinery needed);
+document the ellipsis with `@inheritParams rlang::args_dots_empty`.
+
+For existing functions, the signature change is *migrated*:
+a generated block recovers legacy positional or abbreviated calls
+and emits a single soft deprecation,
+so old code keeps working during a transition period.
+See [Argument-migration blocks](tools/README.md#argument-migration-blocks)
+for the mechanics,
+and declare migrations in a per-topic registry file
+under `tools/migrations/`.
+
 ### Documentation
 
 - Install roxygen2 but also [igraph.r2cdocs](https://github.com/igraph/igraph.r2cdocs).
@@ -156,6 +243,15 @@ igraph` to update the `.Rd` files.
 
 - Links to C docs are added automatically thanks to the igraph.r2cdocs's roclet.
 
+- Write "ID"/"IDs" (not "id"/"ids") when referring to vertex or edge IDs in
+documentation prose. Lowercase stays only where the token is code: argument
+names, runnable `@examples`, and spans wrapped in `` `...` `` or `\code{}`. You
+can check roxygen prose for stray lowercase forms with:
+
+```sh
+Rscript tools/check-id-casing.R
+```
+
 ### Maintaining igraph.r2cdocs
 
 To update the data (when the C docs index has changed after a release) in https://github.com/igraph/igraph.r2cdocs/, run the script that is `data-raw`, commit the csv file and push.

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: igraph
 Title: Network Analysis and Visualization
-Version: 2.3.4
+Version: 2.3.3.9042
 Authors@R: c(
     person("Gábor", "Csárdi", , "csardi.gabor@gmail.com", role = "aut",
            comment = c(ORCID = "0000-0001-7098-9676")),
@@ -35,7 +35,7 @@ URL: https://r.igraph.org/, https://igraph.org/,
 BugReports: https://github.com/igraph/rigraph/issues
 Depends:
     methods,
-    R (>= 3.5.0)
+    R (>= 4.0.0)
 Imports:
     cli,
     graphics,
@@ -60,7 +60,7 @@ Suggests:
     scales,
     stats4,
     tcltk,
-    testthat,
+    testthat (>= 3.3.0),
     vdiffr,
     withr
 Enhances: 
@@ -93,4 +93,4 @@ Encoding: UTF-8
 Roxygen: list(markdown = TRUE, roclets = c("collate", "namespace",
     "igraph.r2cdocs::docs_rd", "devtag::dev_roclet"))
 SystemRequirements: libxml2 (optional), glpk (>= 4.57, optional)
-Config/roxygen2/version: 8.1.0.9000
+Config/roxygen2/version: 8.1.1.9000

Makefile-cigraph

@@ -100,7 +100,7 @@ $(RAY2): src/vendor/%: vendor/%
 
 # R files that are generated/copied
 
-RGEN = R/aaa-auto.R src/rinterface.c \
+RGEN = .build/r-wrappers.stamp src/rinterface.c \
 	configure src/config.h.in
 
 # Files generated by stimulus
@@ -121,21 +121,32 @@ src/rinterface.c: \
            -t tools/stimulus/types-RC.yaml \
            -l RC
 
-R/aaa-auto.R: \
+# Stimulus generates a single R/aaa-auto.R blob, which tools/split-aaa-auto.R
+# then splits into per-category R/aaa-<cat>.R files driven by
+# tools/aaa-categories.yaml. The monolithic blob is written to .build/ so it
+# never lands in R/ itself.
+.build/r-wrappers.stamp: \
 		venv \
 		$(vendored_srcdir)/interfaces/functions.yaml \
 		$(vendored_srcdir)/interfaces/types.yaml \
 		tools/stimulus/aaa-auto.R.in \
 		tools/stimulus/functions-R.yaml \
-		tools/stimulus/types-RR.yaml
+		tools/stimulus/types-RR.yaml \
+		tools/aaa-categories.yaml \
+		tools/split-aaa-auto.R
+	mkdir -p .build
 	$(STIMULUS) \
            -f $(vendored_srcdir)/interfaces/functions.yaml \
            -f tools/stimulus/functions-R.yaml \
            -i tools/stimulus/aaa-auto.R.in \
-           -o R/aaa-auto.R \
+           -o .build/aaa-auto.R \
            -t $(vendored_srcdir)/interfaces/types.yaml \
            -t tools/stimulus/types-RR.yaml \
            -l RR
+	Rscript tools/split-aaa-auto.R .build/aaa-auto.R
+	touch $@
+
+r_wrappers: .build/r-wrappers.stamp
 
 # This is the list of all object files in the R package,
 # we write it to a file to be able to depend on it.
@@ -157,9 +168,9 @@ pre_build: venv patches $(RSRC) \
 	$(PARSER2)
 
 clean:
-	rm -rf src/core src/vendor src/include src/config.h.in src/rinterface.c R/aaa-auto.R
+	rm -rf src/core src/vendor src/include src/config.h.in src/rinterface.c R/aaa-*.R .build
 	git -C $(top_srcdir) reset --hard
 
-.PHONY: all igraph force clean check check-cran check-rhub check-links install test src/sources.mk
+.PHONY: all igraph force clean check check-cran check-rhub check-links install test r_wrappers src/sources.mk
 
 .NOTPARALLEL:

NAMESPACE

@@ -13,16 +13,20 @@ S3method("[",communities)
 S3method("[",igraph)
 S3method("[",igraph.es)
 S3method("[",igraph.vs)
+S3method("[",igraphSDF)
 S3method("[<-",igraph)
 S3method("[<-",igraph.es)
 S3method("[<-",igraph.vs)
+S3method("[<-",igraphSDF)
 S3method("[[",communities)
 S3method("[[",igraph)
 S3method("[[",igraph.es)
 S3method("[[",igraph.vs)
 S3method("[[<-",igraph.es)
 S3method("[[<-",igraph.vs)
+S3method(as.data.frame,igraphSDF)
 S3method(as.dendrogram,communities)
+S3method(as.dendrogram,igraphHRG)
 S3method(as.hclust,communities)
 S3method(as.hclust,igraphHRG)
 S3method(as.igraph,igraphHRG)
@@ -376,7 +380,6 @@ export(get.adjlist)
 export(get.all.shortest.paths)
 export(get.data.frame)
 export(get.diameter)
-export(get.edge)
 export(get.edge.attribute)
 export(get.edge.ids)
 export(get.edgelist)
@@ -610,7 +613,6 @@ export(layout.fruchterman.reingold.grid)
 export(layout.gem)
 export(layout.graphopt)
 export(layout.grid)
-export(layout.grid.3d)
 export(layout.kamada.kawai)
 export(layout.lgl)
 export(layout.mds)