[bugzilla-gnome-org-customizations] template overrides: Add a README

[Krzesimir Nowak <krnowak src gnome org>]

commit a0a0812e045cd8cf2446f5da0c8ab831c5ab367e
Author: Krzesimir Nowak <qdlacz gmail com>
Date:   Sun Feb 8 22:02:33 2015 +0100

    template overrides: Add a README
    
    Most important part is explaining how to add a new template override.

 extensions/TemplateOverrides/README |   72 +++++++++++++++++++++++++++++++++++
 1 files changed, 72 insertions(+), 0 deletions(-)
---
diff --git a/extensions/TemplateOverrides/README b/extensions/TemplateOverrides/README
new file mode 100644
index 0000000..ab28582
--- /dev/null
+++ b/extensions/TemplateOverrides/README
@@ -0,0 +1,72 @@
+ABOUT
+=====
+
+This extension is a central place to store template overrides. It also
+tracks if overridden templates haven't changed. If they did, then
+checksetup will fail.
+
+TERMS
+=====
+
+Template override - it is our version of a template
+Overridden template - it is original version of a template we are
+overriding
+
+ADDING NEW TEMPLATE OVERRIDE
+============================
+
+Follow these steps to add new template override:
+
+(Lets assume we have bugzilla-gnome-org-upstream repo in <BGOU>
+directory and bugzilla-gnome-org-customizations repo in <BGOC>
+directory. Also lets assume that we want to override a
+bug/edit.html.tmpl file)
+
+1. Locate the bug/edit.html.tmpl file in <BGOU> (it it in
+   <BGOU>/templates/en/default/bug/edit.html.tmpl).
+
+2. Compute its sha256 (with i.e. sha256sum).
+
+3. Open <BGOC>/extensions/TemplateOverrides/lib/Digests.pm and add an
+   entry to digests hash (just follow already existing entries). It
+   would look like this:
+
+   'bug/edit.html.tmpl' => '<SHA256SUM>',
+
+   Please ensure that new entry is put in alphabetic order.
+
+4. Copy the file <BGOU>/templates/en/default/bug/edit.html.tmpl to
+   <BGOC>/extensions/TemplateOverrides/templates/en/default/bug/edit.html.tmpl.
+
+5. Add new file and changes in Digests.pm to git, commit.
+
+6. Make changes in template override, add changes to git, commit.
+
+I separated steps 5. and 6., so we can clearly see our changes in
+template override with git log -p.
+
+Also, I recommend keeping changes in overrides as minimal as
+possible. It would be best if the changes were limited to just adding
+a hook. That could be even upstreamed at some point, so we would be
+able to remove an override.
+
+TRACKING CHANGES
+================
+
+Tracking changes is implemented by basically comparing sha256
+checksums during checksetup. Checksetup looks for overridden template
+files, computes their sha256 checksums and compares them with relevant
+entries stored in Digests.pm. If the checksums are different then it
+means that (barring any mistakes) overridden template has changed
+since we added an override and this has to be acknowledged. Checksetup
+fails at this point.
+
+ACKNOWLEDGING THE CHANGES IN OVERRIDDEN TEMPLATES
+=================================================
+
+It is usually done in two steps:
+
+1. Backport the changes in overridden template to template override.
+
+2. Compute the sha256 sum of the overridden template and update the
+relevant entry in Digests.pm.