imio.emailkit

Contributing

imio.emailkit is GPLv2 and developed in the open. Node.js is deliberately not part of make install — you only need it if you are going to build templates.

Prerequisites

Set up

git clone git@github.com:IMIO/imio.emailkit.git
cd imio.emailkit
make install

The targets that matter

  • Name
    make install
    Description

    Install Plone and dependencies. make build is an alias. Node is not involved.

  • Name
    make start
    Description

    Start a Plone instance on localhost:8080. make create-site makes one from scratch; PROFILE=base make create-site for a site with the opt-out.

  • Name
    make check
    Description

    Format, then lint, to Plone standards. make lint and make format are the halves.

  • Name
    make test
    Description

    The whole suite. make test-coverage for coverage.

  • Name
    make build-emails
    Description

    Compile emails/ into the package. Commit the resulting .pt files.

  • Name
    make check-emails
    Description

    The authoring lint, then the staleness gate. This is what CI runs.

  • Name
    make preview-emails
    Description

    Render the committed templates with the committed fixtures and serve them.

  • Name
    make update-golden
    Description

    Regenerate the golden snapshots. Deliberate, never automatic.

  • Name
    make i18n
    Description
    Update the translation catalogs.
  • Name
    make recipe-test
    Description

    Run imio.recipe.emailkit's own suite. make buildout-test is the full buildout-then-compile acceptance run.

Run make help for the complete list.

Before you open a pull request

  1. make check — formatting and lint.
  2. make test — the suite.
  3. make check-emails — if you touched anything under emails/ or kit/. A stale .pt fails CI.

If you changed a template's output on purpose, make update-golden and commit the new snapshots in the same change as the template.

Adding a template

bin/compile-emails --new my_template

That scaffolds the four files a template needs: the .vue skeleton, a fixture, a golden placeholder and a registration stub to paste. Read Authoring rules first — the failures it prevents all produce a successful build.

Scaffolding with plonecli

The package provides <!-- extra stuff goes here --> markers compatible with plonecli and bobtemplates.plone.

make add <template_name>

Where the reasoning lives

This site documents what the package does. Two files in the repository document why, and they are the authority when the two disagree:

  • Name
    SPEC.md
    Description

    The specification: goals, non-goals, the architecture, the phasing, and what was explicitly rejected. Read it.

  • Name
    docs/DECISIONS.md
    Description

    The decision record — every measured finding, every reverted attempt, every "this looked like it worked and did not". Read it.

There is also a SKILL.md covering the authoring conventions for AI-assisted work, which is how much of the template work here is done.

Editing this site

The documentation is a Next.js app under docs/site/. Adding a page is two steps, and the "Edit this page" link at the bottom of any page takes you straight to its source. See docs/site/README.md.

Credits

Built on Maizzle. Scaffolded from Cookieplone following imio.reportproblem's layout.