Roadmap Plugin

Bundled with iolanta ⩾ 2.1.12

Iolanta development roadmap YAML-LD Source Code

iolanta iolanta-development-roadmap.yamlld --as https://iolanta.tech/roadmap/datatypes/mermaid

graph LR
  B0edf7b956318("⬜ Discovery MCP discovers LD based on free form text")
  Bdbc3719a0b3f("⬜ HOWTO Make your own facet")
  B804d0b3c994c("⬜ First WASM based facet")
  Bbae84bb3037d("⬜ Tractatus Logico-Philosophicus → LD")
  B9665037a78d8("⬜ Render a Decision Matrix with Iolanta")
  B988d5d3c5240("⬜ Inference depends on alphabetical order of its CONSTRUCT queries")
  Bb40f83e8cf24("⬜ Implement YAML-LD Ontology")
  Bf21d26c7c614("⬜ <code>mermaid</code> datatype from roadmap plugin does not resolve nor is documented")
  https___iolanta_tech_Facet("Generate Facets list")
  click https___iolanta_tech_Facet "https://iolanta.tech/Facet/"
  B071c9be8f1db("⬜ Generate this roadmap from LD")
  B368c01d14192("⬜ Unblock Nanopubs")
  Bd89247cea044("⬜ Upper ontology not chosen for <code>roadmap</code>")
  Bfff5e8989b4e("⬜ Render LD from IPFS")
  B90ca643a0ed2("⬜ Manage ADRs with Iolanta")
  Bf9f7a63858f6("⬜ Roadmap <code>Unblocked</code> is a <code>Class</code>")
  Bae6299a47bc6("⬜ Implement a 3D view for the roadmap (because should look cool)")
  B7b16b4b4b96f("⬜ pyld fails on lexinfo")
  Bd75d10abd3fa("⬜ Write nanopublications with Iolanta")
  B80f2020766e8("⬜ <code>$type: Bug</code> does not work; maybe use some other syntax even?")
  Ba6a5b3b337be("⬜ Start jeeves-nanopublications")
  B5d5d954aad6e("⬜ Build roadmaps & plans with Iolanta")
  https___github_com_Nanopublication_nanopub_py_pull_180("PR 180: Nanopublication/nanopub-py is merged")
  click https___github_com_Nanopublication_nanopub_py_pull_180 "https://github.com/Nanopublication/nanopub-py/pull/180"
  Baa1bc7cbbeb4("⬜ Unable to specify if <code>Event</code> had happened")
  B2278567e7da9("⬜ Armenian pronouns nanopub")
  B5509ab3b3751("⬜ FOAF Title facet only reacts on foaf:Person class")
  B17e2df495f49("⬜ Iolanta starts with a blank console")
  Bb5cfa37f5673("⬜ SPARQL inference handled by sparqlspace")
  B6151f70f5ab2("⬜ sparqlspace has no integration tests")
  B6237e145dbd0("⬜ FOAF Title facet only reacts on foaf:Person class")
  B7f6c54146532("⬜ Iolanta starts with a blank console")
  Bbe4d7431dc66("⬜ SPARQL inference handled by sparqlspace")
  B8cffaa83c000("⬜ sparqlspace has no integration tests")
  Bd84618b7f641("⬜ pyld fails on lexinfo")
  B0edf7b956318 --> Bd75d10abd3fa
  B7b16b4b4b96f --> B2278567e7da9
  B368c01d14192 --> B2278567e7da9
  B9665037a78d8 --> B90ca643a0ed2
  Bd89247cea044 --> B80f2020766e8
  Bd89247cea044 --> Baa1bc7cbbeb4
  Bd89247cea044 --> Bf9f7a63858f6
  B90ca643a0ed2 --> B5d5d954aad6e
  B071c9be8f1db --> B5d5d954aad6e
  B5d5d954aad6e --> Bae6299a47bc6
  B368c01d14192 --> https___github_com_Nanopublication_nanopub_py_pull_180
  B368c01d14192 --> Ba6a5b3b337be
  B368c01d14192 --> B0edf7b956318
  classDef predicate fill:#1f2233,stroke:transparent,color:#f8fafc,stroke-width:0px;
  classDef hidden fill:transparent,stroke:transparent,color:transparent,stroke-width:0px;
  classDef nanopubdot fill:#0f172a,stroke:#0f172a,color:transparent,stroke-width:2px;
  classDef transparent fill:transparent,stroke:transparent,color:transparent,stroke-width:0px;
  class Edge_7e8f446d3164,Edge_d0a510126a11,Edge_936d868d41f4,Edge_c8f3391f6f6d,Edge_fad8ff6cfa64,Edge_5cf1b681b750,Edge_df8266c58034,Edge_470d7700efd5,Edge_e258e7290f29,Edge_a15eb121ff9b,Edge_0d453c8f89a8,Edge_3f9119679c2a,Edge_308eb0799615 predicate
