This chapter map is generated from the `#` and `##` headings in the numbered chapter files. Click any chapter or section box to open it.
+ +```{mermaid} +mindmap + root((S-CORE Infrastructure)) + node_001["`1 Source Code +Infrastructure 🟠`"] + node_002["`1.1 Hosting & Organization +⚪`"] + node_003["`1.2 Repository +Provisioning & Lifecycle 🟡`"] + node_004["`1.3 Repository Policy +Management 🔴`"] + node_005["1.4 Repository Standards 🟠"] + node_006["`2 Developer Environment +🟡`"] + node_007["2.1 Central Devcontainer 🟠"] + node_008["`2.2 Local Auxiliary +Tooling 🟡`"] + node_009["3 Build & Dependencies ⚪"] + node_010["3.1 Build System ⚪"] + node_011["`3.2 Dependency Management +⚪`"] + node_012["3.3 Toolchain Management ⚪"] + node_013["`3.4 Build Reproducibility +& Evidence ⚪`"] + node_014["`3.5 Build Execution +Infrastructure ⚪`"] + node_015["4 Testing 🟠"] + node_016["`4.1 Test Framework +Integration 🟠`"] + node_017["4.2 Test Traceability 🟠"] + node_018["`4.3 Test Execution & +Dynamic Analysis 🟠`"] + node_019["4.4 Test Reporting 🟠"] + node_020["`5 Code Analysis +Infrastructure ⚪`"] + node_021["5.1 Tooling Baseline ⚪"] + node_022["`5.2 Shared Rule +Configuration ⚪`"] + node_023["5.3 Execution Model ⚪"] + node_024["5.4 Security Scanning 🟠"] + node_025["`5.5 Results and Governance +⚪`"] + node_026["`6 Compliance & +Dependency Analysis ⚪`"] + node_027["6.1 File-Level Licensing ⚪"] + node_028["6.2 Dependency Analysis ⚪"] + node_029["`6.3 SBOM Scoping and +Compliance Evidence ⚪`"] + node_030["`6.4 License Checks and +Compliance ⚪`"] + node_031["`6.5 Monitoring and +Governance ⚪`"] + node_032["`7 Automation +Infrastructure & +Continuous Integration +(CI) ⚪`"] + node_033["7.1 Runners 🟠"] + node_034["7.2 Reusable Workflows ⚪"] + node_035["`7.3 Cross-Repository +Integration ⚪`"] + node_036["7.4 Secrets Management ⚪"] + node_037["7.5 CI Observability ⚪"] + node_038["`8 Release & Distribution +⚪`"] + node_039["8.1 Deliverable Types ⚪"] + node_040["`8.2 Distribution Channels +⚪`"] + node_041["8.3 Release Metadata ⚪"] + node_042["8.4 Consumer Access ⚪"] + node_043["`8.5 Post-Release +Communication & Response ⚪`"] + node_044["`9 Documentation & +Traceability 🟠`"] + node_045["9.1 Authoring & Tooling 🟡"] + node_046["`9.2 Build, Validation & +Publishing 🟡`"] + node_047["`9.3 Cross-Repository +Documentation Integration +🔴`"] + node_048["`9.4 Engineering +Documentation & +Traceability 🟠`"] + node_049["`10 Infrastructure +Operations ⚪`"] + node_050["`10.1 CI Runner Operations +⚪`"] + node_051["`10.2 Infrastructure +Monitoring ⚪`"] + node_052["`10.3 Infrastructure +Maintenance ⚪`"] + node_053["`10.4 Infrastructure +Governance ⚪`"] +``` + + + +:::{toctree} +:maxdepth: 1 +:hidden: + +01-source-code-infrastructure +02-developer-environment +03-build-infrastructure +04-testing-infrastructure +05-static-analysis-infrastructure +06-compliance-infrastructure +07-automation-integration +08-artifact-distribution +09-documentation-infrastructure +10-infrastructure-operations +decisions +::: diff --git a/docs/how-to/building.md b/docs/how-to/building.md new file mode 100644 index 0000000..cc13f62 --- /dev/null +++ b/docs/how-to/building.md @@ -0,0 +1,51 @@ +# How to Build with Bazel + +## Configure registries + +Every S-CORE module repository configures two Bazel registries in `.bazelrc`: + +```text +common --registry=https://raw.githubusercontent.com/eclipse-score/bazel_registry/main/ +common --registry=https://bcr.bazel.build +``` + +The first line resolves S-CORE internal modules. The second line falls back to the public [Bazel Central Registry](https://registry.bazel.build/) for everything else. + +## Add a dependency + +Declare dependencies in `MODULE.bazel`: + +```python +bazel_dep(name = "my_dependency", version = "1.2.3") +``` + +Use the [Registry UI](https://eclipse-score.github.io/bazel_registry_ui/) to discover available modules and their versions. + +## Find available modules + +The [Registry UI](https://eclipse-score.github.io/bazel_registry_ui/) lists all modules published to the S-CORE registry. Each registry entry corresponds to a GitHub Release in the module's repository. + +## Configure toolchains + +Build-side toolchains and policy modules are separate concerns: + +| Repository | Role | +|---|---| +| [bazel_cpp_toolchains](https://github.com/eclipse-score/bazel_cpp_toolchains) | **How to compile** C++ (Linux, QNX) | +| [toolchains_rust](https://github.com/eclipse-score/toolchains_rust) | **How to compile** Rust (incl. Ferrocene) | +| [score_cpp_policies](https://github.com/eclipse-score/score_cpp_policies) | **Which rules to enforce** for C++ | +| [score_rust_policies](https://github.com/eclipse-score/score_rust_policies) | **Which rules to enforce** for Rust | + +Toolchains define compilers and linkers. Policies define warning baselines, lint rules, and sanitizer selections. They evolve independently. + +## Refresh lock files + +`MODULE.bazel.lock` and `uv.lock` should be committed. When dependency declarations change, refresh lock files: + +```bash +pre-commit run --all-files +``` + +## Start a new module + +Use [module_template](https://github.com/eclipse-score/module_template) as a starting point. It provides the standard directory layout, `.bazelrc`, devcontainer configuration, and CI workflows. See [Tutorial: Creating a New Module](../tutorials/creating-a-module.md) for a step-by-step walkthrough. diff --git a/docs/how-to/code-quality.md b/docs/how-to/code-quality.md new file mode 100644 index 0000000..45f4968 --- /dev/null +++ b/docs/how-to/code-quality.md @@ -0,0 +1,53 @@ +# How to Enforce Code Quality + +## Set up pre-commit hooks + +```bash +pre-commit install +``` + +Run all checks manually: + +```bash +pre-commit run --all-files +``` + +Hook definitions are maintained in [eclipse-score/tooling](https://github.com/eclipse-score/tooling/blob/main/.pre-commit-hooks.yaml). Checks include formatting, YAML validation, copyright headers, and lock file freshness. + +## Add copyright and license headers + +Every source file needs: + +- A **copyright notice** in the file header +- An **SPDX license identifier** + +For file formats that do not support inline comments, use a `.license` sidecar file alongside the source file. + +Pre-commit hooks and CI PR checks from [eclipse-score/tooling](https://github.com/eclipse-score/tooling) enforce header presence automatically. + +## Apply C++ policies + +[score_cpp_policies](https://github.com/eclipse-score/score_cpp_policies) centralizes: + +- Warning baselines +- Sanitizer feature selections (ASan, UBSan, LSan, TSan) +- Constraint targets + +Consume these policies as a Bazel dependency to apply consistent C++ quality rules across repositories. + +## Apply Rust policies + +[score_rust_policies](https://github.com/eclipse-score/score_rust_policies) packages: + +- Shared Clippy lint rules +- rustfmt defaults + +## Understand where checks run + +| Stage | What runs | Speed | +|---|---|---| +| **Local (pre-commit)** | Formatting, YAML, copyright headers, lock files | Seconds | +| **Bazel build** | Compiler warnings, lint policies, sanitizers | Minutes | +| **CI** | Full test suite, coverage, compliance checks | Minutes | + +Pre-commit catches formatting and hygiene fast. Bazel enforces deeper checks. CI is the final gate. diff --git a/docs/how-to/index.md b/docs/how-to/index.md new file mode 100644 index 0000000..d7fd5d2 --- /dev/null +++ b/docs/how-to/index.md @@ -0,0 +1,31 @@ +# How-to Guides + +Practical recipes for specific tasks. Assumes you already have a working environment. + +## Module development + +- [Building with Bazel](building.md) — Registry, dependencies, toolchains, lock files +- [Testing](testing.md) — Test frameworks, coverage, sanitizers, QNX +- [Code Quality](code-quality.md) — Pre-commit, lint policies, copyright headers +- [Publishing Modules](publishing.md) — Release, registry import, consumer access +- [Writing Documentation](writing-docs.md) — Bazel + Sphinx/MyST setup, local preview, validation + +## Infrastructure development + +- [Update the Devcontainer](update-devcontainer.md) — Build, publish, and roll out a new shared image +- [Manage CI Secrets](manage-ci-secrets.md) — Create, rotate, and replace secrets with OIDC +- [Update a Shared Toolchain](update-toolchain.md) — Bump compiler or policy versions across repositories + +:::{toctree} +:maxdepth: 1 +:hidden: + +building +testing +code-quality +publishing +writing-docs +update-devcontainer +manage-ci-secrets +update-toolchain +::: diff --git a/docs/how-to/manage-ci-secrets.md b/docs/how-to/manage-ci-secrets.md new file mode 100644 index 0000000..a81bdc3 --- /dev/null +++ b/docs/how-to/manage-ci-secrets.md @@ -0,0 +1,106 @@ +# How to Manage CI Secrets + +This guide covers creating, scoping, rotating, and replacing static secrets with federated identity (OIDC) in S-CORE CI workflows. + +## Secret scopes in GitHub Actions + +GitHub provides three secret scopes: + +| Scope | Where set | Who can use it | +|---|---|---| +| Repository | Repository → Settings → Secrets | Workflows in that repository | +| Organization | Org → Settings → Secrets | Workflows in repositories where the secret is granted | +| Environment | Repository → Settings → Environments | Workflows that target that environment | + +**Default to the narrowest scope that works.** Use environment secrets for deploy-time credentials that should be gated by environment protection rules (e.g. requiring a reviewer before a secret is accessible). + +## Create a new secret + +1. Decide on the scope (repository, organization, or environment). +2. Go to the appropriate Settings → Secrets page on GitHub. +3. Click **New secret** (or **New repository secret** / **New organization secret**). +4. Give the secret a clear, uppercase, underscore-separated name (e.g. `REGISTRY_TOKEN`). +5. Paste the secret value and save. + +To reference it in a workflow: + +```yaml +env: + MY_TOKEN: ${{ secrets.MY_TOKEN }} +``` + +Or pass it directly to a step: + +```yaml +- name: Authenticate + run: some-tool login + env: + TOKEN: ${{ secrets.MY_TOKEN }} +``` + +## Rotate a secret + +1. Generate the new credential in the upstream service (GitHub PAT, API key, etc.). +2. Update the secret value in GitHub Settings. +3. Verify that workflows using the secret still succeed after rotation. +4. Revoke the old credential. + +Rotation should happen on a regular cadence (e.g. annually for long-lived PATs) or immediately when a credential is suspected to be compromised. + +## Replace a static secret with OIDC + +OIDC lets CI jobs request short-lived credentials from a cloud provider instead of storing long-lived static secrets. This is the preferred pattern for cloud access where the provider supports it. + +### How it works + +``` +GitHub Actions job → requests OIDC token from GitHub + → exchanges token at cloud provider + → receives short-lived credential + → calls cloud provider API +``` + +The cloud provider is configured to trust GitHub's OIDC issuer and to grant access to tokens with specific claims (e.g. the repository name, branch, or environment). + +### Example: AWS + +1. In AWS IAM, create an OIDC identity provider for `token.actions.githubusercontent.com`. +2. Create an IAM role with a trust policy that allows GitHub tokens from your repository and branch. +3. In the workflow, use the `aws-actions/configure-aws-credentials` action — no static secret needed: + +```yaml +permissions: + id-token: write + contents: read + +steps: + - uses: aws-actions/configure-aws-credentials@v4 + with: + role-to-assume: arn:aws:iam::123456789012:role/my-role + aws-region: eu-central-1 +``` + +For other providers, the pattern is the same: create the OIDC trust on the provider side, then use the appropriate GitHub Action to request credentials. + +## Cross-repository token provisioning + +S-CORE workflows sometimes need to act across repositories (e.g. opening a PR in another repo). The `cicd-actions` repository provides a composite action for this: + +```yaml +- uses: eclipse-score/cicd-actions/get-app-token@Overview, roadmap, contribution guide, and reference
++ This site explains what S-CORE infrastructure is, which shared capabilities and repositories already exist, + how mature they are, what is still missing, and how a concrete issue or pull request fits into the bigger picture. + Whether you're asking how we do something, where to look for a topic, or how an issue fits the big picture — start here. +
+Contributing to this documentation
+ +Contributing Guide
+Documentation style, structure, and review checklist for contributors to this site.
+ + +How to Write Docs
+Bazel + Sphinx/MyST setup, local preview, validation workflow.
+ +Infrastructure Team
+ +Meeting Minutes
+Infrastructure team meeting notes on GitHub Discussions.
+ + +Slack: #score-infrastructure
+Main channel for infrastructure team discussion.
+ + +Slack: #score-infrastructure-review-requests
+Drop PR links here for review — no comments, just links.
+ + +Repository Overview
+Cross-repo metrics and status across all eclipse-score repositories.
+ +S-CORE Project
+ + + +