140527 - Developers' Guide - Template versioning.

Status: VERIFIED WONTFIX

(Bugzilla :: bugzilla.org, enhancement)

Description

[Matthew Tuck [:CodeMachine]]

Please specify below the relevant information about template versioning,
including when to increase the version, how to insert versions into templates, etc.

This is needed for the developers' guide.

Comment 1

[Gervase Markham [:gerv]]

Attempt 1:

Every template shipped with Bugzilla has a version number at or near the top,
e.g. <!-- [e-mail] --> . If you customise a template, you should keep
the same version number in the custom template, and add your own domain name.

On occasion, the version numbers of the Bugzilla-shipped templates will change.
This version number has a major part and a minor part.

If the major part changes, that means the interface to this template is
incompatible with the interface to previous templates. Bugzilla will note this
incompatibility and tell you about it.

If the minor part changes, the interface is backwardly-compatible, but there are
some changes you should investigate and consider also making in your custom
templates.

For those templates with INTERFACE comments, you can use CVS to see the
differences in this section of the file, to get an rundown on what has changed
about the template interface.

Gerv

Comment 2

[Zach Lipton [:zach]]

Also, make sure to note that template version strings in templates which 
are not html should be wrapped in TT comments.

Comment 3

[Matthew Tuck [:CodeMachine]]

OK, I updated the Guide with the appropriate details.  Please check it.

Gerv, the stuff you mentioned is for administrators, this is the developers'
guide.  Take the admin stuff to bug #147137.

If you're happy with what's been written, feel free to close this out, otherwise
let me know what still has to be done.

Comment 4

[Vaskin Kissoyan]

Bugzilla uses Template Toolkit 2 (tt2) which is available http://www.tt2.org/.
Bugzila version X requires TT version X. There is no need to install tt2
seperately, it is included with your install of bugzilla. The included version is X.

Please find the docs at this URL: 
http://www.template-toolkit.org/docs.html

Comment 5

[Bradley Baetz (:bbaetz)]

Err..

Bugzilla doesn't come with TT. Bundle::Bugzilla brings it in from CPAN, but
thats not the same thing.

Comment 6

[Vaskin Kissoyan]

Ok, so that should be ammended. I'm just concerned that users should know where
to seek documentation on the syntax of these templates.

Comment 7

[Vaskin Kissoyan]

ping

Comment 8

[Dave Miller [:justdave]]

MattyT: status?

Comment 9

[Gervase Markham [:gerv]]

If this is for developers only, it's not a blocker on the 2.16 release.

Gerv

Comment 10

[Dave Miller [:justdave]]

Let's get this in...

Comment 11

[Gervase Markham [:gerv]]

What this bug actually now represents (if anything) is:

The latest ideas for template versioning are that we always use TT comments. The
Developers Guide does not reflect this. It should.

Gerv

Comment 12

[Max Kanat-Alexander]

In order for this to be actually useful, there has to be some easy way for the
admin to find out which version numbers have changed. Until we come up with
that, the template versioning isn't very useful.

Comment 13

[Frédéric Buclin]

The trunk is now frozen to prepare Bugzilla 2.22. Only bug fixes are accepted, no enhancement bugs. As this bug has a pretty low activity (especially from the assignee), it's retargetted to ---. If you want to work on it and you think you can have it fixed for 2.24, please retarget it accordingly (to 2.24).

Comment 14

[GavinS]

The version comments have been removed from the templates, so this can be resolved, I guess...

Comment 15

[Frédéric Buclin]

yes