Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
28 changes: 22 additions & 6 deletions .github/workflows/docs-latest.yml
Original file line number Diff line number Diff line change
Expand Up @@ -2,14 +2,22 @@
#
# SPDX-License-Identifier: Apache-2.0

name: docs-latest
name: docs-publish

on:
push:
branches:
- main
# Fork preview only; remove this branch before merging upstream.
- migration/versioned-publishing
release:
types:
- published
permissions:
contents: write
concurrency:
group: docs-publish
cancel-in-progress: false
jobs:
deploy:
runs-on: ubuntu-latest
Expand All @@ -28,9 +36,17 @@ jobs:
run: |
pip install poetry
poetry install --no-interaction
- name: Configure fake git user to associate commits
- name: Build all documentation versions
run: |
git config --global user.name Docs deploy
git config --global user.email docs-action@shapshifter
- name: Push the main branch under the alias development
run: poetry run mike deploy --push --update-aliases development
if [[ "$GITHUB_EVENT_NAME" == release ]]; then
export ENABLE_PDF_EXPORT=1
fi
SITE_BASE_URL="https://${GITHUB_REPOSITORY_OWNER}.github.io/${GITHUB_REPOSITORY#*/}/" \
bash scripts/build-docs.sh
- name: Publish site to gh-pages
uses: peaceiris/actions-gh-pages@v4
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_branch: gh-pages
publish_dir: ./site
force_orphan: true
2 changes: 1 addition & 1 deletion .github/workflows/docs-pr.yml
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ jobs:
pip install poetry
poetry install --no-interaction
- name: Create local documentation build
run: poetry run mkdocs build
run: bash scripts/build-docs.sh
- name: Archive reports
uses: actions/upload-artifact@v4
with:
Expand Down
40 changes: 0 additions & 40 deletions .github/workflows/docs-release.yml

This file was deleted.

1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@

.idea/
site/
*.code-workspace

# Created by https://www.toptal.com/developers/gitignore/api/windows,python,libreoffice,emacs,microsoftoffice
# Edit at https://www.toptal.com/developers/gitignore?templates=windows,python,libreoffice,emacs,microsoftoffice
Expand Down
8 changes: 7 additions & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ For more information see the projects used to render and upload the documentatio
- [MkDocs](https://www.mkdocs.org/) the rendering engine
- [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) the theme
- [PlantUML for MkDocs](https://pypi.org/project/mkdocs-plantuml/) plugin to render PlantUML diagrams
- [Mike](https://github.com/jimporter/mike) to publish multiple versions
- A static build script to publish each versioned documentation folder under its own URL

Besides the technical features, here are some brief recommendations on using Markdown:

Expand Down Expand Up @@ -51,3 +51,9 @@ Or build it once so you end up with the generated HTML in the `site/` folder:
```
$ poetry run mkdocs build
```

To build all published versions and the root redirect to development, run:

```
$ bash scripts/build-docs.sh
```
10 changes: 8 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,5 +29,11 @@ ordering, and settlement processes.

UFTP and the USEF Framework are developed, maintained and audited by the USEF Foundation.

The directory name of each set of XSDs refer to the corresponding version of USEF Flexibility Trading Protocol Specifications as published
by the [USEF Foundation](https://www.usef.energy/).
XSDs are organized by specification version under `specifications/<version>/xsd/`.
Numbered directories preserve released snapshots; the current draft is under
[`specifications/development/xsd/`](specifications/development/xsd/). Relative
schema includes resolve within each version's XSD directory.

Browsable Markdown and its image assets are stored alongside each version under
`specifications/<version>/docs/`. The version-specific README records the source
tag or commit for each snapshot.
46 changes: 46 additions & 0 deletions VERSIONING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
# Specification Versioning and Publishing

## Version policy

The versioned directory is the source of truth for each specification snapshot:

```text
specifications/
1.0.1/
2.0.0/
3.0.0/
3.1.0/
development/
```

Each directory contains its own documentation and XSDs, plus release artifacts when available. Numbered releases are immutable after publication. `development` is the mutable draft following the latest numbered release; its content must not be presented as a numbered release.

The canonical documentation paths are `/1.0.1/`, `/2.0.0/`, `/3.0.0/`, `/3.1.0/`, and `/development/`. The site root redirects to `/development/`. The version selector links between versions.

All editable specification Markdown and images belong under `specifications/<version>/docs/`; the development source is `specifications/development/docs/`. Keep XSD includes and Markdown image references within their version directory. Do not maintain a duplicate root `docs/` or `xsd/` source.

## Publishing

The `docs-publish` workflow builds each versioned documentation tree as a static site and publishes the complete site to the `gh-pages` branch. `scripts/build-docs.sh` writes the sites to their matching version paths and generates the root `versions.json` consumed by Material's native version selector. The root `index.html` redirects to the development site.

The workflow publishes on pushes to `main` and published releases. A fork-only preview trigger for `migration/versioned-publishing` is currently retained; remove that temporary trigger before merging the workflow upstream.

For a release, copy the approved development documentation, images, and XSDs into a new numbered directory, add available release artifacts, and record their provenance. Never change the content behind an already published numbered path. Verify relative references and the rendered site before publishing.

## Historical provenance

The `V3.0.0` and `V3.1.0` tags are authoritative for their XSDs and release artifacts. Those tags predate or do not contain the Markdown conversion, so the Markdown snapshots use the nearest reviewed documentation commits. The v1.0.1 and v2.0.0 XSDs are reconstructed from their historical commits.

| Version or artifact | Source | Preserved content |
| --- | --- | --- |
| v1.0.1 XSDs | [Commit `e12a4f9`](https://github.com/shapeshifter/shapeshifter-specification/commit/e12a4f9293075ee369b62c7bb0e3cf08ea57b450) | Complete v1.0.1 XSD set from the historical `V1.01/` directory; the README was added later. |
| v2.0.0 XSDs | [Commit `cc7a362`](https://github.com/shapeshifter/shapeshifter-specification/commit/cc7a362d86ac693e130091a5c9376bf2d848ee2c) | Complete v2.0.0 XSD set. |
| v3.0.0 XSDs and release artifacts | [`V3.0.0`, commit `2b2f8f3`](https://github.com/shapeshifter/shapeshifter-specification/tree/2b2f8f394eeab7a47f14e31593bd6634f37621bc) | Tagged XSDs and release documents. The PDF and Word files were introduced in [commit `7068732`](https://github.com/shapeshifter/shapeshifter-specification/commit/7068732d31d059e13e8dafd1cc5d5e89866d9e8b). |
| v3.0.0 Markdown and images | [Commit `24da5e2`](https://github.com/shapeshifter/shapeshifter-specification/commit/24da5e2d8443108a23aaceca8a8215330fb0c65b) | First complete, reviewed Markdown conversion and image assets (2023-02-20). |
| v3.1.0 XSDs and release artifacts | [`V3.1.0`, commit `3078c25`](https://github.com/shapeshifter/shapeshifter-specification/tree/3078c25a067c641dacd38ae8bde1ba4b4fe48413) | Tagged XSDs and release documents. |
| v3.1.0 Markdown and images | [Commit `92ef001`](https://github.com/shapeshifter/shapeshifter-specification/commit/92ef001b79c6312403e4e463bcbc827c14f5a389) | Documentation state immediately preceding the v3.1.0 release (2025-04-30). |
| Development Markdown and images | [Commit `38b40f3`](https://github.com/shapeshifter/shapeshifter-specification/commit/38b40f36316395d169b446cd156a567dd117ae36) | Mutable documentation immediately before it was moved under `specifications/development/`. |
| Development XSDs | [Commit `f799cac`](https://github.com/shapeshifter/shapeshifter-specification/commit/f799cac9867c473fc4a4d18a0db046d577bada0c) | Mutable XSDs immediately before they were moved under `specifications/development/`. |
| Markdown specification and publishing | [PR #67](https://github.com/shapeshifter/shapeshifter-specification/pull/67), later refined | MkDocs, Material for MkDocs, and GitHub Actions publishing history. |

Preserve these commit and tag references even for historical versions that were not published as GitHub Releases. Migration-added READMEs and shared `docs/versions.md` indexes are metadata rather than part of the historical source snapshots.
4 changes: 4 additions & 0 deletions mkdocs-archive.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
INHERIT: mkdocs.yml

nav:
- Shapeshifter Specification: index.md
9 changes: 4 additions & 5 deletions mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,10 @@

site_name: Shapeshifter specification
repo_url: https://github.com/shapeshifter/shapeshifter-specification
site_url: http://localhost:8000/
site_url: !ENV [SITE_URL, "http://localhost:8000/"]
site_author: "Contributors to the Shapeshifter project"
copyright: "Copyright 2020-2025 Contributors to the Shapeshifter project"
docs_dir: docs/
docs_dir: !ENV [DOCS_DIR, "specifications/development/docs/"]
theme:
name: material
features:
Expand All @@ -17,8 +17,7 @@ theme:
- navigation.top # back-to-top button when scrolling back up
logo: assets/images/shapeshifter-icon-white.svg
favicon: assets/images/shapeshifter-icon-color.svg
# TODO: enable this feature once versioned releases have been published
# custom_dir: overrides # to add the warning bar for the latest version
custom_dir: overrides
extra:
version:
default: development
Expand All @@ -43,7 +42,6 @@ plugins:
width: 50vw
skip_classes:
- no-lightbox
- mike
- plantuml-colocator
markdown_extensions:
- admonition # for Recommended Practice blocks
Expand Down Expand Up @@ -117,3 +115,4 @@ nav:
- Flex reservation mechanism: appendix/flex-reservation-mechanism.md
- Message transport mechanism: appendix/message-transport-mechanism.md
- Bibliography: appendix/bibliography.md
- Versioned specification files: versions.md
39 changes: 1 addition & 38 deletions poetry.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

1 change: 0 additions & 1 deletion pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,6 @@ packages = [{include = "shapeshifter_specification"}]
[tool.poetry.dependencies]
python = "^3.10"
mkdocs-material = "^9.6.12"
mike = "^1.1.2"
mkdocs-glightbox = "^0.4.0"
setuptools = "^70.3.0"
weasyprint = "^65.1"
Expand Down
84 changes: 84 additions & 0 deletions scripts/build-docs.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,84 @@
#!/usr/bin/env bash
# Copyright Contributors to the Shapeshifter project
# SPDX-License-Identifier: Apache-2.0

set -euo pipefail

site_dir="${1:-site}"
site_base_url="${SITE_BASE_URL:-http://localhost:8000/}"
tmp_dir="$(mktemp -d)"
trap 'rm -rf "$tmp_dir"' EXIT
versions=(development)

versioned_dirs=()
for docs_dir in specifications/[0-9]*/docs; do
[[ -d "$docs_dir" ]] || continue
versioned_dirs+=("$(basename "$(dirname "$docs_dir")")")
done

while IFS= read -r version; do
[[ -n "$version" ]] && versions+=("$version")
done < <(printf '%s\n' "${versioned_dirs[@]}" | python3 -c 'import sys; versions = [line.strip() for line in sys.stdin if line.strip()]; versions.sort(key=lambda version: tuple(int(part) for part in version.split(".")), reverse=True); print("\n".join(versions))')

mkdir -p "$site_dir"

for version in "${versions[@]}"; do
docs_dir="specifications/$version/docs"
test -d "$docs_dir"
build_docs_dir="$docs_dir"
config_file="mkdocs.yml"
if [[ "$version" == "1.0.1" || "$version" == "2.0.0" ]]; then
config_file="mkdocs-archive.yml"
build_docs_dir="$tmp_dir/$version/docs"
mkdir -p "$build_docs_dir/xsd"
cp -R "$docs_dir/." "$build_docs_dir/"
cp -R "specifications/$version/xsd/." "$build_docs_dir/xsd/"
fi
SITE_URL="${site_base_url}${version}/" \
DOCS_DIR="$build_docs_dir" \
poetry run mkdocs build --strict --config-file "$config_file" --site-dir "$site_dir/$version"
done

printf '%s\n' "${versions[@]}" | python3 -c '
import json
import sys

versions = [line.strip() for line in sys.stdin if line.strip()]
json.dump(
[
{
"version": version,
"title": "Development (unreleased)" if version == "development" else version,
"aliases": [],
}
for version in versions
],
sys.stdout,
indent=2,
)
sys.stdout.write("\n")
' > "$site_dir/versions.json"

{
cat <<'HTML'
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta http-equiv="refresh" content="0; url=./development/">
<title>Redirecting to the development specification</title>
</head>
<body>
<main>
<h1>Shapeshifter specification</h1>
<p>Redirecting to the development specification.</p>
<p>If you are not redirected, continue to
<a href="./development/">Development (unreleased)</a>.
</p>
</main>
</body>
</html>
HTML
} > "$site_dir/index.html"
touch "$site_dir/.nojekyll"
7 changes: 7 additions & 0 deletions specifications/1.0.1/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
# Shapeshifter Specification 1.0.1

This directory preserves the v1.0.1 XSD snapshot from the historical `V1.01/` directory.

Source commit: [`e12a4f9293075ee369b62c7bb0e3cf08ea57b450`](https://github.com/shapeshifter/shapeshifter-specification/commit/e12a4f9293075ee369b62c7bb0e3cf08ea57b450)

The original XSD filenames and schema references are retained. Do not edit this snapshot; make specification changes in the development sources and publish them as a new version.
Loading
Loading