gerv/bugzilla-docs

Fork of Bugzilla where I'm working on rewriting the docs

bugzilla-docs's Issues

5.6. Writing Extensions

5.6.3. Adding New Fields To Bugs

I would mention the bug_end_of_update and bug_end_of_create for setting the new bug fields when a bug changes.

• You can use bug_end_of_create, bug_end_of_create_validators, and bug_end_of_update the create or update the values for your new field.

5.6.4. Adding New Fields To Other Things

• You can use the global hooks object_end_of_create, object_end_of_create_validators, object_end_of_set_all, and object_end_of_update to create or update the values for the new object fields you have added.
• In the hooks you can check the object type being operated on and skip any others. For example, if you added a new field to the products table:

.. code-block:: perl
sub object_end_of_create {
my ($self, $args) = @_;
my $class = $args->{'class'};
my $object = $args->{'object'};
if ($class->isa('Bugzilla::Product') {
[...]
}
}

You will need to do this for most of the hooks starting with object_*.

Windows Todos, explained

2.3. Todo: mod_perl on windows is still a bear.

2.3.1. Todo: No, my install is a 64bit perl. You just have to make sure everything else is 64bit

2.3.3. Todos: No, the module list is incomplete. It varies depending on perl version.
Yes, install-module.pl does not work on windows at the moment. (Weirdly, cpan works and even installs a C compiler!)

5.4 Languages

Need to mention that if multiple languages are installed on the current system, a menu will display in the header allowing the user to manually select a different lanuage to display. This overrides the Accept-Language header.

8.1: Grammar

Add comma: "Bugzilla uses cookies to remember you are logged in, so, unless ..."

WebDot vs GraphViz

Section 7.1.8 is a bit confusing. If I understand correctly, WebDot is a web (CGI) version of GraphViz's "dot" program, and the latter does not require the former; this seems to be implied by the first webdotbase bullet. If so, this section should be cleaned up to somehow indicate that you can use a local GraphViz installation or a WebDot installation, since you don't need WebDot at all if you have local GraphViz (again, if I understand this properly).

8.5 edits

Bugzilla queries are case-insensitive and accent-insensitive, when used with either MySQL or Oracle databases. When using Bugzilla with PostgreSQL, however, some queries are case-sensitive.

Bugzilla queries are case insensitive and accent insensitive when used with either MySQL or Oracle databases. When using Bugzilla with PostgreSQL, however, some queries are case sensitive.

8.2.1: Grammar

(I know this is old text but maybe fix now?)

First paragraph should technically read more like this:

Years of bug-writing experience has been distilled for your reading pleasure into the Bug Writing Guidelines. While some of the advice is Mozilla-specific, the basic principles of reporting Reproducible, Specific bugs and isolating the Product you are using, the Version of the Product, the Component which failed, the Hardware Platform, and Operating System you were using at the time of the failure go a long way toward ensuring accurate, responsible fixes for the bug that bit you.

Section 7 issues

Section 7.3.3:

Login Name: This is generally the user's full email address. However, if you have are using the emailsuffix parameter, this may just be the user's login name. Note that users can now change their login names themselves (to any valid email address).

"can now" -> since what version? Has this ability been around long enough now to remove this note?

Change notes for documentation section 3

3.1 Overview
Should we capitalize the first words in the numeric list?

3.2.3
The 'TODO' should probably be removed. This is, to the best of my knowledge, the best way to pull stable.

3.4.1
On the 'TODO': if we want to avoid the task of updating to the latest point release, we'd probably want to get into detail on git tags, so they can compare against their current running version.

Misc. notes

• Should the migration for each VCS type be consolidated, as many of the sections feature 90% of the same content?
• Should we mention extension-convert.pl in this section for those running versions of Bugzilla using the older extensions style? (I can confirm that this file still works properly, as I used it going from 3.4 to 4.4)

8.6 edits

sets of bugs over time.)

sets of bugs over time).

8.7 edits

For example, the text "http://www.bugzilla.org" will be turned into a link: http://www.bugzilla.org.

Either omit the last part or prevent the former from being linkified in the docs, as there's no difference between the two the way it's currently written.

Section 2.5.1.2

