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
All checks were successful
ci / build (push) Successful in 54s
This commit is contained in:
parent
977e9d7e8a
commit
a0fb081d80
1 changed files with 184 additions and 47 deletions
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue