Skip to content

Policy documents for services run by New Vector

Notifications You must be signed in to change notification settings

InezMc/policies

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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.

About

Policy documents for services run by New Vector

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • Python 83.2%
  • Shell 16.8%