diff --git a/docs/explore-and-author/graph-exploration/versioning-of-graph-changes/20-10-ActualChangesets.png b/docs/explore-and-author/graph-exploration/versioning-of-graph-changes/20-10-ActualChangesets.png deleted file mode 100644 index 5751d5a74..000000000 Binary files a/docs/explore-and-author/graph-exploration/versioning-of-graph-changes/20-10-ActualChangesets.png and /dev/null differ diff --git a/docs/explore-and-author/graph-exploration/versioning-of-graph-changes/20-10-ConfigureVersioningGraph.png b/docs/explore-and-author/graph-exploration/versioning-of-graph-changes/20-10-ConfigureVersioningGraph.png deleted file mode 100644 index 85702c722..000000000 Binary files a/docs/explore-and-author/graph-exploration/versioning-of-graph-changes/20-10-ConfigureVersioningGraph.png and /dev/null differ diff --git a/docs/explore-and-author/graph-exploration/versioning-of-graph-changes/20-10-CreateVersioningGraph.png b/docs/explore-and-author/graph-exploration/versioning-of-graph-changes/20-10-CreateVersioningGraph.png deleted file mode 100644 index c359d273d..000000000 Binary files a/docs/explore-and-author/graph-exploration/versioning-of-graph-changes/20-10-CreateVersioningGraph.png and /dev/null differ diff --git a/docs/explore-and-author/graph-exploration/versioning-of-graph-changes/24-1-GraphTypes.png b/docs/explore-and-author/graph-exploration/versioning-of-graph-changes/24-1-GraphTypes.png deleted file mode 100644 index 38c351fc5..000000000 Binary files a/docs/explore-and-author/graph-exploration/versioning-of-graph-changes/24-1-GraphTypes.png and /dev/null differ diff --git a/docs/explore-and-author/graph-exploration/versioning-of-graph-changes/add-new-graph.png b/docs/explore-and-author/graph-exploration/versioning-of-graph-changes/add-new-graph.png new file mode 100644 index 000000000..23f195fcd Binary files /dev/null and b/docs/explore-and-author/graph-exploration/versioning-of-graph-changes/add-new-graph.png differ diff --git a/docs/explore-and-author/graph-exploration/versioning-of-graph-changes/add-versioning-graph-property.png b/docs/explore-and-author/graph-exploration/versioning-of-graph-changes/add-versioning-graph-property.png new file mode 100644 index 000000000..da67c7ecf Binary files /dev/null and b/docs/explore-and-author/graph-exploration/versioning-of-graph-changes/add-versioning-graph-property.png differ diff --git a/docs/explore-and-author/graph-exploration/versioning-of-graph-changes/create-versioning-graph.png b/docs/explore-and-author/graph-exploration/versioning-of-graph-changes/create-versioning-graph.png new file mode 100644 index 000000000..368216378 Binary files /dev/null and b/docs/explore-and-author/graph-exploration/versioning-of-graph-changes/create-versioning-graph.png differ diff --git a/docs/explore-and-author/graph-exploration/versioning-of-graph-changes/graph-with-versioning-graph.png b/docs/explore-and-author/graph-exploration/versioning-of-graph-changes/graph-with-versioning-graph.png new file mode 100644 index 000000000..d9520ad9b Binary files /dev/null and b/docs/explore-and-author/graph-exploration/versioning-of-graph-changes/graph-with-versioning-graph.png differ diff --git a/docs/explore-and-author/graph-exploration/versioning-of-graph-changes/index.md b/docs/explore-and-author/graph-exploration/versioning-of-graph-changes/index.md index 4eb0e3882..e1ec25b0d 100644 --- a/docs/explore-and-author/graph-exploration/versioning-of-graph-changes/index.md +++ b/docs/explore-and-author/graph-exploration/versioning-of-graph-changes/index.md @@ -9,17 +9,69 @@ tags: This feature keeps track of changes to your Knowledge Graphs by creating change set data based on the user's editing activities. +Changes are not stored in the edited graph itself, but in a separate graph of type `shui:VersioningGraph` — the **Versioning Graph**. +Setting this up is a two step process: you create a Versioning Graph, and then configure the graph you want to track to use it. + !!! info "Supported graph types" - Versioning of graph changes is currently supported for (tracked) graphs of type `void:Dataset` only. + Versioning of graph changes is currently supported for (tracked) graphs of type `void:Dataset` only, + i.e. graphs created as **New Knowledge Graph (void:Dataset)**. - ![](./24-1-GraphTypes.png){ class="bordered" } + On other graph types, the **Versioning Graph** property described in + [Step 2](#2-configure-a-graph-to-use-the-versioning-graph) is not offered. -## Usage +## Setup + +To enable this feature on a specific graph, carry out the following steps in the +**:eccenca-application-explore: Knowledge Graphs** module. + +### 1. Create a Versioning Graph + +Open the graph selection and click **:eccenca-item-add-artefact: Add new graph**. +In the **Add new graph** dialog, choose **New Versioning Graph (shui:VersioningGraph)**. + +![Add new graph dialog with the Versioning Graph option](add-new-graph.png){ class="bordered" } + +Provide a **Graph label** (e.g. `My Changelogs`). +The **Graph URI** is generated from it, by default from your hostname and the label. +You can simply type your own URI into the field, which switches the generation mode to **Custom**. +Alternatively, use the :material-cog-outline: button to pick a different generation template +(**Hostname + provided label**, **Selected graph + provided label**, **UUID** or **Custom**). + +![Create a new graph, providing label and graph URI](create-versioning-graph.png){ class="bordered" } + +Click **Next** to get to the metadata form, then click **Save** to create the graph. + +### 2. Configure a graph to use the Versioning Graph + +Switch to the Knowledge Graph whose changes you want to track and click **Edit** on the **Resource** tab. + +The **Versioning Graph** property is not part of the default graph form, so you have to add it first: +open the **Add data** menu, type `Versioning` in the filter field, +and select **Versioning Graph (beta)**. -If enabled on a graph, all changes using shaped user interfaces will be tracked in the configured Versioning Graph. +![Adding the Versioning Graph property through the Add data menu](add-versioning-graph-property.png){ class="bordered" } -![](./20-10-ActualChangesets.png){ class="bordered" } +The **Versioning Graph (beta)** field is now shown in the **Configuration** section. +Open its dropdown and select the Versioning Graph you created in step 1. + +!!! note + + Only graphs of type `shui:VersioningGraph` are offered here. + If the list is empty, the Versioning Graph from step 1 was not created or does not have the correct type. + +![Selecting the Versioning Graph in the Configuration section](select-versioning-graph.png){ class="bordered" } + +Click **Save**. +The Versioning Graph is now listed in the **Configuration** section, and an additional +**Versioning** tab appears for this graph. + +![The configured graph showing the Versioning Graph and the new Versioning tab](graph-with-versioning-graph.png){ class="bordered" } + +## Usage + +Once enabled on a graph, all changes made through shaped user interfaces are tracked in the configured Versioning Graph. +You can inspect the recorded change sets either on the tracked graph or on the Versioning Graph. !!! info "Versioning limitations" @@ -31,27 +83,23 @@ If enabled on a graph, all changes using shaped user interfaces will be tracked - edits made in the **Properties** tab in the UI - changes executed through **SPARQL UPDATE** queries, including updates from the **Queries catalogue** or external clients +### Change sets of a tracked graph +The **Versioning** tab of a tracked graph lists all change sets recorded for it, with author and timestamp. +Select a change set to see the individual statements it added (`addition`) and removed (`removal`). -## Setup - -To enable this feature on a specific graph you need to setup the following steps. - -??? success "1. Create a Versioning Graph" - - In Exploration, create a new graph and define it as a Versioning Graph. - - ![](./20-10-CreateVersioningGraph.png){ class="bordered" } +![The Versioning tab listing change sets and the details of a selected change set](versioning-tab-changesets.png){ class="bordered" } -??? success "2. Configure a graph to use this Versioning Graph" +### Change sets in the Versioning Graph - In Exploration, edit this graph and add the Versioning Graph property to select the newly created Versioning Graph. +The **Resource** tab of the Versioning Graph itself shows the **Latest Changesets** table, +listing the change sets of all graphs tracked by it, together with the number of added and removed statements. - ![](./20-10-ConfigureVersioningGraph.png){ class="bordered" } +![The Versioning Graph showing the Latest Changesets table](versioning-graph-changesets.png){ class="bordered" } ## Technical Background For each editing activity (→ Save a Form), a ChangeSet resource will be created. This resource has some metadata (user, timestamp, label) as well as links to added and deleted Statements (using RDF Reification). -The details of the used vocabulary are available at the [Changeset Vocabulary](https://vocab.org/changeset/) page. +The details of the used vocabulary are available at the [Changeset Vocabulary](https://vocab.org/changeset/) page. diff --git a/docs/explore-and-author/graph-exploration/versioning-of-graph-changes/select-versioning-graph.png b/docs/explore-and-author/graph-exploration/versioning-of-graph-changes/select-versioning-graph.png new file mode 100644 index 000000000..56cf545cc Binary files /dev/null and b/docs/explore-and-author/graph-exploration/versioning-of-graph-changes/select-versioning-graph.png differ diff --git a/docs/explore-and-author/graph-exploration/versioning-of-graph-changes/versioning-graph-changesets.png b/docs/explore-and-author/graph-exploration/versioning-of-graph-changes/versioning-graph-changesets.png new file mode 100644 index 000000000..48464acf3 Binary files /dev/null and b/docs/explore-and-author/graph-exploration/versioning-of-graph-changes/versioning-graph-changesets.png differ diff --git a/docs/explore-and-author/graph-exploration/versioning-of-graph-changes/versioning-tab-changesets.png b/docs/explore-and-author/graph-exploration/versioning-of-graph-changes/versioning-tab-changesets.png new file mode 100644 index 000000000..0ba7bc6bf Binary files /dev/null and b/docs/explore-and-author/graph-exploration/versioning-of-graph-changes/versioning-tab-changesets.png differ