Change to MiniJinja

[pando85]

Is there an existing issue or pull request for this?

• I have searched the existing issues and pull requests

Feature description

I think that changing the template engine to MiniJinja will be a notable improvement in templates.

Desired solution

Replace Tera with MiniJinja

Alternatives considered

Keep using Tera.

Additional context

No response

[welcome]

Thanks for opening your first issue at git-cliff! Be sure to follow the issue template! ⛰️

[alerque]

Why? Personally the use of Tera was one of the things that stood out in git cliff's favor when I was first considering using it. What is the perceived problem with Tera and why would Minijinja be better?

[pando85]

There are multiple points about user experience which I think are the most important.

MiniJinja works better in a sense that overpass all the limitations that Tera V2 is trying to fix. For example, Tera doesn't support parenthesis for operations priority. These limitations are recognized by his own author.

Also, MiniJinja syntax is widely known because it is compatible with Jinja2.

I'm not saying that Tera is not a good software. I've loved and used it for a long time. But I think that MiniJinja is better and it can be a personal opinion but I wanted to bring the discussion here.

Furthermore, this is not an easy change because it implies a breaking change but probably Tera V2 is going to have similar problems.

[Cyclonit]

Can you provide a couple of examples of syntax that is supported by MiniJinja but not Tera? A list of breaking changes would be nice too.

[pando85]

The things from this list: Keats/tera#637

Plus the syntax is fully compatible with Jinja2.

[orhun]

I think this will be a significant breaking change. However, I'm curious about the possibility of supporting MiniJinja with a feature flag for users who might prefer it over Tera (e.g. --features minijinja-templates).

But I'm not still sure if it is worth it. @pando85 what was the feature you needed the most in MiniJinja which Tera does not have?

[pando85]

I don't have anything special. I want to bring here the discussion. From my perspective it can be a better solution for the future. Probably it could be better just to wait to see what happen with https://github.com/Keats/tera2 which seems that it is already in beta.

Which seems clear to me is that Tera (v1) is going to be deprecated soon.

[orhun]

Ooh, I didn't know about the existence of that repository. Thanks for sharing!

Which seems clear to me is that Tera (v1) is going to be deprecated soon.

It's definitely exciting :)

[muja]

Just to add my POV, I agree with the post. On top of tera being less familiar, it has a lot of short-comings and missing features. For context, I've spent many hours engineering a cliff.toml for our organization, and it was really not a clean experience. To summarize:

• It feels it's almost impossible to manage whitespace like newlines between blocks, especially if there is a conditional paragraph. I finally gave up and added this to make our Markdown linter happy:

  footer = """
  <!-- markdownlint-configure-file
    {
      "MD033": { "allowed_elements": [ "br" ] },
      "MD012": { "maximum": 3 },
      "MD024": { "siblings_only": true },
    }
  -->
  """

  Go's templating engine (which has pretty atrocious syntax) solves this by controlling whitespace handling around {{}} based on dashes:

  • {{- x }}: removes whitespaces before
  • {{ x -}}: removes whitespaces after
  • {{- x -}}: removes whitespaces before and after

• On a related note, all the {% raw %}\n{% endraw %} are extremely verbose and annoying.

• It's not a familiar language and there is no editor support. Most people have had contact with jinja through the omnipresent python or through ansible or other tools, they are rather common. This is one of the cases where I'd argue that familiarity is actually a feature. Nobody wants to adopt / learn new templating languages when there are already enough technologies to grind out there.

• No support for dictionaries / objects.

• Some filters are missing, and it's not possible to add new filters. You can only use macros but their usage is very limited, you can't have a return value, they can only output stuff. The docs only seem to mention how to expose filters written in Rust to the template. I had been spending a lot of time trying to put functionality into a reusable component / function and failed.

  Specifically, I wanted to write a small function that returns ticket footers of a commit:

  {%- for ticket_key in ['JIRA', 'Relates-to', 'JIRA-Ref'] -%}
      {%- for ticket in commit.footers | filter(attribute='token', value=ticket_key) -%}
          {% set_global tickets = tickets | concat(with = ticket.value | replace(from=' ', to='') | split(pat=',')) %}
      {%- endfor -%}
  {%- endfor -%}
  

  It was also not possible to group tickets by commit id since no dictionaries are supported. My goal was to have a summarized "Tickets: ..." on top of every version / under the release description and a list of tickets in the detailed change listing. Alas, it was not possible without duplication.

I've since come to the conclusion to stay away from Tera if possible. I've even toyed with the idea to only use git cliff --context and feed that JSON into the templating engine of your choice. I believe that would be a workaround if git cliff does not plan to add any other templates.

[orhun]

Those are fair points. I'm open to a PR to experimentally support a more known templating engine if anyone wants to contribute :)