⚡ 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. As of the namespace migration (#399), the C# namespace for each package matches its NuGet PackageId (e.g. using AutomationSandbox.UiModel;) — earlier previews used the unprefixed short name (using UiModel;); that was a collision-prone surface for a mature SDK and is now a breaking change, called out in the release notes for the version that ships it:

Tier 2: Extensibility Points

Interfaces intended for consumer extension (ILlmHealingProvider, IHealingReportSink, IIntentPlanner, IContentAnalysisProvider) 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. This list is the live burn-down — the box is checked when the maintainer confirms the criterion at release-decision time; the Status line records where it stands now.

Release trigger. The prerelease → 1.0.0 transition is condition-based, not date-based: 1.0.0 is cut once every box above is checked, no open issue is labeled release-blocker, and the current release notes carry no Known Limitation that blocks a use case the README claims support for. Until then, minor bumps (0.2 → 0.3) continue under the pre-1.0 policy in §2. Every criterion’s Status line above is the live tracker; the mechanical next step is the next preview release, which proves the publish flow end to end.

🇹🇷 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. Ad alanı geçişinden (#399) itibaren her paketin C# ad alanı, NuGet PackageId‘siyle eşleşir (örn. using AutomationSandbox.UiModel;) — önceki önizlemeler önek almamış kısa adı kullanıyordu (using UiModel;); bu, olgun bir SDK için çakışmaya açık bir yüzeydi ve artık bunu taşıyan sürümün release notlarında belirtilen kırıcı bir değişikliktir:

2. Kademe: Genişletilebilirlik Noktaları

Tüketici eklentileri için tasarlanan arayüzler (ILlmHealingProvider, IHealingReportSink, IIntentPlanner, IContentAnalysisProvider), 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. Bu liste canlı burn-down’dur — kutu, bakımcı sürüm-kararı anında kriteri doğruladığında işaretlenir; Durum satırı şu anki halini kaydeder.

Sürüm tetikleyicisi. Ön sürümden 1.0.0‘a geçiş tarihe değil koşula bağlıdır: yukarıdaki her kutu işaretlendiğinde, release-blocker etiketli açık bir sorun kalmadığında ve mevcut sürüm notları README’nin desteklediğini iddia ettiği bir kullanım senaryosunu engelleyen bir Known Limitation taşımadığında 1.0.0 kesilir. O zamana kadar minör sürüm artışları (0.2 → 0.3) §2’deki 1.0 öncesi politika altında devam eder. Yukarıdaki her kriterin Durum satırı canlı takipçidir; mekanik sonraki adım, yayın akışını uçtan uca kanıtlayan bir sonraki ön sürümdür.