⚡ Automation Sandbox Latest Release

🛡️ API Stability, Versioning & Beta-Exit Criteria / API Kararlılığı, Sürüm Politikası ve Beta Çıkış Kriterleri

This document formally defines the public API stability guarantees, the semantic versioning policy across pre-1.0 and post-1.0 lifecycles, and the concrete, checkable exit criteria required for graduating Automation Sandbox from beta to 1.0.0 GA (General Availability).

💡 Select Language / Dil Seçin:

🇬🇧 English Guide

1. Public API Surface & Stability Tiers

Automation Sandbox distinguishes between stable public contracts, extensible provider surfaces, and experimental/internal subsystems.

flowchart TD
    subgraph StablePublic ["Tier 1: Stable Public API (Guaranteed Backward Compatibility)"]
        UiModel["UiModel: UiElementInfo, BoundingRectangle, CandidateScore, LocatorRepository"]
        SelfHealing["SelfHealing: SelfHealingEngine, SimilarityWeights, ThresholdProfile, HealingMode, HealResult"]
        LlmHealing["LlmHealing: ILlmHealingProvider, HttpLlmHealingProvider, Built-in Providers"]
        WebDiscovery["WebDiscovery: WebElementInfo, WebElementMapper, PlaywrightLocatorEmitter"]
        Discovery["Discovery: UiTreeWalker, ApplicationConnector, DiscoveryOptions"]
        Intent["IntentAutomation: IIntentPlanner, IntentActionType, Playwright/FlaUi Generators, IntentAutomationPipeline"]
    end

    subgraph Extensibility ["Tier 2: Extensibility Points (SemVer Gated)"]
        CustomProviders["Custom ILlmHealingProvider / HttpLlmHealingProvider Implementations"]
        CustomSinks["IHealingReportSink / Custom Telemetry Sinks"]
        CustomPlanners["IIntentPlanner Implementations"]
    end

    subgraph Experimental ["Tier 3: Experimental & Internal Tooling (Subject to Iteration)"]
        Evaluators["JointLocatorAssignmentEvaluator (Offline Reconciliation Research)"]
        SyntheticHarness["LocatorAblationHarness & Benchmark Datasets"]
        InternalTests["ScenarioRunner Internals"]
    end

    StablePublic --> Extensibility
    Extensibility --> Experimental

Tier 1: Stable Public API

The following NuGet packages and their core types represent the committed public contract. The C# namespace for each package is its unprefixed short name (e.g. using UiModel;, not using AutomationSandbox.UiModel;):

Tier 2: Extensibility Points

Interfaces intended for consumer extension (ILlmHealingProvider, IHealingReportSink, IIntentPlanner) are protected against breaking changes post-1.0. Any additive default methods will provide default implementations or non-breaking base templates.

Tier 3: Internal & Experimental

Types in ScenarioRunner (such as JointLocatorAssignmentEvaluator and LocatorAblationHarness) are research or benchmark tools and do not constitute a public NuGet API contract.

2. Semantic Versioning & Breaking Change Policy

Automation Sandbox adheres to Semantic Versioning 2.0.0:

Pre-1.0 Lifecycle (0.x.y)

Post-1.0 Lifecycle (1.0.0+)

3. Concrete Beta-Exit Criteria (1.0 GA Checklist)

To exit beta and release 1.0.0, all of the following conditions must be satisfied:

🇹🇷 Türkçe Kılavuz

1. Genel API Yüzeyi ve Kararlılık Kademeleri

Automation Sandbox, kararlı genel sözleşmeler, genişletilebilir sağlayıcı yüzeyleri ve deneysel/dahili alt sistemler arasında ayrım yapar.

flowchart TD
    subgraph StablePublic ["1. Kademe: Kararlı Genel API (Geriye Dönük Uyumluluk Garantili)"]
        UiModel["UiModel: UiElementInfo, BoundingRectangle, CandidateScore, LocatorRepository"]
        SelfHealing["SelfHealing: SelfHealingEngine, SimilarityWeights, ThresholdProfile, HealingMode, HealResult"]
        LlmHealing["LlmHealing: ILlmHealingProvider, HttpLlmHealingProvider, Hazır Sağlayıcılar"]
        WebDiscovery["WebDiscovery: WebElementInfo, WebElementMapper, PlaywrightLocatorEmitter"]
        Discovery["Discovery: UiTreeWalker, ApplicationConnector, DiscoveryOptions"]
        Intent["IntentAutomation: IIntentPlanner, IntentActionType, Playwright/FlaUi Üreticileri, IntentAutomationPipeline"]
    end

    subgraph Extensibility ["2. Kademe: Genişletilebilirlik Noktaları (SemVer ile Korunur)"]
        CustomProviders["Özel ILlmHealingProvider / HttpLlmHealingProvider Implementasyonları"]
        CustomSinks["IHealingReportSink / Özel Telemetri Sink'leri"]
        CustomPlanners["IIntentPlanner Implementasyonları"]
    end

    subgraph Experimental ["3. Kademe: Dahili ve Deneysel Araçlar (Değişime Açık)"]
        Evaluators["JointLocatorAssignmentEvaluator (Çevrimdışı Uzlaşma Araştırması)"]
        SyntheticHarness["LocatorAblationHarness ve Benchmark Veri Setleri"]
        InternalTests["ScenarioRunner İç Bileşenleri"]
    end

    StablePublic --> Extensibility
    Extensibility --> Experimental

1. Kademe: Kararlı Genel API

Aşağıdaki NuGet paketleri ve temel türleri taahhüt edilen genel sözleşmeyi temsil eder. Her paketin C# ad alanı, önek almamış kısa adıdır (örn. using AutomationSandbox.UiModel; değil, using UiModel;):

2. Kademe: Genişletilebilirlik Noktaları

Tüketici eklentileri için tasarlanan arayüzler (ILlmHealingProvider, IHealingReportSink, IIntentPlanner), 1.0 sonrasında kırıcı değişikliklere karşı korunur.

3. Kademe: Dahili ve Deneysel Araçlar

ScenarioRunner içindeki araştırma amaçlı sınıflar (JointLocatorAssignmentEvaluator, LocatorAblationHarness vb.) genel NuGet API sözleşmesine dahil değildir.

2. Semantik Sürümleme ve Değişiklik Politikası

Automation Sandbox Semantic Versioning 2.0.0 standardını uygular:

1.0 Öncesi Yaşam Döngüsü (0.x.y)

1.0 Sonrası Yaşam Döngüsü (1.0.0+)

3. Somut Beta Çıkış Kriterleri (1.0 GA Kontrol Listesi)

Beta sürecini tamamlayıp 1.0.0 genel sürümüne geçmek için aşağıdaki tüm koşulların sağlanması gerekir: