From 9f3df1950fe04f8df1f938f2148274dee29396b7 Mon Sep 17 00:00:00 2001 From: Will Date: Tue, 2 Feb 2021 20:47:18 -0800 Subject: [PATCH] Add changelog page and templates --- content/changelog.md | 47 ++++++++ .../changelog/changelog-changes.html | 108 ++++++++++++++++++ .../changelog/changelog-description.html | 24 ++++ 3 files changed, 179 insertions(+) create mode 100644 content/changelog.md create mode 100644 layouts/shortcodes/changelog/changelog-changes.html create mode 100644 layouts/shortcodes/changelog/changelog-description.html diff --git a/content/changelog.md b/content/changelog.md new file mode 100644 index 00000000..41b0987e --- /dev/null +++ b/content/changelog.md @@ -0,0 +1,47 @@ +--- +title: Changelog +type: docs +weight: 1000 +--- + +{{% changelog/changelog-description %}} + +{{% changelog/changelog-changes %}} + +

Historical versions

+ +Before version 1.1, versioning was applied at the level of individual API specifications. This section includes links to these versions of the APIs. + +* **Client-Server API** + - [r0.6.1](https://matrix.org/docs/spec/client_server/r0.6.1.html) + - [r0.6.0](https://matrix.org/docs/spec/client_server/r0.6.0.html) + - [r0.5.0](https://matrix.org/docs/spec/client_server/r0.5.0.html) + - [r0.4.0](https://matrix.org/docs/spec/client_server/r0.4.0.html) + - [r0.3.0](https://matrix.org/docs/spec/client_server/r0.3.0.html) + - [r0.2.0](https://matrix.org/docs/spec/client_server/r0.2.0.html) + - [r0.1.0](https://matrix.org/docs/spec/client_server/r0.1.0.html) + - [r0.0.1](https://matrix.org/docs/spec/r0.0.1/client_server.html) + - [r0.0.0](https://matrix.org/docs/spec/r0.0.0/client_server.html) + - [Legacy](https://matrix.org/docs/spec/legacy/#client-server-api): + The last draft before the spec was formally released in version + r0.0.0. + +* **Server-Server API** + - [r0.1.4](https://matrix.org/docs/spec/server_server/r0.1.4.html) + - [r0.1.3](https://matrix.org/docs/spec/server_server/r0.1.3.html) + - [r0.1.2](https://matrix.org/docs/spec/server_server/r0.1.2.html) + - [r0.1.1](https://matrix.org/docs/spec/server_server/r0.1.1.html) + - [r0.1.0](https://matrix.org/docs/spec/server_server/r0.1.0.html) + +* **Application Service API** + - [r0.1.1](https://matrix.org/docs/spec/application_service/r0.1.1.html) + - [r0.1.0](https://matrix.org/docs/spec/application_service/r0.1.0.html) + +* **Identity Service API** + - [r0.3.0](https://matrix.org/docs/spec/identity_service/r0.3.0.html) + - [r0.2.1](https://matrix.org/docs/spec/identity_service/r0.2.1.html) + - [r0.2.0](https://matrix.org/docs/spec/identity_service/r0.2.0.html) + - [r0.1.0](https://matrix.org/docs/spec/identity_service/r0.1.0.html) + +* **Push Gateway API** + - [r0.1.0](https://matrix.org/docs/spec/push_gateway/r0.1.0.html) diff --git a/layouts/shortcodes/changelog/changelog-changes.html b/layouts/shortcodes/changelog/changelog-changes.html new file mode 100644 index 00000000..a7d801ac --- /dev/null +++ b/layouts/shortcodes/changelog/changelog-changes.html @@ -0,0 +1,108 @@ +{{/* + + This template is used to render the set of changes in the changelog page. + + If this version of the spec is unstable, it expects to find a + "changelog/newsfragments" directory containing all unreleased changes, + and renders them all. + + Otherwise it expects to find a "changelog/releases" directory, under which + is one or more directories whose name is a patch number, like "0", "1", and so on. + + It renders each of these subdirectories as a separate patch, including + a table containing basic info about that patch and the set of changes in it. + +*/}} + +{{ $path := path.Join "changelogs" }} + +{{ $status := .Site.Params.version.status }} + +{{ if eq $status "unstable" }} +

Changes since last release

+ {{ partial "render-api-changes" (dict "title" "Client-Server API" "id" "client-server-api" "path" (path.Join $path "client_server")) }} + {{ partial "render-api-changes" (dict "title" "Server-Server API" "id" "server-server-api" "path" (path.Join $path "server_server")) }} + {{ partial "render-api-changes" (dict "title" "Application Service API" "id" "application-service-api" "path" (path.Join $path "application_service")) }} + {{ partial "render-api-changes" (dict "title" "Identity Service API" "id" "identity-service-api" "path" (path.Join $path "identity_service")) }} + {{ partial "render-api-changes" (dict "title" "Push Gateway API" "id" "push-gateway-api" "path" (path.Join $path "push_gateway")) }} +{{ else }} + {{ $releases_path := path.Join $path "releases" }} + {{ $major_version := .Site.Params.version.major_version }} + {{ $minor_version := .Site.Params.version.minor_version }} + {{ $releases := partial "reverse-slice" (readDir $releases_path) }} + {{ range $releases }} + {{ if .IsDir }} +

Version {{ $major_version }}.{{ $minor_version }}.{{ .Name }}

+ {{ $release_path := path.Join $releases_path .Name}} + {{ $release_info := readFile (path.Join $release_path "release.yaml") | transform.Unmarshal }} + + + +
Git commithttps://github.com/matrix-org/matrix-doc/tree/{{ $release_info.tag }}
Release date{{ $release_info.date }}
+ {{ partial "render-api-changes" (dict "title" "Client-Server API" "id" "client-server-api" "path" (path.Join $release_path "client_server")) }} + {{ partial "render-api-changes" (dict "title" "Server-Server API" "id" "server-server-api" "path" (path.Join $release_path "server_server")) }} + {{ partial "render-api-changes" (dict "title" "Application Service API" "id" "application-service-api" "path" (path.Join $release_path "application_service")) }} + {{ partial "render-api-changes" (dict "title" "Identity Service API" "id" "identity-service-api" "path" (path.Join $release_path "identity_service")) }} + {{ partial "render-api-changes" (dict "title" "Push Gateway API" "id" "push-gateway-api" "path" (path.Join $release_path "push_gateway")) }} + {{ end }} + {{ end }} +{{ end }} + +{{ define "partials/reverse-slice" }} +{{ $sliceOriginal := . }} +{{ $len := len $sliceOriginal }} +{{ $sliceReversed := slice }} +{{ range seq $len }} + {{ $sliceReversed = $sliceReversed | append (index $sliceOriginal (sub $len .)) }} +{{ end }} +{{ return $sliceReversed }} +{{ end }} + +{{ define "partials/render-api-changes" }} +

{{ .title }}

+ {{ $api_path := .path }} + {{ $config_file := path.Join $api_path "pyproject.toml" }} + {{ $config := readFile $config_file | transform.Unmarshal }} + {{ $news_path := path.Join $api_path "newsfragments" }} + {{ partial "render-newsfragments" (dict "config" $config "news_path" $news_path )}} +{{ end }} + +{{ define "partials/render-newsfragments" }} +{{ $config := .config }} +{{ $news_path := .news_path }} + +{{ $types := dict }} +{{ range $config.tool.towncrier.type }} + {{ $types = merge $types (dict .directory (slice)) }} +{{ end }} + +{{ range (readDir $news_path) }} + + {{ $pieces := split .Name "." }} + + {{ $ticket := index $pieces 0 }} + {{ $description := readFile (path.Join $news_path .Name ) }} + {{ $change_info := (dict "ticket" $ticket "description" $description )}} + + {{ $type := index $pieces 1 }} + {{ $instances := index $types $type }} + {{ $instances = $instances | append $change_info }} + {{ $types = merge $types (dict $type $instances) }} + +{{ end }} + + +{{ end }} diff --git a/layouts/shortcodes/changelog/changelog-description.html b/layouts/shortcodes/changelog/changelog-description.html new file mode 100644 index 00000000..0c5c5c50 --- /dev/null +++ b/layouts/shortcodes/changelog/changelog-description.html @@ -0,0 +1,24 @@ +{{/* + + This template is used to provide different content for the unstable spec + version and for a versioned release. + +*/}} + +{{ $status := .Site.Params.version.status }} + +{{ if eq $status "unstable"}} +

This is the unstable version of the Matrix specification.

+

This changelog lists changes made since the last release of the specification.

+{{ else }} +

This is version {{ .Site.Params.version.major_version}}.{{ .Site.Params.version.minor_version}}.{{ .Site.Params.version.patch_version}} of the Matrix specification.

+ + +

Versions for the Matrix specification follow a three-part format like `major.minor.patch`.

+ +* `major` version increments are reserved for very significant changes. +* `minor` version increments may signal additions, deprecations, or breaking changes. +* `patch` version increments are for clarifications to the specification and don't affect implementations. + +

This changelog lists changes made in the initial {{ .Site.Params.version.major_version}}.{{ .Site.Params.version.minor_version}} release and any subsequent patch releases to that version.

+{{ end }}