From 586cdc6bc6163d6db7e9254f42c9afe0e7f5fd21 Mon Sep 17 00:00:00 2001 From: cedricdcc Date: Wed, 12 Nov 2025 11:49:37 +0100 Subject: [PATCH 1/2] Add publication details overview, Mermaid diagram, GH Pages sites, W3ID.org info, and future endpoints placeholder --- .../publication-details.md | 131 ++++++++++++------ 1 file changed, 91 insertions(+), 40 deletions(-) diff --git a/book/07-technical-details/publication-details.md b/book/07-technical-details/publication-details.md index 53e1879..5894c87 100644 --- a/book/07-technical-details/publication-details.md +++ b/book/07-technical-details/publication-details.md @@ -11,9 +11,6 @@ EMO-BON uses W3ID.org for persistent identifiers. **Purpose**: Provide stable, long-term URIs that won't break if hosting infrastructure changes. **Usage**: -- Ontology namespaces -- Profile URIs -- Key entity identifiers **Example**: `https://w3id.org/emobon/` may redirect to `https://data.emobon.embrc.eu/` @@ -30,10 +27,6 @@ EMO-BON uses GitHub Pages for publishing static content. **Purpose**: Central entry point for EMO-BON data **Content**: -- Links to all observatories -- Documentation -- Data catalog -- Project information **Custom Domain**: Configured via CNAME file to use `data.emobon.embrc.eu` @@ -44,10 +37,6 @@ EMO-BON uses GitHub Pages for publishing static content. **Purpose**: Human-readable views of observatory data **Content**: -- Sample listings -- Sampling events -- Environmental measurements -- Downloadable data files ### Profile Sites @@ -56,10 +45,6 @@ EMO-BON uses GitHub Pages for publishing static content. **Purpose**: Documentation of RO-Crate profiles **Content**: -- Profile specifications -- Field definitions -- Semantic templates -- Examples ### Documentation Books @@ -83,12 +68,6 @@ See the [Conventions](../08-addendum/conventions.md) section for naming guidelin ### Repository Types -- **-crate**: RO-Crate data repositories -- **-profile**: RO-Profile specifications -- **-action**: GitHub Actions -- **-docker**: Docker images -- **-book**: Documentation books -- **.github.io**: GitHub Pages sites ## Publishing Workflow @@ -122,40 +101,112 @@ EMO-BON uses the custom domain `data.emobon.embrc.eu`: ### Static Files -- HTML pages -- CSS stylesheets -- JavaScript for interactivity -- Images and media ### Data Files -- CSV exports -- RDF/Turtle files -- JSON-LD metadata -- Downloadable datasets ### API Endpoints -- SPARQL endpoint (when available) -- GitHub API for repository access -- UDAL query service (in development) ## Versioning and Archival ### Git Versioning -- All content versioned in Git -- Full history preserved -- Tags for releases ### DOIs EMO-BON datasets may receive DOIs for citation: -- Zenodo integration for releases -- Per-observatory or per-analysis DOIs ### Long-term Preservation -- GitHub provides backup -- Periodic exports to archives -- Integration with institutional repositories +# Publication Details + +## Overview + +This document provides an overview and detailed description of all publication endpoints managed by the emo-bon organization, including GitHub Pages sites and W3ID.org redirects. It is structured to support future additions of other publication mechanisms. + +### Current Publication Endpoints + +- GitHub Pages sites (across emo-bon organization) +- W3ID.org redirects +- [Placeholder] Other endpoints (to be added) + +--- + +## Mermaid Diagram: Publication Endpoints + +```mermaid +flowchart TD + A[emo-bon Organization] --> B[data-workflow-book] + A --> C[emo-bon.github.io] + A --> D[observatory-xxx-crate] + A --> E[profile-xxx] + A --> F[other-book] + C --> G[data.emobon.embrc.eu] + D --> H[data.emobon.embrc.eu/observatory-xxx-crate/] + E --> I[data.emobon.embrc.eu/profile-xxx/] + F --> J[data.emobon.embrc.eu/other-book/] + subgraph GH_Pages_Sites + C + D + E + F + end +``` + +--- + +## Details + +### GitHub Pages Publications + +Below is a list of current GitHub Pages sites published by the emo-bon organization. Each site serves a specific purpose within the EMO-BON data workflow and documentation ecosystem. + +#### Main Website +- **Repository:** [emo-bon.github.io](https://github.com/emo-bon/emo-bon.github.io) +- **URL:** [https://data.emobon.embrc.eu/](https://data.emobon.embrc.eu/) +- **Purpose:** Central entry point for EMO-BON data, documentation, and project information. + +#### Observatory Crate Sites +- **Pattern:** `observatory-{obsid}-crate` (e.g., [observatory-abc-crate](https://github.com/emo-bon/observatory-abc-crate)) +- **URL:** `https://data.emobon.embrc.eu/observatory-{obsid}-crate/` +- **Purpose:** Human-readable views of observatory data, including sample listings, events, and downloadable files. + +#### Profile Sites +- **Pattern:** `{name}-profile` (e.g., [analysis-profile](https://github.com/emo-bon/analysis-profile)) +- **URL:** `https://data.emobon.embrc.eu/{name}-profile/` +- **Purpose:** Documentation of RO-Crate profiles, including specifications and semantic templates. + +#### Documentation Books +- **Pattern:** `{name}-book` (e.g., [data-workflow-book](https://github.com/emo-bon/data-workflow-book)) +- **URL:** `https://data.emobon.embrc.eu/{name}-book/` +- **Purpose:** Comprehensive documentation, technical details, and best practices. + +#### Other Sites +- [Placeholder for future GitHub Pages publications] + +### W3ID.org + +W3ID.org is a community-driven service for providing persistent, reliable URIs for web resources, especially in the context of linked data and semantic web projects. See [w3id.org](https://w3id.org/) for more information. + +#### Purpose +- Ensures long-term stability of URIs, even if hosting infrastructure changes +- Used for ontology namespaces, profile URIs, and key entity identifiers in EMO-BON + +#### EMO-BON Implementation +- EMO-BON maintains its W3ID configuration at: [emo-bon/w3id.org](https://github.com/emo-bon/w3id.org/tree/master/emo-bon) +- Each path under `https://w3id.org/emobon/` is mapped to the appropriate resource or documentation +- Redirection is managed via an `.htaccess` file in the repository + +##### Example .htaccess logic +```apache +RewriteEngine On +RewriteRule ^emobon/(.*)$ https://data.emobon.embrc.eu/$1 [R=302,L] +``` +This rule redirects requests from `https://w3id.org/emobon/...` to the corresponding path at `https://data.emobon.embrc.eu/...`. + +For more details, see the [emo-bon w3id.org repo](https://github.com/emo-bon/w3id.org/tree/master/emo-bon). + +### Other Publication Endpoints + +This section is reserved for future publication endpoints. If new mechanisms or platforms are adopted, documentation will be added here. From d8077807e2f1a82ca8d9a6343f60b880af14d168 Mon Sep 17 00:00:00 2001 From: cedricdcc Date: Wed, 12 Nov 2025 11:55:56 +0100 Subject: [PATCH 2/2] Add documentation for repo naming, types, publishing workflow, custom domain, content delivery, versioning, and DOIs --- .../publication-details.md | 73 +++++++++++++++++++ 1 file changed, 73 insertions(+) diff --git a/book/07-technical-details/publication-details.md b/book/07-technical-details/publication-details.md index 5894c87..e8b9f9f 100644 --- a/book/07-technical-details/publication-details.md +++ b/book/07-technical-details/publication-details.md @@ -157,6 +157,79 @@ flowchart TD --- ## Details +### Versioning and Archival + +#### Git Versioning +- All content is versioned in Git, preserving full history and supporting reproducibility. +- Tags are used for releases and important milestones. + +#### DOIs +- EMO-BON datasets may receive DOIs for citation and long-term reference. +- Zenodo integration is used for releases, enabling per-observatory or per-analysis DOIs. +### Content Delivery + +GitHub Pages sites in the emo-bon organization deliver a variety of content types: + +#### Static Files +- HTML pages +- CSS stylesheets +- JavaScript for interactivity +- Images and media + +#### Data Files +- CSV exports +- RDF/Turtle files +- JSON-LD metadata +- Downloadable datasets + +#### API Endpoints +- SPARQL endpoint (where available) +- GitHub API for repository access +- UDAL query service (in development) +### Custom Domain Configuration + +EMO-BON uses the custom domain `data.emobon.embrc.eu` for its main GitHub Pages site and related publications. This is configured as follows: +1. **CNAME File**: Each repository intended for publication includes a `CNAME` file in its root, specifying the custom domain. +2. **DNS Configuration**: EMBRC manages DNS records to point the domain to GitHub Pages servers. +3. **GitHub Configuration**: Repository settings are updated to use the custom domain. +4. **HTTPS**: GitHub Pages automatically provides HTTPS for custom domains. +### Publishing Workflow + +#### Automated Publishing + +For data repositories and sites, publishing is typically automated: +1. **Data Changes**: Updates (e.g., logsheet edits) trigger a GitHub Actions workflow. +2. **Processing**: Data is validated and processed automatically. +3. **Generation**: RO-Crate packages and HTML content are generated. +4. **Deployment**: Results are pushed to the `gh-pages` branch. +5. **Publication**: GitHub Pages serves the updated content to the web. + +#### Manual Publishing + +For documentation and profile repositories, publishing is often manual: +1. **Edit**: Changes are made in the main branch. +2. **Review**: Pull requests are reviewed and approved. +3. **Merge**: Approved changes are merged to main. +4. **Build**: GitHub Actions build the site or documentation. +5. **Deploy**: The site is deployed to GitHub Pages. +### Repository Naming Conventions + +Repository names in the emo-bon organization follow clear conventions to ensure consistency and discoverability. For detailed guidelines, see the [Conventions](../08-addendum/conventions.md) section. + +Common patterns include: +- Use of hyphens to separate words +- Suffixes indicating repository type (e.g., `-crate`, `-profile`, `-book`) +- Descriptive names for observatories, profiles, and documentation + +### Repository Types + +The following repository types are used in the emo-bon organization: +- **-crate**: RO-Crate data repositories containing structured datasets and metadata +- **-profile**: RO-Profile specifications defining metadata schemas and templates +- **-action**: GitHub Actions for workflow automation +- **-docker**: Docker images for reproducible environments +- **-book**: Documentation books (e.g., this data workflow book) +- **.github.io**: GitHub Pages sites for web publication ### GitHub Pages Publications