classDef unblocked fill:#0a5,stroke:#063,stroke-width:2px,color:#fff;
class Bdbc3719a0b3f unblocked
class B804d0b3c994c unblocked
class Bbae84bb3037d unblocked
class B9665037a78d8 unblocked
class B988d5d3c5240 unblocked
class Bb40f83e8cf24 unblocked
class Bf21d26c7c614 unblocked
class https___iolanta_tech_Facet unblocked
class B071c9be8f1db unblocked
class B368c01d14192 unblocked
class Bd89247cea044 unblocked
class Bfff5e8989b4e unblocked
class B7b16b4b4b96f unblocked
class B5509ab3b3751 unblocked
class B17e2df495f49 unblocked
class Bb5cfa37f5673 unblocked
class B6151f70f5ab2 unblocked

iolanta-development-roadmap.yamlld (top 20 lines)

"@context": https://iolanta.tech/roadmap/contexts/v0.1.yamlld

tasks:
  # IPFS rendering
  - $id: _:ipfs
    $: Render LD from IPFS

  # Decision Matrix & ADRs workflow
  - $id: _:render-decision-matrix
    $: Render a Decision Matrix with Iolanta
    blocks:
      - $id: _:manage-adrs
        $: Manage ADRs with Iolanta
        blocks:
          - $id: _:manage-roadmaps
            $: Build roadmaps & plans with Iolanta
            blocks:
              - $id: _:roadmap3d
                $: Implement a 3D view for the roadmap (because should look cool)

# …

Quick Start

To use the Roadmap plugin in your roadmap files, import the context:

"@context": https://iolanta.tech/roadmap/contexts/v0.1.yamlld

This context provides the namespace prefixes and property mappings you need to write roadmap data.

Minimal Example

"@context": https://iolanta.tech/roadmap/contexts/v0.1.yamlld

$included:
  - $id: _:complete-docs
    $type: roadmap:Task
    $: Complete documentation
    blocks:
      - $: Publish release
        $type: roadmap:Task

Nesting Tasks

Tasks can be nested directly under blocks: or is-blocked-by: properties. This creates a more compact and readable structure:

- $type: roadmap:Task
  $: Main task
  blocks:
    - $: Subtask 1
      $type: roadmap:Task
    - $: Subtask 2
      $type: roadmap:Task
      blocks:
        - $: Nested subtask
          $type: roadmap:Task

Identifiers

When you need to reference a roadmap item from another item (using blocks or is-blocked-by), you must give it an identifier using $id. In roadmap files, identifiers should be blank nodes using the _: prefix:

• ✅ Good: $id: _:implement-auth
• ❌ Bad: $id: roadmap:task-1 (full URI not needed for local references)

If an item is not referenced anywhere else in your roadmap, you don't need to provide an $id at all. You only need an identifier when: - The item is referenced from elsewhere (e.g., blocks: [_:some-task]) - The item needs to be referenced later in the file

Data Model

The Roadmap plugin uses the following classes and properties:

• roadmap:Task

  ---

  A to-do item or feature
  Subclass of prov:Activity

• roadmap:Bug

  ---

  A known issue
  Subclass of roadmap:Task

• roadmap:Event

  ---

  A scheduled event or milestone
  Subclass of prov:Activity

• → roadmap:blocks

  ---

  Indicates that one item blocks another
  Inverse of roadmap:is-blocked-by, subproperty of prov:wasInformedBy

• ← roadmap:is-blocked-by

  ---

  Indicates that one item is blocked by another
  Inverse of roadmap:blocks, subproperty of prov:wasInformedBy

Relationship to PROV Ontology

The roadmap vocabulary builds on the PROV ontology (prov:Activity, prov:wasInformedBy), allowing roadmap items to be integrated with provenance tracking and activity descriptions.

Rendering

Command Line

Render a roadmap file as a Mermaid diagram:

iolanta path/to/roadmap.yamlld --as https://iolanta.tech/roadmap/datatypes/mermaid

In MkDocs

Use the Iolanta template to render roadmaps in your documentation:

{{ (docs / 'path/to/roadmap.yamlld') | as('https://iolanta.tech/roadmap/datatypes/mermaid') }}

Exporting to Images

Generate PNG or SVG images from your roadmap for use in blogs, documentation, or presentations:

# Generate PNG
iolanta path/to/roadmap.yamlld --as https://iolanta.tech/roadmap/datatypes/mermaid | mmdc -i - -o roadmap.png

# Generate SVG
iolanta path/to/roadmap.yamlld --as https://iolanta.tech/roadmap/datatypes/mermaid | mmdc -i - -o roadmap.svg -b transparent

This requires @mermaid-js/mermaid-cli to be installed. Install it with:

npm install -g @mermaid-js/mermaid-cli

Context Versioning

The roadmap context is versioned to ensure stability. Current version:

• v0.1: https://iolanta.tech/roadmap/contexts/v0.1.yamlld

When referencing the context, pin to a specific version (e.g., v0.1) for stability.

Future versions will be published at https://iolanta.tech/roadmap/contexts/v<version>.yamlld.