The theory58S mirror seems to be gone. It's been my experience that newer perls are much easier to work with on Windows, perhaps we could recommend 5.12 or newer?

8.3: comments & suggestions

"These define exactly what state the bug is in - from ..."

First, I'd vastly prefer the use of proper em dashes (with no spaces, e.g. "... bug is in—from ...") everywhere (and I wouldn't be surprised if dash styles change throughout the document). Second, perhaps a colon is better suited here.

This applies to other sections below that follow the same pattern.

8.4 edits

for large chunks of ASCII data

plaintext (or plain text)?

Section 2.4 issues

Going to report issues here as I go through the OS X installation docs.

First, I think you can get gd support also through homebrew via "brew install gd". It would be nice to indicate how we can verify that Bugzilla has found gd, though.

5.6. Writing Extensions

• Early on I would mention that the extensions/Example/* files contain good examples on how to use the various hooks.
• Need to mention page.cgi and page_before_template to create standalone cgi pages such as reports, etc.
• template_before_process can be used to add data or alter current data.
• Add a small section describing how to add a WebService API call such as Example.hello.

5.6.2. Adding New Fields To Other Things

• Need add couple more bullet points about object_end_of_set_all, object_end_of_create, and object_end_of_update.

5.6.3. Adding Admin Configuration Panels

• Add section mentioning how to access the param values from templates such as [%

Param('extension_param') %] or Bugzilla->params->{extension_param}.

• Also needs short explanation about creating a extensions/ExtensionName/lib/Config.pm module for defining the new parameters. Again mention extensions/Example/lib/Config.pm for example.

5.6.6. Checking Syntax

• The extra whitespace in the sample code looks strange.

5.5 Templates

5.5.1. Template Directory Structure

• In the warning section, s/data/templates/data/template/ and also mentioned that it is Perl code as another reason not ot manually edit those files.

5.5.2. Choosing a Customization Method

• In point 3, the template hooks do not necessarily allow you to alter the current UI using the template syntax. Mainly you can 'add' things to the UI using template syntax. Or you can add JavaScript code and then be able to make alterations to the core Bugzilla UI.

5.5.3. How To Edit Templates

• Bugzilla usually does a pretty good job of picking up on template changes and recompiling the needed templates dynamically so checksetup.pl is not always necessary. Although checksetup.pl will correct any permissions issues so that the web server can generate the compiled template code properly.

5.5.5. Particular Templates

• bug/create/create.html.tmpl and bug/create/comment.txt.tmpl:
  • Remove 'mozilla.org' from the sentence describing the guide-entry form.
• The default template, on which you could base it, is custom/bug/create/create.html.tmpl and should be in the same directory.
• s/widgets/form inputs/
• Then, create a template like custom/bug/create/comment.txt.tmpl, and call it comment-.txt.tmpl and should be in the same directory.
• You can not use [% form. %]. You will need to instead use as an example:

[% USE Bugzilla %]
[% cgi = Bugzilla.cgi %]
User-Agent: [%+ cgi.user_agent() %]
Build Identifier: [%+ cgi.param("buildid") %]

8.2.2: Grammar

"Bugzilla allows you to 'clone' an existing bug"

I think we should use double quotes here, as we appear to do elsewhere.

8.8 edits

The preferences are split into a number of tabs:

It's a bit weird to end on a colon here, since what follows are subsections with big headers, not an in-section list. Maybe something like

The preferences are split into a number of tabs, detailed in the sections below.

or something.

6.1. APIs

6.1.1. Ad-Hoc APIs

• RSS Feed and iCalendar
• I would not mention that the CSV format and XML format should not be used for new code as IMO they are considered stable and should not be going away anytime soon. CSV is also useful for spreadsheet import, for example.

For the others, would it be worth mentioning the end points for each of the different API methods?

• REST - /rest/bug/35 (or /rest.cgi/bug/35 if they do not use mod_rewrite)
• XMLRPC - /xmlrpc.cgi
• JSONRPC - /jsonrpc.cgi

IMO, we could just leave out the mention of the BzAPI compatibility extension as this is documentation for upstream and may just cause extra confusion. People will just use the REST API anyway. Also I woild leave out the mention of REST v2 since documentation about a stable API should not need to mention about upcoming features or releases. That is for the release notes.