233398 - Section 4.2: CVS prevents hooks documentation from being accurate

Status: RESOLVED FIXED

(Bugzilla :: Extensions, defect)

Description

[Dave Miller [:justdave]]

The current documentation states there are directories for the hooks files to be
placed in already.  We can't create empty directories in CVS for the hooks. 
Either checksetup.pl needs to create them (automatically by grepping for
Hook.process?), or we need something in them (a README file?) or we need to
change the documentation to indicate that the user needs to create it.  Our
tarball-producing scripts and the cvs command line that we tell people to use
will cause empty directories to be removed on checkout.

Comment 1

[Max Kanat-Alexander]

You could put an empty hidden file in there, called .dir. -M

Comment 2

[Gervase Markham [:gerv]]

Max: such a file wouldn't be hidden on Windows.

I say we change the documentation to tell the user to create it. We'd need to
explain it quite carefully, but I'm sure we can manage that.

Gerv

Comment 3

[Myk Melez [:myk] [@mykmelez]]

Making users create these directories makes things harder for them
unnecessarily.  Of the options, the README sounds best to me, since it's the
simplest, lowest-tech approach (i.e. doesn't rely on possibly buggy code), and
we could put a brief note in it explaining where hooks in the directory get
placed in the UI.

Note that a README file only needs to be placed into the lowest-level
directories (f.e. extension/hook/global/useful-links/edit), since other
directories'll have child directories within them.

Comment 4

[Gervase Markham [:gerv]]

Yeah, OK. Sounds sensible.

Something like:

"Templates in the directory are hooked into <part of the UI>.

For more information on the "hooks" customisation mechanism, see the Bugzilla
Guide."

Gerv

Comment 5

[Dave Miller [:justdave]]

Preliminarily moving all docs bugs to 2.18, we should make a valiant attempt to
have the docs as up-to-date as possible when 2.18 releases.

Comment 6

[Frédéric Buclin]

Is this bug still relevant? I have no idea what justdave is talking about in comment 0.

Comment 8

[Frédéric Buclin]

Bugzilla 2.22 is no longer supported.

Comment 9

[Max Kanat-Alexander]

Documentation for the extensions system now lives entirely in the POD for Bugzilla::Extensions, so we should just point people there instead.

Comment 10

[Max Kanat-Alexander]

Attachment: v1

This removes the existing hooks docs in favor of just pointing at the POD of Bugzilla::Extension.

Comment 11

[Frédéric Buclin]

Comment on attachment 415288 [details] [diff] [review]
v1

r=LpSolit

Comment 12

[Max Kanat-Alexander]

Checking in docs/en/xml/customization.xml;
/cvsroot/mozilla/webtools/bugzilla/docs/en/xml/customization.xml,v  <--  customization.xml
new revision: 1.48; previous revision: 1.47
done