diff --git a/.github/workflows/community-health.yml b/.github/workflows/community-health.yml index 6d07aa7..3019642 100644 --- a/.github/workflows/community-health.yml +++ b/.github/workflows/community-health.yml @@ -29,3 +29,22 @@ jobs: abort "#{path}: body must be an array" unless doc["body"].is_a?(Array) end puts "validated #{paths.length} issue-form files" + + profile-maturity: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Validate organization profile maturity claims + shell: bash + run: | + set -euo pipefail + test -s profile/README.md + test -s REPOSITORY_MATURITY.md + grep -Fq '1.0.0-draft' profile/README.md + grep -Fq 'Prerelease Alpha' profile/README.md + grep -Fq 'Scaffold · Planned' profile/README.md + grep -Fq 'CoreLinkPlatform/platform' REPOSITORY_MATURITY.md + if grep -Fq 'CoreLinkPlatform/examples' profile/README.md; then + echo "organization profile references the unavailable examples repository" >&2 + exit 1 + fi diff --git a/README.md b/README.md index 6b5837b..7aed507 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,7 @@ repositories. - `ISSUE_TEMPLATE/`: organization-wide bug, feature, implementation, Product Epic and documentation forms. - `PULL_REQUEST_TEMPLATE.md`: pull-request checklist. - `profile/README.md`: organization profile shown on GitHub. +- `REPOSITORY_MATURITY.md`: reconciled repository roles and maturity claims. ## Usage diff --git a/REPOSITORY_MATURITY.md b/REPOSITORY_MATURITY.md new file mode 100644 index 0000000..7468c28 --- /dev/null +++ b/REPOSITORY_MATURITY.md @@ -0,0 +1,67 @@ +# CoreLink repository maturity inventory + +**Last reconciled: 2026-08-06** + +CoreLink is one product delivered through multiple repositories. This inventory +records repository role and maturity; it is not a second product roadmap. +Product goals, milestones and cross-repository Epics remain authoritative in +[`product-planning`](https://github.com/CoreLinkPlatform/product-planning). + +Maturity words follow the shared CoreLink vocabulary: **Scaffold**, +**Experimental**, **Alpha**, **Beta**, **Stable**, **Deprecated**, and +**Planned**. Repository visibility or the presence of source code does not make +a capability Stable or commercially supported. + +## Current inventory + +| Repository | Product role | Current maturity | What that means now | +| --- | --- | --- | --- | +| [`platform`](https://github.com/CoreLinkPlatform/platform) | Core runtime | Implemented foundation / pre-release | Substantial tenancy, identity, device, command and event foundations exist; product acceptance gates are still open. | +| [`api-contracts`](https://github.com/CoreLinkPlatform/api-contracts) | Public/admin/internal API and event contracts | Alpha · `1.0.0-draft` public boundary | Device + Command public slice and canonical event envelope are reviewable; draft is not a Stable v1 release. | +| [`developer-docs`](https://github.com/CoreLinkPlatform/developer-docs) | Versioned developer documentation | Alpha | v1 information architecture and contract-backed quickstart target the draft public boundary. | +| [`sdk-typescript`](https://github.com/CoreLinkPlatform/sdk-typescript) | TypeScript client | Prerelease Alpha | Generated client exists; no production-supported package release is claimed. | +| [`sdk-python`](https://github.com/CoreLinkPlatform/sdk-python) | Python client | Prerelease Alpha | Generated client exists; no production-supported package release is claimed. | +| [`sdk-java`](https://github.com/CoreLinkPlatform/sdk-java) | Java client | Scaffold · Planned | No supported Java package exists yet. | +| [`cli`](https://github.com/CoreLinkPlatform/cli) | Developer/operator CLI | Scaffold · Planned | No installable supported CLI exists yet. | +| [`mock-server`](https://github.com/CoreLinkPlatform/mock-server) | Local/CI API simulation | Scaffold · Planned | No supported mock-server package/runtime exists yet. | +| [`mcp-server`](https://github.com/CoreLinkPlatform/mcp-server) | Agent/MCP integration | Scaffold · Planned | No supported MCP server/tool surface exists yet. | +| [`website`](https://github.com/CoreLinkPlatform/website) | Public product website | Active public surface / pre-release claims | Claims must mirror this inventory and retained repository/release evidence. | +| [`product-planning`](https://github.com/CoreLinkPlatform/product-planning) | Product governance | Source of truth | Owns product hierarchy, milestones, decisions and cross-repository acceptance. | +| [`.github`](https://github.com/CoreLinkPlatform/.github) | Organization governance/community health | Source of truth | Owns organization defaults, profile, contribution/security policy and shared Issue forms. | + +The former `examples` link is intentionally absent: no accessible +`CoreLinkPlatform/examples` repository was found during this reconciliation. +Examples must not be advertised as a runnable product resource until a real, +versioned repository and acceptance evidence exist. + +## Capability boundary represented publicly + +Today the public developer boundary is intentionally narrower than the internal +runtime foundation: + +- public API contract: Device + Command on `1.0.0-draft`; +- public event contract: canonical event envelope; +- TypeScript/Python clients: prerelease Alpha; +- Java/CLI/mock/MCP: Scaffold/Planned; +- telemetry, digital twin, media, white-label and broader integration claims + require their own contract/runtime/release evidence before being presented as + Stable supported public capability. + +## Ownership and review + +- Product Council/product planning owns milestone and product-maturity decisions. +- Each repository owns implementation evidence and its repository README. +- The website and organization profile may summarize maturity but must link back + to the owning repository/contract instead of becoming independent roadmaps. +- A repository owner changing a public maturity claim must update affected docs, + website/profile copy and retained release evidence in the same product change + or link follow-up work explicitly. +- Exceptions are recorded as product decisions in `product-planning`; they are + not hidden in marketing copy or repository-local status text. + +## Reconciliation cadence + +Review this inventory at every product milestone gate and whenever a repository +enters or leaves Scaffold/Experimental/Alpha/Beta/Stable/Deprecated status. +A release tag alone is insufficient: contract compatibility, runtime evidence, +documentation and the owning repository's acceptance gate must agree. diff --git a/profile/README.md b/profile/README.md index 205f69f..ccf0ea9 100644 --- a/profile/README.md +++ b/profile/README.md @@ -2,80 +2,96 @@ # CoreLink Platform -### Connected product infrastructure for devices, applications, and digital services +### زیرساخت اتصال و یکپارچه‌سازی محصولات هوشمند -Build, integrate, and operate connected products through consistent APIs, SDKs, event contracts, and developer tools. +CoreLink یک محصول واحد با چند مرز پیاده‌سازی است: قراردادهای عمومی، runtime، +SDKها، مستندات و ابزارها با یک مدل maturity مشترک تکامل پیدا می‌کنند. -[Developer Documentation](https://developers.corelinkplatform.ir) +[Developer Documentation](https://github.com/CoreLinkPlatform/developer-docs) · [API Contracts](https://github.com/CoreLinkPlatform/api-contracts) · -[Examples](https://github.com/CoreLinkPlatform/examples) +[Product Website](https://corelinkplatform.ir) · -[Report an Issue](https://github.com/CoreLinkPlatform/developer-docs/issues) +[Repository Maturity](../REPOSITORY_MATURITY.md) --- -## What is CoreLink? +## وضعیت فعلی محصول -CoreLink is a developer platform for integrating connected devices, applications, and business systems. +CoreLink هنوز یک انتشار Stable v1 نیست. مرز عمومی فعلی به‌صورت شفاف محدود است: -It provides a consistent abstraction over device communication, provisioning, telemetry, commands, digital twins, events, and external integrations. +- **API Contracts:** Alpha، با baseline فعلی `1.0.0-draft` برای Device و + Command و canonical event envelope. +- **TypeScript SDK:** Prerelease Alpha. +- **Python SDK:** Prerelease Alpha. +- **Java SDK / CLI / Mock Server / MCP Server:** Scaffold · Planned. +- **Core runtime:** foundation پیاده‌سازی‌شده دارد، اما تکمیل engineering + foundation به‌تنهایی معادل پذیرش محصول یا انتشار Stable نیست. -CoreLink is designed for: +[موجودی کامل maturity ریپوها](../REPOSITORY_MATURITY.md) مرجع این خلاصه است. -- connected-product manufacturers; -- IoT solution providers; -- fleet and mobility platforms; -- white-label applications; -- enterprise integration teams; -- backend, web, mobile, and automation developers. +## CoreLink چه مسئله‌ای را حل می‌کند؟ -## Platform capabilities +CoreLink برای ساخت محصولات متصل طراحی شده است: دستگاه و integration در مرز +زیرساخت جذب می‌شوند و applicationها با شناسه‌ها، قراردادها و رفتارهای +CoreLink-owned کار می‌کنند. -CoreLink provides common interfaces for: +جهت محصول شامل device lifecycle، commands، telemetry/state، events، +integrations و تجربه‌های white-label است؛ اما هر مورد فقط وقتی «قابلیت پشتیبانی +شده» محسوب می‌شود که contract، runtime، مستندات و release evidence همان maturity +را تأیید کنند. -- device registration and identity; -- device provisioning and lifecycle management; -- telemetry and state synchronization; -- remote command execution; -- location and mobility services; -- media and streaming workflows; -- event-driven integrations; -- webhooks and external system connectivity; -- multi-tenant and white-label applications; -- developer and AI-assisted integrations. +## از کجا شروع کنیم؟ -The public APIs describe platform capabilities rather than specific internal implementations. This allows the underlying infrastructure to evolve without forcing unnecessary changes on applications and integrations. +| منبع | وضعیت | کاربرد فعلی | +| --- | --- | --- | +| [Developer docs](https://github.com/CoreLinkPlatform/developer-docs) | Alpha | مستندات نسخه‌دار و quickstart مبتنی بر contract | +| [API contracts](https://github.com/CoreLinkPlatform/api-contracts) | Alpha · `1.0.0-draft` | مرز عمومی Device + Command و event envelope | +| [TypeScript SDK](https://github.com/CoreLinkPlatform/sdk-typescript) | Prerelease Alpha | کلاینت generated؛ هنوز release پایدار نیست | +| [Python SDK](https://github.com/CoreLinkPlatform/sdk-python) | Prerelease Alpha | کلاینت generated؛ هنوز release پایدار نیست | +| [Java SDK](https://github.com/CoreLinkPlatform/sdk-java) | Scaffold · Planned | مسیر توسعه آینده؛ package پشتیبانی‌شده ندارد | +| [CLI](https://github.com/CoreLinkPlatform/cli) | Scaffold · Planned | ابزار برنامه‌ریزی‌شده؛ installable release ندارد | +| [Mock Server](https://github.com/CoreLinkPlatform/mock-server) | Scaffold · Planned | شبیه‌ساز برنامه‌ریزی‌شده | +| [MCP Server](https://github.com/CoreLinkPlatform/mcp-server) | Scaffold · Planned | سطح agent/MCP برنامه‌ریزی‌شده | -## Start here +## قرارداد عمومی امروز -| Resource | Description | -|---|---| -| [Developer documentation](https://github.com/CoreLinkPlatform/developer-docs) | Guides, concepts, tutorials, and API usage | -| [API contracts](https://github.com/CoreLinkPlatform/api-contracts) | OpenAPI, AsyncAPI, schemas, and Postman collections | -| [TypeScript SDK](https://github.com/CoreLinkPlatform/sdk-typescript) | SDK for Node.js, browsers, React, and Next.js | -| [Python SDK](https://github.com/CoreLinkPlatform/sdk-python) | SDK for Python applications and automation | -| [Java SDK](https://github.com/CoreLinkPlatform/sdk-java) | SDK for Java and Spring-based applications | -| [Examples](https://github.com/CoreLinkPlatform/examples) | Runnable integration examples | -| [CLI](https://github.com/CoreLinkPlatform/cli) | Command-line tools for developers and operators | -| [MCP Server](https://github.com/CoreLinkPlatform/mcp-server) | AI and agent integrations using Model Context Protocol | -| [Mock Server](https://github.com/CoreLinkPlatform/mock-server) | Local and CI-compatible API simulation | +برای integration جدید، قرارداد عمومی منبع حقیقت است؛ نه ساختار provider یا +جزئیات داخلی runtime. -## Quick example +- شناسه عمومی دستگاه: `corelink_device_id`; +- tenant scope در مسیرهای عمومی صریح است; +- authentication فعلی قرارداد عمومی: Bearer JWT; +- Command create نیازمند `Idempotency-Key` است; +- provider/connector identifiers جزئیات پیاده‌سازی‌اند. -```ts -import { CoreLink } from "@corelink/sdk"; +Quickstart و referenceهای نسخه‌دار در +[`developer-docs`](https://github.com/CoreLinkPlatform/developer-docs) قرار +دارند. -const corelink = new CoreLink({ - baseUrl: process.env.CORELINK_API_URL!, - accessToken: async () => process.env.CORELINK_ACCESS_TOKEN!, -}); +## یک محصول، چند repository -const devices = await corelink.devices.list({ - tenantId: "tenant_id", -}); +Product hierarchy، milestone gates و تصمیم‌های cross-repository در +[`product-planning`](https://github.com/CoreLinkPlatform/product-planning) +مدیریت می‌شوند. هر repository فقط implementation/evidence مرز خودش را نگه +می‌دارد. -console.log(devices.items); +وضعیت یک repository را از public بودن، تعداد فایل‌ها یا وجود یک scaffold نتیجه +نمی‌گیریم. واژگان مشترک maturity عبارت‌اند از **Scaffold, Experimental, Alpha, +Beta, Stable, Deprecated, Planned**. + +## اعتماد، امنیت و مشارکت + +- آسیب‌پذیری امنیتی را طبق [Security Policy](../SECURITY.md) گزارش کنید. +- تغییرات کد و مستندات باید [Contribution Guide](../CONTRIBUTING.md) را رعایت کنند. +- Issueهای اجرایی از [organization Issue forms](../ISSUE_TEMPLATE/) استفاده + می‌کنند و به Product Epic مربوط لینک می‌شوند. +- وضعیت محصول یا package را قبل از استفاده production از repository مالک و + [maturity inventory](../REPOSITORY_MATURITY.md) بررسی کنید. + +--- + +CoreLink Platform · one product, explicit maturity, evidence before claims.