DevFW-CICD/website-and-documentation
23
0
Fork 1
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(governance): completely revised governance documentation based on confluence and old edp-doc content analysis
All checks were successful
ci / build (push) Successful in 54s
Details

Browse source
This commit is contained in:
Stephan Lo 2025-12-19 15:01:21 +01:00
parent 977e9d7e8a
commit a0fb081d80
1 changed files with 184 additions and 47 deletions
Download patch file Download diff file Expand all files Collapse all files

231
content/en/docs/governance/_index.md
View file

@ -3,47 +3,155 @@ title: "Governance"
linkTitle: "Governance" linkTitle: "Governance"
weight: 100 weight: 100
description: > 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 ## 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 ## 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 - A coherent developer experience spanning development, testing, validation, rollout, monitoring and (eventually) billing.
* Proof of Concept - Reuse through templates and "golden paths".
* Friendly User Phase - A portal-centric interaction model where developers consume platform capabilities via stable APIs and UI, not ad-hoc cluster access.
* Production Rollout
### 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 ## 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: 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. - **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. - **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. - **Open Source Strategy:** The platform aligns with the "Public Money, Public Code" philosophy, mandating that funded developments are returned to the community.
**Access Model:** **Access Model:**
The platform operates on a hybrid visibility 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. - **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)). - **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. - **User Base:** Primary users include the internal development team, with friendly user access granted to the IPCEI team and MMS BT.
### Security Controls ### 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. 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 ## Community & External Relations
### Open Source Contributions ### Open Source Contributions
@ -91,24 +205,47 @@ We actively contributed our extensions back to the upstream Forgejo project on *
**Key Pull Requests:** **Key Pull Requests:**
* **API Compatibility:** Added GitHub-compatible endpoints for runner registration. - **API Compatibility:** Added GitHub-compatible endpoints for runner registration.
* [PR #9409: Feat: Add endpoints for GARM](https://codeberg.org/forgejo/forgejo/pulls/9409) - [PR #9409: Feat: Add endpoints for GARM](https://codeberg.org/forgejo/forgejo/pulls/9409)
* **Webhook Support:** Implemented webhook triggers for workflow events. - **Webhook Support:** Implemented webhook triggers for workflow events.
* [PR #9803: Feat: Add webhook support for workflow events](https://codeberg.org/forgejo/forgejo/pulls/9803) - [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. - **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) - [PR #9962: Feat: Support for ephemeral runners](https://codeberg.org/forgejo/forgejo/pulls/9962)
### External Stakeholders ### External Stakeholders
User experience research and feedback integration. 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