Go to file
Lukas Wagner 4865711339 notify: add template rendering
This commit adds template rendering to the `proxmox-notify` crate, based
on the `handlebars` crate.

Title and body of a notification are rendered using any `properties`
passed along with the notification. There are also a few helpers,
allowing to render tables from `serde_json::Value`.

'Value' renderers. These can also be used in table cells using the
'renderer' property in a table schema:
  - {{human-bytes val}}
    Render bytes with human-readable units (base 2)
  - {{duration val}}
    Render a duration (based on seconds)
  - {{timestamp val}}
    Render a unix-epoch (based on seconds)

There are also a few 'block-level' helpers.
  - {{table val}}
    Render a table from given val (containing a schema for the columns,
    as well as the table data)
  - {{object val}}
    Render a value as a pretty-printed json
  - {{heading_1 val}}
    Render a top-level heading
  - {{heading_2 val}}
    Render a not-so-top-level heading
  - {{verbatim val}} or {{/verbatim}}<content>{{#verbatim}}
    Do not reflow text. NOP for plain text, but for HTML output the text
    will be contained in a <pre> with a regular font.
  - {{verbatim-monospaced val}} or
      {{/verbatim-monospaced}}<content>{{#verbatim-monospaced}}
    Do not reflow text. NOP for plain text, but for HTML output the text
    will be contained in a <pre> with a monospaced font.

Signed-off-by: Lukas Wagner <l.wagner@proxmox.com>
2023-07-24 10:25:48 +02:00
.cargo cargo: switch to use packaged crates by default 2020-01-03 09:39:52 +01:00
proxmox-api-macro update d/copyright files to debian copyright-format 1.0 2023-05-23 13:02:39 +02:00
proxmox-apt proxmox-apt: bump to 0.10.3-1 2023-07-05 12:38:08 +02:00
proxmox-async add some missing d/source/format files 2023-06-02 08:44:50 +02:00
proxmox-auth-api auth-api: fixup examples 2023-07-10 09:06:35 +02:00
proxmox-borrow update d/copyright files to debian copyright-format 1.0 2023-05-23 13:02:39 +02:00
proxmox-compression bump proxmox-compression to 0.2.1-1 2023-06-15 11:01:19 +02:00
proxmox-http bump proxmox-http to 0.9.0-1 2023-05-23 13:02:51 +02:00
proxmox-human-byte bump proxmox-human-byte to 0.1.0-1 2023-06-26 13:37:29 +02:00
proxmox-io update d/copyright files to debian copyright-format 1.0 2023-05-23 13:02:39 +02:00
proxmox-lang update d/copyright files to debian copyright-format 1.0 2023-05-23 13:02:39 +02:00
proxmox-ldap bump proxmox-ldap to 0.2.0-1 2023-06-26 14:22:50 +02:00
proxmox-login cargo fmt 2023-06-23 11:50:39 +02:00
proxmox-metrics bump proxmox-metrics to 0.3.0-1 2023-05-23 13:02:51 +02:00
proxmox-notify notify: add template rendering 2023-07-24 10:25:48 +02:00
proxmox-openid cargo fmt 2023-06-23 11:50:39 +02:00
proxmox-rest-server proxmox-rest-server: bump to 0.4.1-1 2023-06-27 12:44:52 +02:00
proxmox-router update d/copyright files to debian copyright-format 1.0 2023-05-23 13:02:39 +02:00
proxmox-schema schema: add schema/format for comments 2023-07-24 10:25:22 +02:00
proxmox-section-config section-config: derive Clone for SectionConfigData 2023-07-24 10:25:20 +02:00
proxmox-serde update d/copyright files to debian copyright-format 1.0 2023-05-23 13:02:39 +02:00
proxmox-shared-memory bump proxmox-shared-memory to 0.3.0-1 2023-05-23 13:02:51 +02:00
proxmox-sortable-macro update d/copyright files to debian copyright-format 1.0 2023-05-23 13:02:39 +02:00
proxmox-subscription bump proxmox-subscription to 0.4.0-1 2023-05-23 13:02:51 +02:00
proxmox-sys cargo fmt 2023-06-23 11:50:39 +02:00
proxmox-tfa bump proxmox-tfa to 4.0.4 2023-07-05 10:46:12 +02:00
proxmox-time update d/copyright files to debian copyright-format 1.0 2023-05-23 13:02:39 +02:00
proxmox-uuid update d/copyright files to debian copyright-format 1.0 2023-05-23 13:02:39 +02:00
.gitignore git: ignore top level *-deb make target files 2022-08-26 12:18:44 +02:00
build.sh build.sh: split overly long line 2023-06-03 16:48:10 +02:00
bump.sh add bump.sh 2022-12-07 10:36:27 +01:00
Cargo.toml notify: add template rendering 2023-07-24 10:25:48 +02:00
Makefile buildsys: also cleanup *.build files for convenience 2023-06-04 18:27:46 +02:00
README.rst update/extend README.rst 2022-12-12 11:05:30 +01:00
rustfmt.toml bump edition in rustfmt.toml 2022-10-13 15:00:28 +02:00

Local cargo config
==================

This repository ships with a ``.cargo/config`` that replaces the crates.io
registry with packaged crates located in ``/usr/share/cargo/registry``.

A similar config is also applied building with dh_cargo. Cargo.lock needs to be
deleted when switching between packaged crates and crates.io, since the
checksums are not compatible.

To reference new dependencies (or updated versions) that are not yet packaged,
the dependency needs to point directly to a path or git source.

Steps for Releases
==================

- Run ./bump.sh <CRATE> [patch|minor|major|<VERSION>]
-- Fill out changelog
-- Confirm bump commit
- Build packages with `make deb`.
-- Don't forget to commit updated d/control!

Adding Crates
=============

1) At the top level:
  - Generate the crate: ``cargo new --lib the-name``
  - Sort the crate into ``Cargo.toml``'s ``workspace.members``

2) In the new crate's ``Cargo.toml``:
  - In ``[package]`` set:
      authors.workspace = true
      license.workspace = true
      edition.workspace = true
      exclude.workspace = true
  - Add a meaningful ``description``
  - Copy ``debian/copyright`` and ``debian/debcargo.toml`` from another subcrate.

Adding a new Dependency
=======================

1) At the top level:
  - Add it to ``[workspace.dependencies]`` specifying the version and any
    features that should be enabled throughout the workspace

2) In each member's ``Cargo.toml``:
  - Add it to the desired dependencies section with ``workspace = true`` and no
    version specified.
  - If this member requires additional features, add only the extra features to
    the member dependency.

Updating a Dependency's Version
===============================

1) At the top level:
  - Bump the version in ``[workspace.dependencies]`` as desired.
  - Check for deprecations or breakage throughout the workspace.

Notes on Workspace Inheritance
==============================

Common metadata (like authors, license, ..) are inherited throughout the
workspace. If new fields are added that are identical for all crates, they
should be defined in the top-level ``Cargo.toml`` file's
``[workspace.package]`` section, and inherited in all members explicitly by
setting ``FIELD.workspace = true`` in the member's ``[package]`` section.

Dependency information is also inherited throughout the workspace, allowing a
single dependency specification in the top-level Cargo.toml file to be used by
all members.

Some restrictions apply:
- features can only be added in members, never removed (this includes
  ``default_features = false``!)
 - the base feature set at the workspace level should be the minimum (possibly
   empty!) set required by all members
- workspace dependency specifications cannot include ``optional``
 - if needed, the ``optional`` flag needs to be set at the member level when
   using a workspace dependency