Policy documents for services run by New Vector
  • Python 83.2%
  • Shell 16.8%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2023-07-21 10:54:53 +01:00
data Template values for new vector 2019-09-23 14:10:48 +01:00
docs Update README.md 2023-07-21 10:54:53 +01:00
scripts Modifications to the script to generate a duplicate of the most recent file with a filename that only includes the major version number - in order to generate files compatible with the IS and IM t's and c's acceptance mechanisms 2019-09-24 15:20:22 +01:00
vector-im-policies/docs/ems Denise/chat tos 2020-07-13 20:26:00 +00:00
.gitignore Script to generate versioned instances of policy docs from the git commit history 2019-09-19 11:49:43 +01:00
package-lock.json Bump markdown-it from 9.0.1 to 12.3.2 2022-01-12 22:53:05 +00:00
package.json Bump markdown-it from 9.0.1 to 12.3.2 2022-01-12 22:53:05 +00:00
README.md Update README.md 2021-04-23 15:26:44 +00:00

policies

Policy documents for services run by New Vector Ltd (trading as Element)

Versioning

Documents are versioned using semver:

  • Major bump - significant change requiring subjects' specific re-acknowledgement/acceptance
  • Minor bump - notable change in text, but not something that would require subjects' specific attention
  • Patch bump - fixing a typo

Versioning metadata is stored in the top of the policy doc - each doc has a metadata segment inspired by gatsby that looks something like:

---
title: Document Title
version 1.0.0
---

Identity servers and integration managers manage tracking subjects' 'accepted terms' by tracking the URL representing those terms - it is therefore imperative that any generated links to docs include the major version and only the major version (e.g. https://example.com/document-title-1) so that only a change in the major version triggers the 're-optin' flow.

Versioning Tooling

/scripts/versions.py will mine the github commit history for a given document and output a file representing the most recent state of that document for each numbered version. versions.py doesn't handle templating or markdown->html.

To apply this to all of the policy docs:

for FILE in $(find docs -name '*.md' | grep -v README.md); do ./scripts/versions.py $FILE; done;

Templating

Most of these files are templated using {{ variable_name }}, to be digested by ansible/jinja2 somewhere down the line for deployment to different instances. To apply Element data to the templates, you can use jinja2-cli:

$ jinja2 <filename> ~/path/to/new_vector.json --format=json

Turning the Markdown into HTML

This section needs some work. You can generate a full set of html docs from the .md source using:

npm run build

This will create a /build directory with a folder structure mirroring /docs, with a .html file in place of every .md file.

At the moment this does not play nicely with versions.py, and it is questionable whether it is a good idea at all to have a build system as part of the docs repo when, in some instances at least (such as the matrix.org website) what's needed is a markdown file that gatsby will then ingest.