WORDPRESS.ORG TRAC TEMPLATES
============================

These templates customize Trac for WordPress.org: they wrap the make.wordpress.org
global header and footer around Trac, add gravatars, and make a slew of other
adjustments.

They target Trac 1.6, which uses the **Jinja2** template engine (Trac switched from
Genshi to Jinja2 in 1.4). Jinja2 templates use `#`-prefixed line statements
(`# if`, `# for`, `# set`, `# macro`, `# include`, ...), `${...}` expressions, and
`{# ... #}` / `##` comments. See:
  https://trac.edgewall.org/wiki/TracDev/Proposals/Jinja/TracInterfaceCustomization
  https://trac.edgewall.org/wiki/TracDev/PortingFromGenshiToJinja

Testing changes to these files requires a local Trac 1.6 (Python 3) install; see
https://trac.edgewall.org/wiki/TracInstall. Changes must not be deployed without
testing.

IMPORTANT: Genshi's `py:match` stream filter — which the old `site.html` used to
rewrite arbitrary elements anywhere in Trac's generated HTML — HAS NO JINJA2
EQUIVALENT. Jinja2 site customization is limited to three *additive* placeholder
templates (below). Everything the old `site.html` did by matching/rewriting existing
markup (strip the Trac header/footer, swap the login/logout links, inject notices
into the new-ticket form, reporter/owner gravatars, prefs tweaks, query/search
tweaks, nofollow-ugc link rewriting, CDN cache-busting, etc.) now lives client-side
in wp-trac.js / wp-trac.css (served from s.w.org, and/or the env htdocs).


SHARED TEMPLATES (used by every Trac)
-------------------------------------

 *  site_head.html, site_header.html, site_footer.html

    The three placeholder templates Trac 1.6 auto-includes (replacing the old
    single `site.html`). site_head.html is injected into <head>; site_header.html
    at the start of <body>; site_footer.html at the end of <body>. They compute the
    per-request values (project slug, canonical/robots, notifications, etc.) and
    pull in the markup includes below. Only additive content belongs here.

 *  wporg-head.html, wporg-header.html, wporg-footer.html

    Manually-synced snippets of WP.org's <head>, header and footer, generated by
    update-headers.php. Included by the three site_* templates. Plain HTML fragments
    (no <html> wrapper).

 *  wporg-menu.html

    The per-Trac headline/menu, included by site_header.html. The copy here is the
    shared default (renders the project name). An environment can ship its own
    wporg-menu.html to override it (see core/, meta/).

 *  ticket_change.html

    Overrides the core Trac template of the same name to add author gravatars,
    chat-bot (slackbot/ircbot) and prbot rendering, and comment rendering with
    abuse/DoS safety caps. REQUIRES a companion Trac plugin that registers three
    functions into the Jinja2 context (Genshi allowed inline <?python?>; Jinja2 does
    not): wporg_sanitize_user_nicename(name), wporg_wiki_to_html(context, wikidom,
    escape_newlines=None), and wporg_prbot_strip_meta(text). See the file header.


PER-ENVIRONMENT TEMPLATES (core/, meta/, bbpress/, buddypress/)
---------------------------------------------------------------

Each Trac environment's own templates directory takes precedence over the shared
one. To *supplement* (rather than replace) the shared site_head/site_footer, an
environment ships site-specific-head.html and/or site-specific-footer.html, which
the shared site_head.html/site_footer.html `# include ... ignore missing`:

 *  core/site-specific-head.html      — make-core.css
 *  core/site-specific-footer.html    — #report-popup + contributor-label JS
 *  meta/site-specific-footer.html    — autocomplete-users JS
 *  core/wporg-menu.html, meta/wporg-menu.html — per-Trac headline/menu

bbpress/ and buddypress/ ship their own wporg-head/header/footer.html (bbPress.org
/ BuddyPress.org branding) and a no-op wporg-menu.html. Their old Genshi banner
reorganization (py:match on div#banner) is now client-side in wp-trac.js / CSS.


update-headers.php
------------------

Regenerates wporg-head.html, wporg-header.html and wporg-footer.html from the
wordpress.org global-header-footer REST API. It writes bare HTML fragments (no
Genshi/<html> wrapper).