docs: Plan for upgrading C core from 0.10.17 to 1.0.1

[Copilot]

Summary

This PR adds a comprehensive analysis and plan for upgrading the vendored igraph C library from version 0.10.17 to 1.0.1. The document is at doc/c-core-upgrade-1.0.1-plan.md.

Key Findings

Scope of Change

• 760 commits between 0.10.17 and 1.0.1 (via 1.0.0-rc1 → 1.0.0 → 1.0.1)
• ~2,150 diff lines in functions.yaml (the C function interface definitions)
• ~249 diff lines in types.yaml (type system changes)
• ~111 references to igraph_attribute in rinterface_extra.c that need updating
• ~30 deprecated functions removed
• ~45 function signature changes (parameter additions, type changes, reordering)

Approaches Analyzed

Approach	Verdict
A: "Big Bang" vendor + fix everything	❌ Too large, previously failed
B: Vendor + skip failing tests	✅ Viable fallback
C: Incremental commit-by-commit vendoring	⚠️ Not effective (changes arrive as large merges)
D: Rewritten upstream history	⚠️ Sound but not cost-effective
E: Hybrid — preparatory PRs + vendor + skip-and-fix	✅ Recommended

Recommended Strategy (Approach E)

Phase 1 — Preparatory PRs (on current 0.10.17):

1. Type renames in Stimulus configs (mechanical, fully automatable)
2. Remove deprecated function wrappers (mostly automatable)
3. Pre-adapt attribute handler where possible
4. Forward-compatible parameter additions

Phase 2 — Vendor 1.0.1:
5. Single PR: vendor, fix compilation, skip failing tests

Phase 3 — Restore tests:
6–N. Fix skipped tests by category in individual PRs

Agentic History Rewrite Assessment

The idea of creating a synthetic series of commits between 0.10.17 and 1.0.1 where each builds and passes tests is not practical due to:

• Entangled changes across many feature branches
• The attribute handler overhaul being an atomic ~500-line rewrite
• Multi-repo git orchestration beyond current agent capabilities

However, the concept is effectively captured by the preparatory PRs approach: each PR is a small, reviewable, independently-testable step toward the migration.

Effort Estimate

• Total: 3–6 weeks across all phases
• Critical path: attribute handler rewrite in rinterface_extra.c