From c1a281bb8ad873e98af06569b4a6d95543e2979d Mon Sep 17 00:00:00 2001 From: Andreas Zwinkau Date: Tue, 18 Nov 2025 10:42:53 +0100 Subject: [PATCH 1/6] First draft of DR-005-Infra --- docs/design_decisions/DR-005-infra.rst | 74 ++++++++++++++++++++++++++ 1 file changed, 74 insertions(+) create mode 100644 docs/design_decisions/DR-005-infra.rst diff --git a/docs/design_decisions/DR-005-infra.rst b/docs/design_decisions/DR-005-infra.rst new file mode 100644 index 00000000000..9257840ff56 --- /dev/null +++ b/docs/design_decisions/DR-005-infra.rst @@ -0,0 +1,74 @@ +.. + Copyright (c) 2025 Contributors to the Eclipse Foundation + + See the NOTICE file(s) distributed with this work for additional + information regarding copyright ownership. + + This program and the accompanying materials are made available under the + terms of the Apache License Version 2.0 which is available at + https://www.apache.org/licenses/LICENSE-2.0 + + SPDX-License-Identifier: Apache-2.0 + +DR-005-Infra: Hosting Strategy for Module Documentation +======================================================= + +.. dec_rec:: Hosting strategy for module webspaces + :id: dec_rec__infra__webspace + :status: proposed + :context: Infrastructure + :decision: tbd + +Context / Problem +----------------- + +We host site content for modules using GitHub Pages (per-repo webspaces). +While this works so far, the storage and site limits are becoming noticeable. +More diagrams, pull-requests, and versions will exacerbate the problem. + +Goals and Requirements +^^^^^^^^^^^^^^^^^^^^^^ + +1. Provide sufficient storage and bandwidth for released documentation and static assets. +2. Keep a consistent site/URL structure and navigation across modules. +3. Keep hosting and maintenance costs predictable and low. +4. Dedicated space for releases? + +Options Considered +------------------ + +Option G: Continue with per-repo GitHub Pages (status quo) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Keep publishing module webspaces to GitHub Pages. +Invest efforts to keep space needs low as we only have 1GiB per repository. + +😡 Effort: Increasing. + + +Option C: Centralized hosting under the Eclipse webspace +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Host module webspaces in sub-folders of https://eclipse.dev/score/ +The site would be the canonical public landing page, +while modules may still publish artifact outputs to GitHub or to an internal storage bucket. + +😡 Effort: Infrastructure and migration needed. + +Option X: ... +^^^^^^^^^^^^^ + +Use an external hosting provider? +Pay GitHub for more space? + + +Evaluation +---------- + +.. csv-table:: + :header: Criteria, Option G, Option C, Option X + :widths: 20, 10, 10, 10 + + Effort, 💚, 😡, ? + +decision tbd From 3197fbbeb1be6e8c0f523f9ba10772568c548b7a Mon Sep 17 00:00:00 2001 From: Andreas Zwinkau Date: Tue, 18 Nov 2025 17:25:43 +0100 Subject: [PATCH 2/6] Revised after chat with Christian and Alex --- docs/design_decisions/DR-005-infra.rst | 115 +++++++++++++++++++++---- 1 file changed, 98 insertions(+), 17 deletions(-) diff --git a/docs/design_decisions/DR-005-infra.rst b/docs/design_decisions/DR-005-infra.rst index 9257840ff56..c6024c7f1dc 100644 --- a/docs/design_decisions/DR-005-infra.rst +++ b/docs/design_decisions/DR-005-infra.rst @@ -15,21 +15,54 @@ DR-005-Infra: Hosting Strategy for Module Documentation .. dec_rec:: Hosting strategy for module webspaces :id: dec_rec__infra__webspace - :status: proposed + :status: accepted :context: Infrastructure - :decision: tbd + :decision: Combine Website from multiple Repos Context / Problem ----------------- We host site content for modules using GitHub Pages (per-repo webspaces). +While GitHub *repos* can store up to 10GiB (size of ``.git`` folder), +GitHub *Pages* only allows 1GiB of storage. While this works so far, the storage and site limits are becoming noticeable. More diagrams, pull-requests, and versions will exacerbate the problem. +.. plantuml:: + + node "Module Repo" as ModuleRepo + node ".gh_pages branch" as gh_pages + cloud "GitHub Pages" as GitHubPages + + ModuleRepo -> gh_pages : "build" + gh_pages -> GitHubPages : "publish" + +In addition to GitHub Pages, the project also has the website +https://eclipse.dev/score/ hosted via the Eclipse Foundation. +The website is relatively small and there are plans to move most content elsewhere +(where it can be managed via Wordpress). + +The foundation updates the content every 5 minutes from +the `eclipse-score-website-published `_ repo. +The sources are in the `eclipse-score-website `_ repo +and get deployed automatically using the GitHub Action +`Build and Archive `_. + +.. plantuml:: + + node "eclipse-score-website-published" as PublishedRepo + node "eclipse-score-website" as WebsiteSrc + cloud "eclipse.dev/score" as EclipseSite + + WebsiteSrc -> PublishedRepo : "Build & Archive" + PublishedRepo <. EclipseSite : "pull every 5min" + +No limits for this hosting are known. + Goals and Requirements ^^^^^^^^^^^^^^^^^^^^^^ -1. Provide sufficient storage and bandwidth for released documentation and static assets. +1. Provide sufficient storage and bandwidth for released documentation. 2. Keep a consistent site/URL structure and navigation across modules. 3. Keep hosting and maintenance costs predictable and low. 4. Dedicated space for releases? @@ -43,32 +76,80 @@ Option G: Continue with per-repo GitHub Pages (status quo) Keep publishing module webspaces to GitHub Pages. Invest efforts to keep space needs low as we only have 1GiB per repository. -😡 Effort: Increasing. +😡 Effort: Increasing. + +Option P: Publish Action into "published" Repo +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +As we alread have the "published" repository, +we can push more content in there. +Up to the 10GiB repo limit. +.. plantuml:: -Option C: Centralized hosting under the Eclipse webspace -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + node "Module Repo" as ModuleRepo + node "eclipse-score-website-published" as PublishedRepo + node "eclipse-score-website" as WebsiteSrc + cloud "eclipse.dev/score" as EclipseSite -Host module webspaces in sub-folders of https://eclipse.dev/score/ -The site would be the canonical public landing page, -while modules may still publish artifact outputs to GitHub or to an internal storage bucket. + ModuleRepo -> PublishedRepo : "build" + WebsiteSrc -> PublishedRepo : "Build & Archive" + PublishedRepo <. EclipseSite : "pull every 5min" + ModuleRepo -[hidden]-> WebsiteSrc -😡 Effort: Infrastructure and migration needed. -Option X: ... -^^^^^^^^^^^^^ +💚 Effort: We must adapt our GitHub action's deploy steps. -Use an external hosting provider? -Pay GitHub for more space? +😡 Speed: Updating a huge "published" repo will take time. +💚 Independence: No HelpDesk needed to potentially adapt configuration. + +Option E: Combine Website from multiple Repos +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +We let the eclipse.dev website pull content from multiple repositories. +`The configuration is done by the Eclipse Foundation `_: + + Finally, to publish your website on eclipse.dev, + you'll need support from us to update your project's website metadata in the projects.eclipse.org (PMI). + This informs us on where to find the necessary static HTML to serve. + You can request an update to your website deployment metadata by opening a ticket. + +The configuration is visible as ``website_repo`` from +`the Eclipse API of S-CORE `_. + +.. plantuml:: + + node "Module Repo" as ModuleRepo + node "eclipse-score-website-published" as PublishedRepo + node "eclipse-score-website" as WebsiteSrc + cloud "eclipse.dev/score" as EclipseSite + node ".gh_pages branch" as gh_pages + + ModuleRepo -> gh_pages : "build" + WebsiteSrc -> PublishedRepo : "Build & Archive" + PublishedRepo <. EclipseSite : "pull every 5min" + gh_pages <. EclipseSite : "pull every 5min" + ModuleRepo -[hidden]-> WebsiteSrc + +💚 Effort: Request config change via Eclipse HelpDesk. + +💚 Speed: Faster than option P because many *small* repos. + +😡 Independence: HelpDesk needed to adapt configuration. (Add repo, rename folder) Evaluation ---------- +All options have the same costs in terms of hosting fees. + .. csv-table:: - :header: Criteria, Option G, Option C, Option X + :header: Criteria, Option G, Option P, Option E :widths: 20, 10, 10, 10 - Effort, 💚, 😡, ? + Effort, 😡, 💚, 💚 + Speed, --, 😡, 💚 + Independence, --, 💚, 😡 -decision tbd +Option G is not sustainable due to increasing effort. +Thus we pick option E because deployment speed is more important than independence. From 701b34c5273148fce623b4ae21dea03107a0910d Mon Sep 17 00:00:00 2001 From: Andreas Zwinkau <95761648+a-zw@users.noreply.github.com> Date: Wed, 19 Nov 2025 09:41:44 +0100 Subject: [PATCH 3/6] Apply suggestions from code review Co-authored-by: Alexander Lanin Signed-off-by: Andreas Zwinkau <95761648+a-zw@users.noreply.github.com> --- docs/design_decisions/DR-005-infra.rst | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/design_decisions/DR-005-infra.rst b/docs/design_decisions/DR-005-infra.rst index c6024c7f1dc..9e9e599210e 100644 --- a/docs/design_decisions/DR-005-infra.rst +++ b/docs/design_decisions/DR-005-infra.rst @@ -22,7 +22,7 @@ DR-005-Infra: Hosting Strategy for Module Documentation Context / Problem ----------------- -We host site content for modules using GitHub Pages (per-repo webspaces). +We currently host module documentation using GitHub Pages (per-repo webspaces). While GitHub *repos* can store up to 10GiB (size of ``.git`` folder), GitHub *Pages* only allows 1GiB of storage. While this works so far, the storage and site limits are becoming noticeable. @@ -62,7 +62,7 @@ No limits for this hosting are known. Goals and Requirements ^^^^^^^^^^^^^^^^^^^^^^ -1. Provide sufficient storage and bandwidth for released documentation. +1. Provide sufficient storage and bandwidth for documentation (releases and PR-previews). 2. Keep a consistent site/URL structure and navigation across modules. 3. Keep hosting and maintenance costs predictable and low. 4. Dedicated space for releases? @@ -75,13 +75,14 @@ Option G: Continue with per-repo GitHub Pages (status quo) Keep publishing module webspaces to GitHub Pages. Invest efforts to keep space needs low as we only have 1GiB per repository. +e.g. by optimizing page size, or providing PR previews only on demand. 😡 Effort: Increasing. Option P: Publish Action into "published" Repo ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -As we alread have the "published" repository, +As we alread have the "eclipse-score-website-published" repository, we can push more content in there. Up to the 10GiB repo limit. @@ -102,6 +103,8 @@ Up to the 10GiB repo limit. 😡 Speed: Updating a huge "published" repo will take time. +```suggestion +😡 Size: We risk running into size problems once again: ~500MB (see score repo measurement) * 20 modules (whatever the number is) = 10GB 💚 Independence: No HelpDesk needed to potentially adapt configuration. Option E: Combine Website from multiple Repos From 6a6984aa17357e50eb0e6339a5302fcd439eca56 Mon Sep 17 00:00:00 2001 From: Andreas Zwinkau Date: Wed, 19 Nov 2025 10:41:39 +0100 Subject: [PATCH 4/6] Revise with review feedback --- docs/design_decisions/DR-005-infra.rst | 77 ++++++++++++++++++++------ 1 file changed, 60 insertions(+), 17 deletions(-) diff --git a/docs/design_decisions/DR-005-infra.rst b/docs/design_decisions/DR-005-infra.rst index 9e9e599210e..24ea52cadae 100644 --- a/docs/design_decisions/DR-005-infra.rst +++ b/docs/design_decisions/DR-005-infra.rst @@ -19,24 +19,27 @@ DR-005-Infra: Hosting Strategy for Module Documentation :context: Infrastructure :decision: Combine Website from multiple Repos -Context / Problem ------------------ +Problem Description +------------------- We currently host module documentation using GitHub Pages (per-repo webspaces). -While GitHub *repos* can store up to 10GiB (size of ``.git`` folder), -GitHub *Pages* only allows 1GiB of storage. +**GitHub Pages only allows 1GiB of webspace**. While this works so far, the storage and site limits are becoming noticeable. +The score platform repository currently has 1GiB in gh-pages (460MiB ``.git`` repo size). More diagrams, pull-requests, and versions will exacerbate the problem. .. plantuml:: - node "Module Repo" as ModuleRepo - node ".gh_pages branch" as gh_pages + collections "Module Repos" as ModuleRepo + collections ".gh_pages branches" as gh_pages cloud "GitHub Pages" as GitHubPages ModuleRepo -> gh_pages : "build" gh_pages -> GitHubPages : "publish" +Context +^^^^^^^ + In addition to GitHub Pages, the project also has the website https://eclipse.dev/score/ hosted via the Eclipse Foundation. The website is relatively small and there are plans to move most content elsewhere @@ -67,6 +70,8 @@ Goals and Requirements 3. Keep hosting and maintenance costs predictable and low. 4. Dedicated space for releases? +⚠️ What about additional documentation artifacts from DoxyGen, RustDoc, ...? + Options Considered ------------------ @@ -79,6 +84,8 @@ e.g. by optimizing page size, or providing PR previews only on demand. 😡 Effort: Increasing. +The effort is serious enough that we don't consider the other criteria at all. + Option P: Publish Action into "published" Repo ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -88,7 +95,7 @@ Up to the 10GiB repo limit. .. plantuml:: - node "Module Repo" as ModuleRepo + collections "Module Repos" as ModuleRepo node "eclipse-score-website-published" as PublishedRepo node "eclipse-score-website" as WebsiteSrc cloud "eclipse.dev/score" as EclipseSite @@ -98,16 +105,21 @@ Up to the 10GiB repo limit. PublishedRepo <. EclipseSite : "pull every 5min" ModuleRepo -[hidden]-> WebsiteSrc +The limit is not 1GiB per repo anymore but 10GiB for all repos. +That sounds worse at first, because with 20 repos, it would be 10GiB / 20. +However, here the *average* size per repository matters. +With option G above a single repo limit is already a problem. +Still, this might not ease the problem sufficiently. 💚 Effort: We must adapt our GitHub action's deploy steps. 😡 Speed: Updating a huge "published" repo will take time. -```suggestion -😡 Size: We risk running into size problems once again: ~500MB (see score repo measurement) * 20 modules (whatever the number is) = 10GB +😡 Size: 10GiB total limit. + 💚 Independence: No HelpDesk needed to potentially adapt configuration. -Option E: Combine Website from multiple Repos +Option C: Combine Website from multiple Repos ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ We let the eclipse.dev website pull content from multiple repositories. @@ -123,11 +135,11 @@ The configuration is visible as ``website_repo`` from .. plantuml:: - node "Module Repo" as ModuleRepo + collections "Module Repos" as ModuleRepo node "eclipse-score-website-published" as PublishedRepo node "eclipse-score-website" as WebsiteSrc cloud "eclipse.dev/score" as EclipseSite - node ".gh_pages branch" as gh_pages + collections ".gh_pages branches" as gh_pages ModuleRepo -> gh_pages : "build" WebsiteSrc -> PublishedRepo : "Build & Archive" @@ -139,20 +151,51 @@ The configuration is visible as ``website_repo`` from 💚 Speed: Faster than option P because many *small* repos. +💚 Size: 10GiB per repo should suffice for a long time. + 😡 Independence: HelpDesk needed to adapt configuration. (Add repo, rename folder) +Option D: Direct Webspace Push +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Instead of using the foundation's pulling mechanism, +we could push directly to some webspace from each module's GitHub Action. + +The eclipse.dev/score website is separate and not relevant for this option. + +.. plantuml:: + + collections "Module Repos" as ModuleRepo + cloud webspace + + ModuleRepo -> webspace : "build & publish" + +😡 Effort: Requires custom setup for the publication? + +💚 Speed: Fast + +💚 Size: Independent of any GitHub limits. + +💚 Independence: Full control because custom. + Evaluation ---------- All options have the same costs in terms of hosting fees. +Criteria in order of importance (most important first): + .. csv-table:: - :header: Criteria, Option G, Option P, Option E - :widths: 20, 10, 10, 10 + :header: Criteria, Option G, Option P, Option C, Option D + :widths: 20, 10, 10, 10, 10 - Effort, 😡, 💚, 💚 - Speed, --, 😡, 💚 - Independence, --, 💚, 😡 + Effort, 😡, 💚, 💚, ❓ + Size, 😡, 😡, 💚, 💚 + Speed, ❔, 😡, 💚, 💚 + Independence, ❔, 💚, 😡, 💚 Option G is not sustainable due to increasing effort. +Option P still has risky size limits. Thus we pick option E because deployment speed is more important than independence. + +⚠️ evaluate option D properly From 7dd56c2fcf57d7b615b0383f0f61a9cd63f8c530 Mon Sep 17 00:00:00 2001 From: Andreas Zwinkau Date: Mon, 19 Jan 2026 14:54:25 +0100 Subject: [PATCH 5/6] Rename to avoid conflicts --- docs/design_decisions/{DR-005-infra.rst => DR-006-infra.rst} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/design_decisions/{DR-005-infra.rst => DR-006-infra.rst} (100%) diff --git a/docs/design_decisions/DR-005-infra.rst b/docs/design_decisions/DR-006-infra.rst similarity index 100% rename from docs/design_decisions/DR-005-infra.rst rename to docs/design_decisions/DR-006-infra.rst From 92e076bda99017f253dc6b40ba9d6150d1f67b1e Mon Sep 17 00:00:00 2001 From: Andreas Zwinkau Date: Mon, 19 Jan 2026 14:55:38 +0100 Subject: [PATCH 6/6] Adapt title --- docs/design_decisions/DR-006-infra.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/design_decisions/DR-006-infra.rst b/docs/design_decisions/DR-006-infra.rst index 24ea52cadae..1b046ff8237 100644 --- a/docs/design_decisions/DR-006-infra.rst +++ b/docs/design_decisions/DR-006-infra.rst @@ -10,7 +10,7 @@ SPDX-License-Identifier: Apache-2.0 -DR-005-Infra: Hosting Strategy for Module Documentation +DR-006-Infra: Hosting Strategy for Module Documentation ======================================================= .. dec_rec:: Hosting strategy for module webspaces