Add framework for "proclamation"-based changelog fragments.

Author: rpavlik

.proclamation.json

@@ -0,0 +1,31 @@
+{
+    "#": "This is a config file for proclamation, the changelog combiner: https://gitlab.com/ryanpavlik/proclamation",
+    "projects": [
+        {
+            "project_name": "OpenXR SDK",
+            "news_filename": "CHANGELOG.SDK.md",
+            "template": "changes/template.md",
+            "sections": {
+                "Registry": {
+                    "directory": "changes/registry"
+                },
+                "SDK": {
+                    "directory": "changes/sdk"
+                }
+            }
+        },
+        {
+            "project_name": "OpenXR Specification",
+            "news_filename": "CHANGELOG.Docs.md",
+            "template": "changes/template.md",
+            "sections": {
+                "Registry": {
+                    "directory": "changes/registry"
+                },
+                "Specification": {
+                    "directory": "changes/specification"
+                }
+            }
+        }
+    ]
+}

changes/README.md

@@ -0,0 +1,71 @@
+# Changelog Fragments
+
+The OpenXR specification editor uses the "proclamation" package to assemble
+changelogs for each public release, which incorporate fragments of changelog
+text added by the author of a change in one of these directories.
+
+If you want to preview the changelog or perform a release, you can run a command
+like the following to install it locally:
+
+```sh
+pip3 install proclamation
+```
+
+See <https://gitlab.com/ryanpavlik/proclamation> for more details on *proclamation*.
+
+## Fragments
+
+Each change should add a changelog fragment file, whose contents are
+Markdown-formatted text describing the change briefly. Reference metadata will
+be used to automatically add links to associated issues/merge requests/pull
+requests, so no need to add these in your fragment text.
+
+## References
+
+The changelog fragment system revolves around "references" - these are issue
+reports, public pull requests, or private pull requests associated with a
+change. Each fragment must have at least one of these, which forms the main part
+of the filename. If applicable, additional can be added within the file - see
+below for details.
+
+The format of references for internal issues/MRs is:
+
+```txt
+<ref_type>.<number>.gl
+```
+
+where
+
+- `ref_type` is "issue" or "mr"
+- `number` is the issue or MR number
+- `gl` refers to internal GitLab.
+
+The format of references for public (GitHub) issues/pull requests is:
+
+```txt
+<ref_type>.<number>.gh.<repo_name>
+```
+
+where
+
+- `ref_type` is "issue" or "pr"
+- `number` is the issue or PR number
+- `gh` refers to public GitHub
+- `repo_name` is the repository name: one of "OpenXR-Docs", "OpenXR-SDK-Source",
+  etc.
+
+Your changelog fragment filename is simply the "main" reference with the `.md`
+extension added.
+
+To specify additional references in a file, prefix the contents of the changelog
+fragment with a block delimited above and below by `---`, with one reference on
+each line. (This can be seen as a very minimal subset of "YAML Front Matter", if
+you're familiar with that concept.) For example:
+
+```md
+---
+- issue.35.gl
+- mr.93.gl
+---
+Your changelog fragment text goes here.
+```

changes/registry/README.md

@@ -0,0 +1,8 @@
+# Registry Changes
+
+Please create changelog fragments in this directory for changes that affect the
+`xr.xml` registry. These fragments will be included in both the docs and SDK
+changelogs.
+
+See the README.md in the parent directory for information on the format and
+naming of changelog fragment files.

changes/sdk/README.md

@@ -0,0 +1,8 @@
+# SDK Changes
+
+Please create changelog fragments in this directory for changes that affect
+SDK code only. These fragments will only be applied to the
+SDK changelog.
+
+See the README.md in the parent directory for information on the format and
+naming of changelog fragment files.

changes/specification/README.md

@@ -0,0 +1,8 @@
+# Specification Changes
+
+Please create changelog fragments in this directory for changes that affect
+specification text only. These fragments will only be applied to the
+specification changelog.
+
+See the README.md in the parent directory for information on the format and
+naming of changelog fragment files.

changes/template.md

@@ -0,0 +1,42 @@
+{% macro format_ref(ref) -%}
+{%- set service = ref.service_params[0] -%}
+{%- if ref.ref_service == "gh" -%}
+    {%- set project = ref.service_params[1] %}
+    {%- set project_base = "https://github.com/KhronosGroup/" + project %}
+    {%- set link_text %}{{ project }}/#{{ ref.number }}{% endset %}
+    {%- if ref.item_type == "issue" -%}
+        {%- set subdir = "issues" %}
+    {%- else -%}
+        {%- set subdir = "pull" %}
+    {%- endif -%}
+{%- else -%}
+    {%- set project_base = "https://gitlab.khronos.org/openxr/openxr" %}
+    {%- if ref.item_type == "issue" -%}
+        {%- set link_text %}internal issue {{ ref.number }}{% endset %}
+        {%- set subdir = "issues" %}
+    {%- else -%}
+        {%- set link_text %}internal MR {{ ref.number }}{% endset %}
+        {%- set subdir = "merge_requests" %}
+    {%- endif -%}
+{%- endif -%}
+[{{ link_text }}]({{project_base}}/{{subdir}}/{{ ref.number }})
+{%- endmacro -%}
+{% macro format_refs(refs) -%}
+    {%- if (refs | length) > 0 -%}
+        {%- set comma = joiner(", ") -%}
+        {% for ref in refs -%}
+            {{comma()}}{{format_ref(ref)}}
+        {%- endfor %}
+    {%- endif %}
+{%- endmacro -%}
+{% block title %}## {{ project_name }} {{project_version}} ({{date}}){% endblock %}
+
+{% for section in sections %}
+- {{ section.name }}
+{%- for chunk in section.chunks %}{% set rawtext %}{{ chunk.text }} ({{format_refs(chunk.refs)}}){% endset %}
+  - {{ rawtext | wordwrap | indent }}
+{%- else %}
+  - No significant changes
+{% endfor -%}
+{% endfor %}
+