Fallout-build / Fallout-build/Fallout

[RFC #2] Extension-point catalogue for v12 SDK

Open
#98 1 comment 0 reactions 0 assignees View on GitHub
RFC target/vNext
Dominant language
C#
Stars
154
Forks
19
Avg merge
1d 22h
Merged PRs (30d)
15

Description

**RFC #2 — Extension-point catalogue for v12 SDK**

Self-RFC. The starter catalogue below is what we'll ship in `Fallout.Plugin.Sdk` 1.0 unless this discussion adds or removes points.

## Context
The SDK exposes a closed set of extension points — surfaces plugins contribute to. Each becomes a public, additive-only contract for the SDK's lifetime. Too few and the SDK is useless; too many and we lock in shapes we haven't validated.

## Proposed starter catalogue

| Extension point | What plugins contribute | Maps onto today's... |
|---|---|---|
| `IBuildMiddleware` | A handler that runs in one build phase (Initializing / DiscoveringTargets / Planning / Executing / Reporting). | The 23 init-pipeline attributes (`[InjectParameterValues]` etc.). |
| `IHost` + `IHostDetector` | A CI host adapter. Detector checks the environment; host emits CI-specific metadata. | `TeamCity`, `AzurePipelines`, `GitHubActions`, etc. derived from `Host`. |
| `IParameterSource` | Resolves `[Parameter]`-style values from a custom source (Vault, 1Password, env, args, parameter files). | `ParameterService` reflection logic. |
| `IToolWrapperContribution` | Registers a new `*Tasks` static facade for third-party tool wrappers. | The 62 first-party tool wrappers in `Fallout.Common.Tools.*`. |
| `ITargetLifecycleListener` | Lifecycle callbacks (target running / succeeded / failed / build finished). | `IOnTargetRunning`, `IOnTargetSucceeded`, etc. (the `IBuildExtension` hooks). |
| `IOutputSink` | Receives structured output events for logging, telemetry, or external observability. | Serilog enricher hooks. |

## Why this list
These six unify the four existing extensibility surfaces (lifecycle hooks, component interfaces, CI hosts, tool wrappers) into one coherent set. Each is something a contributor can plausibly ship in a plugin, and each already has a first-party implementation as the reference — nothing speculative.

Component interfaces (`ICompile`, `IPack`, etc.) are *not* in the catalogue: they're public interfaces with default members, and plugins can declare their own (`IDeployTerraform`) without registering anything. The catalogue is for things that need DI registration to take effect.

## Explicit non-starters (for v12)
- **`ITargetFactory`** — plugins replacing target discovery. Too much rope; defer to v13+.
- **`IBuildStatePersistence`** — plugins replacing the resume-file mechanism. Internal-only.
- **`IFileSystem` / `IProcessRunner` / `IConsoleHost`** — plugins can *consume* these but not contribute alternatives.
- **Source-generator plugins** — contributors can ship their own source generators alongside their package (.NET supports this directly); the SDK has no special API for them.

## Questions for discussion
1. Is `IOutputSink` the right shape, or should logging run through Serilog's existing sinks? Default: ship `IOutputSink` as a thin, easy-to-register wrapper, but also let plugins register Serilog sinks directly via `builder.Services`. Disagree?
2. A single `IPlugin`-level catch-all (like VS's `IVsPackage`) for things we forgot? Default: no — a back-door defeats a closed catalogue. Add a real extension point when the use case shows up.
3. Anything missing that a plausible v12 plugin would need? Comment with the use case.

## Out of scope (other RFCs)
- The plugin contract that registers these — RFC #97.
- Versioning when we *add* an extension point in a minor — RFC #99.
- Runtime discovery of registrations — RFC #100.
- Conflicting contributions — RFC #101.

## How to engage
Comment with use cases for missing extension points. "I want to ship a plugin that does X" is the most useful framing — if X needs an extension point we don't have, that's signal.

## Decision lands in
When this RFC locks (2026-08-31), the catalogue becomes the spec for the SDK-6 series:
- #151 — [SDK-6a] IBuildMiddleware
- #152 — [SDK-6b] IHost + IHostDetector
- #153 — [SDK-6c] IParameterSource
- #154 — [SDK-6d] IToolWrapperContribution
- #155 — [SDK-6e] ITargetLifecycleListener
- #156 — [SDK-6f] IOutputSink

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.