From a0fb081d800fe327b23ee9555712b2380da44c66 Mon Sep 17 00:00:00 2001 From: Stephan Lo Date: Fri, 19 Dec 2025 15:01:21 +0100 Subject: [PATCH] docs(governance): completely revised governance documentation based on confluence and old edp-doc content analysis --- content/en/docs/governance/_index.md | 231 +++++++++++++++++++++------ 1 file changed, 184 insertions(+), 47 deletions(-) diff --git a/content/en/docs/governance/_index.md b/content/en/docs/governance/_index.md index 94a1333..7a3063f 100644 --- a/content/en/docs/governance/_index.md +++ b/content/en/docs/governance/_index.md @@ -3,47 +3,155 @@ title: "Governance" linkTitle: "Governance" weight: 100 description: > - Project history, architecture decisions, compliance, and audit information. + Project history, decision context, and audit-oriented traceability (primary sources and evidence). --- -{{% alert title="Draft" color="warning" %}} -**Editorial Status**: This page is currently being developed. - -* **Jira Ticket**: [TICKET-6737](https://jira.telekom-mms.com/browse/IPCEICIS-6737) -* **Assignee**: Sophie -* **Status**: Draft - Structure only -* **Last Updated**: 2025-11-16 -* **TODO**: - * [ ] Migrate relevant ADRs from docs-old - * [ ] Document project history and phases - * [ ] Add deliverables mapping - * [ ] Include compliance documentation -{{% /alert %}} - ## Governance Overview -This section provides information for auditors, governance teams, and stakeholders who need to understand the project's decision-making process, history, and compliance. +This chapter is publicly accessible, but it is written from within the IPCEI-CIS project context and therefore builds heavily on internal shared understanding. -## Architecture Decision Records (ADRs) +Most terminology, references, and primary sources in this chapter are internal (e.g., Confluence, Jira). Access and context are assumed. -Documentation of significant architectural decisions made during the project, including context, options considered, and rationale. +Primary intended audience: + +- IPCEI-CIS auditors +- IPCEI-CIS project management +- Project leads of other IPCEI-CIS sub-projects +- IPCEI-CIS central architecture ## Project History -### Development Process +### Mandate and product vision -The EDP was developed using collaborative approaches including mob programming and iterative development with regular user feedback. +Within the IPCEI-CIS work package for an Edge Developer Framework, the goal of the Developer Framework / EDP effort is to provide services that enable teams to develop, validate, roll out and operate applications efficiently across the edge cloud continuum. -### Project Phases +The initial product framing emphasized: -* Research & Design -* Proof of Concept -* Friendly User Phase -* Production Rollout +- A coherent developer experience spanning development, testing, validation, rollout, monitoring and (eventually) billing. +- Reuse through templates and "golden paths". +- A portal-centric interaction model where developers consume platform capabilities via stable APIs and UI, not ad-hoc cluster access. -### Deliverables Mapping +Primary source (internal only): [Confluence: Sub Project Developer Framework](https://confluence.telekom-mms.com/spaces/IPCEICIS/pages/856788263/Sub+Project+Developer+Framework) -Mapping to IPCEI-CIS deliverables and project milestones. +### Phases and milestones + +The following phase model is based on the project artifacts currently present in Confluence and this repository. It is intentionally phrased as “what changed and why”, rather than as a release plan. + +#### Phase 1 — Discovery & system design (2024) + +Focus: + +- Establish a reference architecture for an Internal Developer Platform (IDP) style solution. +- Evaluate IDP foundations (explicitly referencing CNOE as a favored baseline), using a “planes” model as conceptual structure. +- Early emphasis on becoming self-hosting quickly (“eat your own dogfood”) and validating end-to-end paths. + +Primary source (internal only): [Confluence: System Design](https://confluence.telekom-mms.com/spaces/IPCEICIS/pages/856788272/System+Design) + +#### Phase 2 — Proof of Concept (PoC) definition and scope (2024) + +Focus: + +- Align on a shared understanding of the product “Developer Platform” (technical and business framing) and what is feasible within 2024. +- Define PoC goals and acceptance criteria, including an end-to-end story centered on: + - an IDP builder/orchestrator running in the target environment (OSC), + - a developer portal (Backstage) for the user experience, + - a “golden path” flow from source → CI/CD → deployment. + +Primary sources: + +- Confluence (internal only): [Confluence: Proof of Concept 2024](https://confluence.telekom-mms.com/spaces/IPCEICIS/pages/902010138/Proof+of+Concept+2024) +- Repository: docs-old PoC structure summary: [PoC Structure](../../docs-old/v1/project/plan-in-2024/poc/) + +#### Phase 3 — PoC consolidation: deliverables, repository structure, traceability (late 2024) + +Focus: + +- Package outputs produced since mid-2024 into a demonstrable PoC product. +- Make “traces” explicit from backlog items to concrete outputs (repos, docs, capabilities), to support governance and auditability. +- Establish working agreements for branching, PR-based review, and Definition of Done. + +Primary source: repository document [Team and Work Structure](../../docs-old/v1/project/team-process/) (docs-old). + +#### Phase 4 — “Forgejo as a Service” and Foundry-based provisioning (2025) + +Focus: + +- Expand from “PoC capabilities” toward a service milestone around Forgejo, including supporting services (persistence, backups, caching, indexing, SSO, runners, observability). +- Provision Foundry/EDP resources via Infrastructure-as-Code, initially in OTC. +- Address reliability and migration risks while moving from earlier instances to production endpoints. + +Evidence: + +- Confluence (internal only): [Confluence: Forgejo as a service](https://confluence.telekom-mms.com/spaces/IPCEICIS/pages/999903971/Forgejo+as+a+service) (service decomposition and operational concerns) +- ADR: “Add Scaleway as Cloud resource Provider” explicitly places Foundry/EDP IaC provisioning in mid-April 2025 and captures platform issues and mitigation. +- Postmortem (2025-07-14) documents downtime rooted in an incomplete Foundry migration and the need for explicit migration plans. + +#### Phase 5 — EdgeConnect integration: deployment target + SDK/tooling (ongoing) + +Focus: + +- Treat EdgeConnect as a sovereign deployment target operated outside EDP, and provide consumable tooling to integrate it into delivery workflows. +- Provide reusable automation components (SDK, CLI client, Terraform provider, Forgejo Actions) so that EdgeConnect is used consistently through stable entry points. +- Use EdgeConnect for deploying project artifacts (including this documentation website) to edge cloudlets. + +Evidence: + +- Repository: EdgeConnect documentation under `/docs/edgeconnect/` (SDK/client/actions). +- Repository: docs-old “Publishing to Edge” describes the documentation deployment via `edgeconnectdeployment.yaml`. + +### Development and delivery process evolution + +Across the phases above, delivery methods and team process evolved in response to scaling and operational needs: + +- Scrum ceremonies and working agreements are documented in Confluence (internal only): [Confluence: How we SCRUM](https://confluence.telekom-mms.com/spaces/IPCEICIS/pages/977833214/How+we+SCRUM). +- Collaborative delivery techniques (mob / ensemble programming) appear as an explicit practice, including in incident documentation (“Team: Mob”) and internal guidance on sustainable mobbing models. + +### Deliverables mapping + +This section captures the traceability model and evidence-backed anchors that connect capabilities/phases to concrete outputs (repositories, documentation pages, deployed services). It does not yet claim a complete IPCEI deliverable-ID → epic → artifact mapping. + +#### Traceability model (used for audit) + +The working model (used throughout the PoC) is: + +- Deliverable / capability definition (often in Confluence) → +- Ticket(s) in Jira / Forgejo → +- Implementation via commits + pull requests → +- Concrete output (repo, docs page, automation component, deployed service) → +- Evidence (ADR / postmortem / runbook / deployment config) showing real operation. + +Primary sources for the traceability intent: + +- Repository: PoC design README lists Jira parts and calls for a mapping table from “parts” to upstream references. +- Repository: team-process documents emphasize “traces from tickets to outputs” and an outcome summary in the ticket as part of Definition of Done. + +#### Matrix (evidence-backed overview) + +This matrix is intended to be directly consumable: it summarizes what can already be evidenced from the current sources. It is an overview across phases/capabilities; it is not the full IPCEI deliverable-ID mapping. + +| Phase | What is delivered / proven | Concrete outputs (where) | Evidence / trace hooks | +| --- | --- | --- | --- | +| Phase 1 — Discovery & system design | Reference architecture framing and decision drivers | Confluence (internal only): [System Design](https://confluence.telekom-mms.com/spaces/IPCEICIS/pages/856788272/System+Design) (planes model, CNOE baseline preference, dogfooding) | Architecture notes are the earliest “why” evidence for later component choices | +| Phase 2 — PoC definition | PoC scope, acceptance criteria, end-to-end “golden path” story | Repository: PoC structure page (docs-old) and PoC design README | Jira parts exist for user docs + hands-on building blocks (see “Ticket anchors” below) | +| Phase 3 — PoC consolidation & traceability | A packaged PoC with explicit traceability from backlog to outputs | Repository: PoC team-process guidance (Definition of Done, PR review, “traces”) | “Outcome” is expected to be summarized in the ticket with links to PR/commit artifacts | +| Phase 4 — Forgejo-as-a-Service + Foundry provisioning | A service milestone with operational concerns (persistence, backups, SSO, runners) and IaC provisioning | ADR (Scaleway as additional install channel) + postmortem (Foundry migration downtime) | Concrete operational evidence that architecture and migration risks were handled as governance work | +| Phase 5 — EdgeConnect integration | EdgeConnect as delivery target and integration tooling | Repository: EdgeConnect docs section + docs-old “Publishing to Edge” (deployment yaml) | Deployment configuration and workflow description provide concrete “proof of use” | + +#### Ticket anchors (PoC) + +The PoC design README explicitly provides Jira anchors that can be used to build a full traceability matrix: + +- Part 1 (User documentation): [IPCEICIS-368](https://jira.telekom-mms.com/browse/IPCEICIS-368) +- Part 2.1 (Local IdP creation): [IPCEICIS-765](https://jira.telekom-mms.com/browse/IPCEICIS-765) +- Part 2.2 (OSC IdP creation): [IPCEICIS-766](https://jira.telekom-mms.com/browse/IPCEICIS-766) +- Part 2.x.1 (Golden Path template): [IPCEICIS-514](https://jira.telekom-mms.com/browse/IPCEICIS-514) +- Part 2.x.2 (Fibonacci example app): [IPCEICIS-759](https://jira.telekom-mms.com/browse/IPCEICIS-759) +- Part 2.x.3 (Forgejo Actions CI/CD): [IPCEICIS-760](https://jira.telekom-mms.com/browse/IPCEICIS-760) +- Part 2.x.4 (Telemetry): [IPCEICIS-761](https://jira.telekom-mms.com/browse/IPCEICIS-761) +- Part 2.x.5 (OSC infrastructure): [IPCEICIS-762](https://jira.telekom-mms.com/browse/IPCEICIS-762) +- Part 2.x.6 (Additional items): [IPCEICIS-763](https://jira.telekom-mms.com/browse/IPCEICIS-763) +- Part 2.3 (Extended local orchestration): [IPCEICIS-767](https://jira.telekom-mms.com/browse/IPCEICIS-767) +- Part 3 (User documentation): [IPCEICIS-768](https://jira.telekom-mms.com/browse/IPCEICIS-768) ## Compliance & Audit @@ -59,17 +167,17 @@ The internal service is officially designated as the [Edge Developer Platform (E The decision to utilize **[Forgejo](https://forgejo.org/)** as the core self-hosted Git service was driven by specific strategic requirements: -* **EU-Based Stewardship:** Forgejo is stewarded by **[Codeberg e.V.](https://docs.codeberg.org/getting-started/what-is-codeberg/)**, a non-profit organization based in Berlin, Germany. This alignment ensures compliance with GDPR and data sovereignty requirements, placing governance under EU jurisdiction rather than US tech entities. -* **License Protection (GPL v3+):** Unlike "Open Core" models, Forgejo uses a copyleft license. This legally protects our custom extensions (such as GARM support) from being appropriated into proprietary software, ensuring the ecosystem remains open. -* **Open Source Strategy:** The platform aligns with the "Public Money, Public Code" philosophy, mandating that funded developments are returned to the community. +- **EU-Based Stewardship:** Forgejo is stewarded by **[Codeberg e.V.](https://docs.codeberg.org/getting-started/what-is-codeberg/)**, a non-profit organization based in Berlin, Germany. This alignment ensures compliance with GDPR and data sovereignty requirements, placing governance under EU jurisdiction rather than US tech entities. +- **License Protection (GPL v3+):** Unlike "Open Core" models, Forgejo uses a copyleft license. This legally protects our custom extensions (such as GARM support) from being appropriated into proprietary software, ensuring the ecosystem remains open. +- **Open Source Strategy:** The platform aligns with the "Public Money, Public Code" philosophy, mandating that funded developments are returned to the community. **Access Model:** The platform operates on a hybrid visibility model: -* **Public Access:** The [`DEVFW-CICD`](https://edp.buildth.ing/DevFW-CICD) organization is publicly accessible, fostering transparency. -* **Private Access:** Sensitive development occurs in restricted organizations (e.g., [`DEVFW`](https://edp.buildth.ing/DevFW)). -* **User Base:** Primary users include the internal development team, with friendly user access granted to the IPCEI team and MMS BT. +- **Public Access:** The [`DEVFW-CICD`](https://edp.buildth.ing/DevFW-CICD) organization is publicly accessible, fostering transparency. +- **Private Access:** Sensitive development occurs in restricted organizations (e.g., [`DEVFW`](https://edp.buildth.ing/DevFW)). +- **User Base:** Primary users include the internal development team, with friendly user access granted to the IPCEI team and MMS BT. ### Security Controls @@ -79,6 +187,12 @@ Overview of implemented security controls and compliance measures. Cross-references to Jira tickets, epics, and project tracking for audit trails. +Current, evidence-backed anchors: + +- PoC “parts” and hands-on scope are anchored in Jira and listed explicitly in the PoC design README (see Ticket anchors above). +- PoC consolidation and governance intent (“traces from tickets to outputs”) is described in the team-process documentation. +- The Forgejo ProjectMgmt prototype documents how tickets, milestones, and boards were structured in Forgejo to run demo slices and work packages. + ## Community & External Relations ### Open Source Contributions @@ -91,24 +205,47 @@ We actively contributed our extensions back to the upstream Forgejo project on * **Key Pull Requests:** -* **API Compatibility:** Added GitHub-compatible endpoints for runner registration. - * [PR #9409: Feat: Add endpoints for GARM](https://codeberg.org/forgejo/forgejo/pulls/9409) -* **Webhook Support:** Implemented webhook triggers for workflow events. - * [PR #9803: Feat: Add webhook support for workflow events](https://codeberg.org/forgejo/forgejo/pulls/9803) -* **Ephemeral Runners:** Added support for runners that terminate after a single job. - * [PR #9962: Feat: Support for ephemeral runners](https://codeberg.org/forgejo/forgejo/pulls/9962) +- **API Compatibility:** Added GitHub-compatible endpoints for runner registration. + - [PR #9409: Feat: Add endpoints for GARM](https://codeberg.org/forgejo/forgejo/pulls/9409) +- **Webhook Support:** Implemented webhook triggers for workflow events. + - [PR #9803: Feat: Add webhook support for workflow events](https://codeberg.org/forgejo/forgejo/pulls/9803) +- **Ephemeral Runners:** Added support for runners that terminate after a single job. + - [PR #9962: Feat: Support for ephemeral runners](https://codeberg.org/forgejo/forgejo/pulls/9962) ### External Stakeholders User experience research and feedback integration. -## Documentation Template +## References -When creating governance documentation: +This list is an index of all links referenced on this page, plus the intended meaning (“semantics”) of each link. + +- (internal only) Confluence: [Sub Project Developer Framework](https://confluence.telekom-mms.com/spaces/IPCEICIS/pages/856788263/Sub+Project+Developer+Framework) — mandate, quick links, and high-level framing. +- (internal only) Confluence: [System Design](https://confluence.telekom-mms.com/spaces/IPCEICIS/pages/856788272/System+Design) — architecture framing (planes model, baseline preferences, early decision drivers). +- (internal only) Confluence: [Proof of Concept 2024](https://confluence.telekom-mms.com/spaces/IPCEICIS/pages/902010138/Proof+of+Concept+2024) — PoC scope, goals, and evaluation/acceptance framing. +- (internal only) Confluence: [Forgejo as a service](https://confluence.telekom-mms.com/spaces/IPCEICIS/pages/999903971/Forgejo+as+a+service) — service decomposition and operational concerns used as evidence for Phase 4. +- (internal only) Confluence: [How we SCRUM](https://confluence.telekom-mms.com/spaces/IPCEICIS/pages/977833214/How+we+SCRUM) — delivery process reference. +- (internal only) Jira: [IPCEICIS-368](https://jira.telekom-mms.com/browse/IPCEICIS-368) — PoC part 1 traceability anchor. +- (internal only) Jira: [IPCEICIS-765](https://jira.telekom-mms.com/browse/IPCEICIS-765) — PoC part 2.1 traceability anchor. +- (internal only) Jira: [IPCEICIS-766](https://jira.telekom-mms.com/browse/IPCEICIS-766) — PoC part 2.2 traceability anchor. +- (internal only) Jira: [IPCEICIS-514](https://jira.telekom-mms.com/browse/IPCEICIS-514) — PoC golden path template traceability anchor. +- (internal only) Jira: [IPCEICIS-759](https://jira.telekom-mms.com/browse/IPCEICIS-759) — PoC example app traceability anchor. +- (internal only) Jira: [IPCEICIS-760](https://jira.telekom-mms.com/browse/IPCEICIS-760) — PoC CI/CD traceability anchor. +- (internal only) Jira: [IPCEICIS-761](https://jira.telekom-mms.com/browse/IPCEICIS-761) — PoC telemetry traceability anchor. +- (internal only) Jira: [IPCEICIS-762](https://jira.telekom-mms.com/browse/IPCEICIS-762) — PoC infrastructure traceability anchor. +- (internal only) Jira: [IPCEICIS-763](https://jira.telekom-mms.com/browse/IPCEICIS-763) — PoC additional items traceability anchor. +- (internal only) Jira: [IPCEICIS-767](https://jira.telekom-mms.com/browse/IPCEICIS-767) — PoC orchestration extension traceability anchor. +- (internal only) Jira: [IPCEICIS-768](https://jira.telekom-mms.com/browse/IPCEICIS-768) — PoC part 3 (user documentation) traceability anchor. +- Documentation site: [PoC Structure](../../docs-old/v1/project/plan-in-2024/poc/) — published docs-old summary of the PoC structure. +- Documentation site: [Team and Work Structure](../../docs-old/v1/project/team-process/) — published docs-old description of process and traceability intent. +- Documentation site: [Forgejo component page](../components/forgejo/_index.md) — internal documentation entry point for the Forgejo/EDP component. +- Service entry point: [edp.buildth.ing](https://edp.buildth.ing) — EDP Forgejo instance. +- Service org: [edp.buildth.ing/DevFW-CICD](https://edp.buildth.ing/DevFW-CICD) — public organization referenced for transparency. +- Service org: [edp.buildth.ing/DevFW](https://edp.buildth.ing/DevFW) — private organization reference. +- Upstream project: [forgejo.org](https://forgejo.org/) — Forgejo project homepage. +- Upstream governance: [Codeberg e.V.](https://docs.codeberg.org/getting-started/what-is-codeberg/) — referenced as steward/governance body. +- Upstream contribution: [PR #9409](https://codeberg.org/forgejo/forgejo/pulls/9409) — GARM endpoints contribution. +- Upstream contribution: [PR #9803](https://codeberg.org/forgejo/forgejo/pulls/9803) — webhook workflow events contribution. +- Upstream contribution: [PR #9962](https://codeberg.org/forgejo/forgejo/pulls/9962) — ephemeral runners contribution. +- Upstream hosting: [Codeberg.org](https://codeberg.org/) — hosting platform used for upstream Forgejo contributions. -1. **Context**: Background and situation -2. **Decision/Event**: What was decided or what happened -3. **Rationale**: Why this decision was made -4. **Alternatives**: Other options considered -5. **Consequences**: Impact and outcomes -6. **References**: Links to tickets, discussions, external resources