diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..592a962 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,24 @@ +## Description + +Brief description of changes. + +## Type of Change + +- [ ] Bug fix +- [ ] New feature +- [ ] Documentation update +- [ ] ADR (Architecture Decision Record) + +## ADR Checklist (if applicable) + +If this PR includes a new ADR, ensure: + +- [ ] ADR is added to `mkdocs.yml` nav section +- [ ] ADR is added to "Recent Decisions" table in `docs/index.md` +- [ ] ADR follows the standard template + +## Review + +- [ ] I have reviewed my own changes +- [ ] Documentation is updated (if needed) + diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml new file mode 100644 index 0000000..dede914 --- /dev/null +++ b/.github/workflows/deploy-docs.yml @@ -0,0 +1,42 @@ +name: Deploy Documentation + +on: + push: + branches: + - main + - master + workflow_dispatch: + +permissions: + contents: write + +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v6 + with: + fetch-depth: 0 + + - name: Configure Git Credentials + run: | + git config user.name "github-actions[bot]" + git config user.email "41898282+github-actions[bot]@users.noreply.github.com" + + - uses: actions/setup-python@v6 + with: + python-version: 3.x + + - name: Cache dependencies + uses: actions/cache@v4 + with: + key: mkdocs-material-${{ github.ref }} + path: ~/.cache + restore-keys: | + mkdocs-material- + + - name: Install dependencies + run: pip install -r requirements.txt + + - name: Build and Deploy + run: mkdocs gh-deploy --force diff --git a/docs/assets/favicon.png b/docs/assets/favicon.png new file mode 100644 index 0000000..a0fbbea Binary files /dev/null and b/docs/assets/favicon.png differ diff --git a/docs/assets/logo.png b/docs/assets/logo.png new file mode 100644 index 0000000..b426fb4 Binary files /dev/null and b/docs/assets/logo.png differ diff --git a/docs/decisions/0003-use-single-process-approach-for-architecture-requests.md b/docs/decisions/0003-use-single-process-approach-for-architecture-requests.md index 43304cf..0260f51 100644 --- a/docs/decisions/0003-use-single-process-approach-for-architecture-requests.md +++ b/docs/decisions/0003-use-single-process-approach-for-architecture-requests.md @@ -24,15 +24,12 @@ Use a **single unified process** where formality emerges naturally from impact. **Process:** ```mermaid +%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#a7c947', 'primaryTextColor': '#1a1a1a', 'primaryBorderColor': '#8bb030', 'lineColor': '#045c64', 'secondaryColor': '#e8f5e9', 'tertiaryColor': '#f5f5f5', 'fontFamily': 'Open Sans'}}}%% flowchart LR A[Open Issue] --> B{Discussion
Time varies} B -->|Simple| C[Close with
Answer] B -->|Complex| D[Create ADR PR] D --> E[Publish] - - style A fill:#e1f5ff - style D fill:#fff4e1 - style E fill:#e8f5e9 ``` **Key insight:** Same process, different discussion length based on natural impact. diff --git a/docs/decisions/0004-use-mkdocs-material-for-documentation-site.md b/docs/decisions/0004-use-mkdocs-material-for-documentation-site.md new file mode 100644 index 0000000..f563860 --- /dev/null +++ b/docs/decisions/0004-use-mkdocs-material-for-documentation-site.md @@ -0,0 +1,60 @@ +# ADR-0004. Use MkDocs Material for Documentation Site + +Date: 2025-11-28 + +## Status + +Accepted + +## Context + +We need a documentation site to publish ADRs, standards, and process documentation at `https://scilifelab.github.io/architecture/`. + +Requirements: + +- Automatic publishing from GitHub +- Support for Mermaid diagrams (same syntax as GitHub) +- Search functionality +- Easy for contributors (just Markdown) +- Professional appearance +- Adaptable to SciLifeLab visual identity + +## Decision + +Use **MkDocs Material** with SciLifeLab visual customization. + +## Rationale + +**Simple and effective:** + +- Markdown → beautiful website in 5 minutes +- Built-in Mermaid support (identical to GitHub) +- Contributors only need Markdown knowledge +- Industry standard (Google, Microsoft use it) + +**Better than alternatives:** + +- Quarto: Too complex for pure documentation +- Jekyll: Less modern, more configuration +- Custom solution: Unnecessary maintenance burden + +**Customizable:** +Material theme easily adapted to SciLifeLab brand through `mkdocs.yml` configuration. + +## Consequences + +**Positive:** + +- Fast deployment +- Low contributor barrier +- Professional appearance +- Excellent search +- Automatic publishing via GitHub Actions + +**Negative:** + +- Web-only output (no native PDF) +- Brand customization limited to theme capabilities + +**Implementation:** +Create `mkdocs.yml` with Material theme, SciLifeLab colors, and GitHub Actions deployment. diff --git a/docs/decisions/templates/template.md b/docs/decisions/templates/template.md index 1f7944b..85339a7 100644 --- a/docs/decisions/templates/template.md +++ b/docs/decisions/templates/template.md @@ -17,3 +17,4 @@ The change that we're proposing or have agreed to implement. ## Consequences What becomes easier or more difficult to do and any risks introduced by the change that will need to be mitigated. + diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..ac6836f --- /dev/null +++ b/docs/index.md @@ -0,0 +1,78 @@ +# SciLifeLab Architecture Board + +> Ensuring interoperable, sustainable, and FAIR infrastructure across SciLifeLab's federated platforms. + +The Architecture Board provides technical governance and guidance for SciLifeLab infrastructure, enabling seamless collaboration while respecting platform autonomy. We support decision-making for technical architecture across all SciLifeLab platforms and services. + +!!! question "Need Architecture Help?" + + - No question too small + - We aim to respond promptly + - Early guidance prevents expensive mistakes + + [:octicons-issue-opened-16: Open an Issue](https://github.com/SciLifeLab/architecture/issues/new?template=architecture-question.md){ .md-button .md-button--primary } + [:octicons-comment-discussion-16: Start a Discussion](https://github.com/SciLifeLab/architecture/discussions){ .md-button } + [:octicons-mail-16: architecture@scilifelab.se](mailto:architecture@scilifelab.se){ .md-button } + +## What We Do + +```mermaid +%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#a7c947', 'primaryTextColor': '#1a1a1a', 'primaryBorderColor': '#8bb030', 'lineColor': '#045c64', 'secondaryColor': '#e8f5e9', 'tertiaryColor': '#f5f5f5', 'fontFamily': 'Open Sans'}}}%% +graph LR + A[Project Team] -->|Question| B[Architecture Board] + B -->|Guidance| A + B -->|Decision| C[ADR] + C -->|Published| D[Documentation] + D -->|Informs| A +``` + +### :material-compass: Architecture Guidance + +Best practices for technical design, integration patterns, and technology choices. + +### :material-file-document-edit: Decision Records + +Transparent documentation of all significant architectural decisions (ADRs). + +### :material-connection: Cross-Platform Coordination + +Facilitate collaboration to ensure coherent architecture across SciLifeLab. + +## Recent Decisions + +| Decision | Status | Summary | +| --------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------ | +| [ADR-0004: MkDocs Material](decisions/0004-use-mkdocs-material-for-documentation-site.md) | Accepted | Use MkDocs Material for documentation site | +| [ADR-0003: Single Process](decisions/0003-use-single-process-approach-for-architecture-requests.md) | Accepted | Single process for architecture requests | +| [ADR-0002: CC BY-SA 4.0](decisions/0002-use-cc-by-sa-4-0-license.md) | Accepted | Use CC BY-SA 4.0 license for content | +| [ADR-0001: Record Decisions](decisions/0001-record-architecture-decisions.md) | Accepted | Record architecture decisions as ADRs | + +## Board Members + +| Name | Affiliation | Role | +| ----------------- | ----------- | -------------------------------------------------------------------------------------------------------------------- | +| Jonas Hagberg | NBIS | Chair, [Certified IT Architect](https://app.diplomasafe.com/sv-SE/diploma/d2e66e08f42702140adfb61a0fb2315ef6d93ccb8) | +| Johan Viklund | NBIS | Technical Expert | +| Jonas Söderberg | NBIS SCoRe | Technical Expert | +| Johannes Alneberg | NGI | Technical Expert | +| Jonas Windhager | NBIS BIIF | Technical Expert | + +_Adjunct members: Björn Nystedt, Hanna Kultima (Integrated Data Services Project Management Team)_ + +## Get Involved + +The Architecture Board welcomes input from all SciLifeLab teams and the broader academic community. Whether you have a technical proposal, an architecture concern, or need guidance on a decision, we're here to help. + +!!! tip "How to Contribute" + + 1. **Not sure yet?** Start a [GitHub Discussion](https://github.com/SciLifeLab//architecture/discussions) or email [architecture@scilifelab.se](mailto:architecture@scilifelab.se) + 2. **Have a question?** Open a [GitHub Issue](https://github.com/SciLifeLab/architecture/issues) to get guidance + 3. **Proposing a change?** Create an ADR following our [template](decisions/0001-record-architecture-decisions.md) + 4. **Found an issue?** Submit a pull request with your suggested improvements + +--- + +Part of [SciLifeLab](https://scilifelab.se) – Sweden's national infrastructure for life sciences research. + +**Please cite as:** +SciLifeLab Architecture Board. (2025). _SciLifeLab Architecture Governance._ GitHub repository: diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css new file mode 100644 index 0000000..4b813c5 --- /dev/null +++ b/docs/stylesheets/extra.css @@ -0,0 +1,132 @@ +/* SciLifeLab Visual Identity Colors */ + +@import url("https://fonts.googleapis.com/css2?family=Open+Sans:wght@300;400;500;600;700&display=swap"); + +:root { + /* SciLifeLab Brand Colors */ + --scilifelab-lime: #a7c947; + --scilifelab-lime-dark: #8bb030; + --scilifelab-teal: #045c64; + --scilifelab-teal-dark: #034750; + + /* MkDocs Material overrides */ + --md-primary-fg-color: #045c64; + --md-primary-fg-color--light: #067a85; + --md-primary-fg-color--dark: #034750; + --md-accent-fg-color: #a7c947; + + /* Typography */ + --md-text-font: "Open Sans", -apple-system, BlinkMacSystemFont, Helvetica, + Arial, sans-serif; +} + +/* Dark mode */ +[data-md-color-scheme="slate"] { + --md-primary-fg-color: #045c64; + --md-accent-fg-color: #a7c947; + --md-typeset-a-color: #a7c947; +} + +/* Header - Teal */ +.md-header { + background-color: #045c64; +} + +/* Navigation tabs */ +.md-tabs { + background-color: #034750; +} + +/* Logo sizing */ +.md-header__button.md-logo img { + height: 1.6rem; + width: auto; +} + +/* Links in content */ +.md-typeset a:not(.md-button) { + color: #045c64; +} + +[data-md-color-scheme="slate"] .md-typeset a:not(.md-button) { + color: #a7c947; +} + +/* Headings */ +.md-typeset h2 { + border-bottom: 2px solid #a7c947; + padding-bottom: 0.4rem; +} + +/* Tables */ +.md-typeset table:not([class]) th { + background-color: #045c64; + color: white; +} + +/* Code */ +.md-typeset code { + background-color: rgba(4, 92, 100, 0.1); + color: #045c64; +} + +[data-md-color-scheme="slate"] .md-typeset code { + background-color: rgba(167, 201, 71, 0.15); + color: #c5db7a; +} + +/* Buttons - Primary (lime) */ +.md-typeset .md-button--primary { + background-color: #a7c947; + border-color: #a7c947; + color: #1a1a1a; +} + +.md-typeset .md-button--primary:hover { + background-color: #8bb030; + border-color: #8bb030; +} + +/* Buttons - Secondary in dark mode: Teal with white text */ +[data-md-color-scheme="slate"] .md-typeset .md-button:not(.md-button--primary) { + background-color: #045c64; + border-color: #045c64; + color: #ffffff; +} + +[data-md-color-scheme="slate"] + .md-typeset + .md-button:not(.md-button--primary):hover { + background-color: #067a85; + border-color: #067a85; + color: #ffffff; +} + +/* Footer */ +.md-footer { + background-color: #045c64; +} + +.md-footer-meta { + background-color: #034750; +} + +/* Admonitions */ +.md-typeset .admonition.note, +.md-typeset details.note { + border-color: #045c64; +} + +.md-typeset .admonition.tip, +.md-typeset details.tip { + border-color: #a7c947; +} + +/* Active nav item */ +.md-nav__link--active { + color: #045c64 !important; +} + +[data-md-color-scheme="slate"] .md-nav__link--active { + color: #a7c947 !important; +} diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..9cbff3c --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,102 @@ +site_name: SciLifeLab Architecture +site_url: https://scilifelab.github.io/architecture/ +site_description: Architecture decisions and guidelines for SciLifeLab infrastructure +site_author: SciLifeLab Architecture Board + +repo_name: scilifelab/architecture +repo_url: https://github.com/scilifelab/architecture + +theme: + name: material + logo: assets/logo.png + favicon: assets/favicon.png + font: + text: Open Sans + code: Fira Code + icon: + repo: fontawesome/brands/github + palette: + - media: "(prefers-color-scheme: light)" + scheme: default + primary: teal + accent: lime + toggle: + icon: material/brightness-7 + name: Switch to dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + primary: teal + accent: lime + toggle: + icon: material/brightness-4 + name: Switch to light mode + features: + - navigation.instant + - navigation.tracking + - navigation.tabs + - navigation.top + - navigation.footer + - search.suggest + - search.highlight + - content.code.copy + +extra_css: + - stylesheets/extra.css + +markdown_extensions: + - admonition + - pymdownx.details + - pymdownx.emoji: + emoji_index: !!python/name:material.extensions.emoji.twemoji + emoji_generator: !!python/name:material.extensions.emoji.to_svg + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format + - pymdownx.highlight: + anchor_linenums: true + - pymdownx.inlinehilite + - tables + - attr_list + - toc: + permalink: true + +plugins: + - search + +nav: + - Home: index.md + - Architecture Decisions: + - decisions/0001-record-architecture-decisions.md + - decisions/0002-use-cc-by-sa-4-0-license.md + - decisions/0003-use-single-process-approach-for-architecture-requests.md + - decisions/0004-use-mkdocs-material-for-documentation-site.md + +extra: + social: + - icon: fontawesome/brands/github + link: https://github.com/SciLifeLab + - icon: fontawesome/solid/globe + link: https://scilifelab.se + generator: false + consent: + title: Cookie consent + description: >- + We use cookies to recognize your repeated visits and preferences, as well + as to measure the effectiveness of our documentation and whether users + find what they're searching for. With your consent, you're helping us to + make our documentation better. + actions: + - accept + - reject + - manage + cookies: + github: + name: GitHub + checked: true + +copyright: >- + Licensed under + CC BY-SA 4.0 + by SciLifeLab diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..6efdf48 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,2 @@ +mkdocs-material>=9.7 + diff --git a/scripts/adr-new b/scripts/adr-new index 6e23629..68db2d4 100755 --- a/scripts/adr-new +++ b/scripts/adr-new @@ -15,3 +15,4 @@ if [ -n "$output" ] && [ -f "$output" ]; then echo "$output" fi +