Add comprehensive documentation for resource extension points

[Copilot]

ASO v2 provides 9 extension interfaces for customizing resource behavior, but lacked documentation causing contributor friction. This adds ~3,700 lines of technical documentation covering all extension points.

Changes

New Documentation Structure

• docs/hugo/content/contributing/extension-points/ folder with overview and 9 detailed guides
• Each extension point documented with: interface definition, motivation, usage patterns, real examples, testing guidance
• Cross-referenced with Hugo-compatible links

Extension Points Documented

• ARMResourceModifier - Modify ARM payloads pre-submission (soft-delete, child resources)
• Deleter - Multi-step deletion, pre-deletion operations
• ErrorClassifier - Classify ARM errors as retryable/fatal
• Importer - Filter resources during asoctl import
• KubernetesSecretExporter - Export Azure secrets to Kubernetes
• PostReconciliationChecker - Defer Ready condition until async operations complete
• PreReconciliationChecker - Block reconciliation until prerequisites met
• PreReconciliationOwnerChecker - Block reconciliation based on owner state without accessing resource
• SuccessfulCreationHandler - One-time initialization post-creation

Note: Claimer was initially included but removed as it is an internal interface, not a contributor-facing extension point.

Code Enhancement

Enhanced interface comments in v2/pkg/genruntime/extensions/*.go to include usage guidance and problem statements inline.

Example

// Before: minimal comment
type ErrorClassifier interface {
    ClassifyError(...) (core.CloudErrorDetails, error)
}

// After: actionable guidance
// ErrorClassifier customizes how the reconciler reacts to Azure errors.
// Implement when:
// - Resource-specific error codes need special handling
// - Transient errors are misclassified as fatal
// - Error messages need resource-specific clarification
type ErrorClassifier interface {
    // ClassifyError evaluates errors, determining retry behavior.
    // cloudError: error from ARM
    // apiVersion: ARM API version used
    // next: default classification to chain
    ClassifyError(...) (core.CloudErrorDetails, error)
}

Each documentation page includes 5-6 implementation patterns with real codebase examples (KeyVault soft-delete, PrivateEndpoint approval, MySQL config filtering, Kusto cluster/database state blocking).

• Fixes Add documentation of resource extension points #3902

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Add documentation of resource extension points</issue_title>
<issue_description>Describe the current behavior

Currently we have little documentation of the various extension points available when adding a completely new resource. This lack of information has proven to be a hinderance for multiple contributors.

Describe the improvement

Add documentation describing the available extension points and when they should be used.

• Overview of extensions and extension implementation patterns
• Docs for ARMResourceModifier
• Docs for Claimer
• Docs for Deleter
• Docs for ErrorClassifier
• Docs for Importer
• Docs for KubernetesExporter
• Docs for PostReconciliationChecker
• Docs for PostReconciliationChecker
• Docs for SuccessfulCreationHandler

Copilot Instructions

• Create a new documentation folder under docs/hugo/content/contributing/ called extension-points and create an _index.md file to act as a table of contents.
• For each extension point identified above, write a separate documentation page to detail the purpose and use of the extension point.
• Each documentation page should have the following sections:
  • Description - a description of what the extension point does, and when it's invoked
  • Motivation - details about why the extension point is needed. Most everything you need here is already documented in the code, either at the point of declaration for the interface, or when it's implemented.
  • When to use - guidance on when the extension point should be implemented. You'll need to harvest comments from PRs that implemented the extension points to find all the existing commentary on this.
  • Example - pick a representative example of use of the extension point, and provide the code with annotations.

If you find the code for an extension interface is lacking, but find the information elsewhere, update the comments on the code, but take extra care not to change the declaration itself.
Some of these interfaces are also lacking documentation in the code; this should be extended at the same time.
</issue_description>

Comments on the Issue (you are @copilot in this section)

@matthchr Would be nice to do this, but low pri

• Fixes Add documentation of resource extension points #3902

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[theunrepentantgeek]

@copilot Please add documentation for PreReconciliationOwnerChecker - this is a variant of PreReconciliationChecker that was omitted from the original request.

[Copilot]

@copilot Please add documentation for PreReconciliationOwnerChecker - this is a variant of PreReconciliationChecker that was omitted from the original request.

Added documentation for PreReconciliationOwnerChecker in commit c04a5c3.

This extension is a specialized variant of PreReconciliationChecker that validates only the owner's state before reconciliation, without performing GET operations on the resource itself. It's used when the owner's state can completely block access to child resources (e.g., Kusto databases cannot be accessed when the cluster is powered off or updating).

The documentation includes:

• Detailed comparison with PreReconciliationChecker
• Real-world example from Kusto Database
• Clear guidance on when to use each checker
• Enhanced code comments in the interface definition

[theunrepentantgeek]

This is good, but there are a few things to tweak, @copilot. Please make the requested changes.

[Copilot]

This is good, but there are a few things to tweak, @copilot. Please make the requested changes.

All requested changes completed in commit df58f62:

• Fixed comment grammar in importer.go
• Updated _index.md description
• Changed "type assertion" to "type-check at the appropriate time"
• Removed Claimer documentation and deleted claimer.md file