390603 - Configuration parameters documentation needs updating

Status: RESOLVED FIXED

(Bugzilla :: Documentation, defect)

Description

[bigstijn]

User-Agent:       Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1; .NET CLR 1.1.4322; .NET CLR 2.0.50727; .NET CLR 1.0.3705; InfoPath.1)
Build Identifier: Bugzilla 3.0

upgrade_notification and proxy_url should be part of documentation (3.1. Bugzilla Configuration)

In 3.14.2. Upgrading - Notifications, there is a reference to 3.1.:
based on the upgrade_notification parameter, see Section 3.1. 

In bug 380375 is mentioned:
- proxy_url should be of the form  http://proxy_url/ or http://user:pass@proxy_url/
- when no proxy_url is defined, bugzilla looks to the HTTP_PROXY env variable
- when authentication for the proxy is necessary, the proxy_url with the authentication syntax should be used. (Using HTTP_PROXY_USER will not work)


When this is ignored, the admin gets (according to bug 380375 ) a direct error message.  So, it's a good idea to put in the configuration documentation.

Reproducible: Always

Comment 1

[Max Kanat-Alexander]

LpSolit: Didn't I review a patch about 30 seconds ago that does this?

Comment 2

[Frédéric Buclin]

Heh, not exactly the same request. The other bug fixes (among others) http://www.bugzilla.org/docs/tip/html/upgrading.html#upgrading-notifications while this bug is about http://www.bugzilla.org/docs/tip/html/parameters.html

But that's a dupe of another bug, though, one which request to update section 3.1 already.

Comment 3

[bigstijn]

(In reply to comment #2)
> But that's a dupe of another bug, though, one which request to update section
> 3.1 already.

Sorry, I can't find it.

Comment 4

[Frédéric Buclin]

(In reply to comment #3)
> Sorry, I can't find it.

Yes, you are right. I cannot find it either. I probably suggested on IRC to file a bug to add all missing parameters at once, and I never did.

Comment 5

[Sam Folk-Williams]

I am working on this. A little review shows the entire section to be quite badly out of date, so I will do a patch that fleshes out the whole section (in addition to adding these two parameters).

-Sam

Comment 6

[Max Kanat-Alexander]

Okay. Remember not to duplicate the documentation that's already in the Parameters page itself. That is, only parameters that actually *need* additional documentation need to be doc'ed.

Comment 7

[Sam Folk-Williams]

(In reply to comment #6)
> Okay. Remember not to duplicate the documentation that's already in the
> Parameters page itself. That is, only parameters that actually *need*
> additional documentation need to be doc'ed.
> 

Well I think some things that are more critical can be explained at greater length. My plan is basically to summarize each of the several categories of parameters that are in the menu on the left, and then to highlight a few of the more important ones from each section. The required parameters I believe should all be doc'ed in the docs...

Comment 8

[Sam Folk-Williams]

Attachment: draft 1 patch

This ended up being a pretty large patch:

- Broke the entire section into sub sections, with one seb section for each of the configuration categories that exist on editparams.cgi
- Documented *all* of the required parameters (i know some of this is redundant with the docs already in bugzilla itself, but I think it's best to over-doc than under-doc
- Described all the other sections and documented certain (not all) parameters in some of those sections
- Moved several of the additional configuration descriptions from the Installation section and put them here
- Deleted some stuff from the additional configuration section in Installation as it seemed quite outdated.

Please carefully review - I'm open to any comments/suggestions/disagreements here. Also, there's a good chance I messed up some XML and such though i tried to be careful.

-Sam

Comment 9

[Colin Ogilvie [:cso]]

Comment on attachment 301107 [details] [diff] [review]
draft 1 patch

The XML that's generated after applying this patch is invalid:

Creating separate HTML documentation ...
jade -t sgml -i html -d /usr/share/sgml/docbook/ldp/ldp.dsl#html /usr/share/doc/openjade-1.3.2/pubtext/xml.dcl ../xml/Bugzilla-Guide.xml

jade:../xml/administration.xml:216:64:E: element "code" undefined
jade:../xml/administration.xml:218:69:E: element "code" undefined
jade:../xml/administration.xml:219:28:E: element "code" undefined

-- code appears to be a 4.3 feature, whereas we declare the docs to be v4.1.2; I'm not adverse to upgrading to declaring the docs to be 4.3 as long as it doesn't break them.

jade:../xml/administration.xml:263:19:E: an attribute value literal can occur in an attribute specification list only after a VI delimiter
jade:../xml/administration.xml:263:20:E: character data is not allowed here
jade:../xml/administration.xml:295:19:E: an attribute value literal can occur in an attribute specification list only after a VI delimiter
jade:../xml/administration.xml:295:20:E: character data is not allowed here
jade:../xml/administration.xml:346:19:E: an attribute value literal can occur in an attribute specification list only after a VI delimiter
jade:../xml/administration.xml:346:20:E: character data is not allowed here
jade:../xml/administration.xml:355:19:E: an attribute value literal can occur in an attribute specification list only after a VI delimiter
jade:../xml/administration.xml:355:20:E: character data is not allowed here
jade:../xml/administration.xml:418:19:E: an attribute value literal can occur in an attribute specification list only after a VI delimiter
jade:../xml/administration.xml:418:20:E: character data is not allowed here
jade:../xml/administration.xml:461:19:E: an attribute value literal can occur in an attribute specification list only after a VI delimiter
jade:../xml/administration.xml:461:20:E: character data is not allowed here
jade:../xml/administration.xml:475:19:E: an attribute value literal can occur in an attribute specification list only after a VI delimiter
jade:../xml/administration.xml:475:20:E: character data is not allowed here
jade:../xml/administration.xml:487:19:E: an attribute value literal can occur in an attribute specification list only after a VI delimiter
jade:../xml/administration.xml:487:20:E: character data is not allowed here
jade:../xml/administration.xml:754:19:E: an attribute value literal can occur in an attribute specification list only after a VI delimiter
jade:../xml/administration.xml:754:20:E: character data is not allowed here
jade:../xml/administration.xml:830:19:E: an attribute value literal can occur in an attribute specification list only after a VI delimiter
jade:../xml/administration.xml:830:20:E: character data is not allowed here
jade:../xml/administration.xml:841:19:E: an attribute value literal can occur in an attribute specification list only after a VI delimiter
jade:../xml/administration.xml:841:20:E: character data is not allowed here
jade:../xml/administration.xml:852:19:E: an attribute value literal can occur in an attribute specification list only after a VI delimiter
jade:../xml/administration.xml:852:20:E: character data is not allowed here
jade:../xml/administration.xml:880:19:E: an attribute value literal can occur in an attribute specification list only after a VI delimiter
jade:../xml/administration.xml:880:20:E: character data is not allowed here

-- All appear to be due to |<section id"something">| without an = sign, an easy fix for you :)

jade:../xml/administration.xml:695:17:E: end tag for element "notes" which is not open
jade:../xml/administration.xml:752:17:E: end tag for "note" omitted, but OMITTAG NO was specified
jade:../xml/administration.xml:690:10: start tag was here

-- Another simple fix as it's just a typo.

I'm going to take a read through the content just now.

Comment 10

[Colin Ogilvie [:cso]]

Some other minor issues are:

<glossterm linkend="gloss-contrib"><filename class="directory">contrib
</filename></glossterm> directory. Another possible solution is fixing
<ulink url="http://bugzilla.mozilla.org/show_bug.cgi?id=201069">bug
201069</ulink>.

-> the link to contrib ends up being 'contrib ' so the underline looks weird.
-> the link to Bugzilla should be be https:

'Bonsai is a tool that enables queries a CVS tree' should be 'Bonsai is a tool that enables queries *to* a CVS tree'

'Instead, InnoDB is used, which can do transaction-bsaed locking.' -> 'Instead, InnoDB is used, which can do transaction-based locking.'

Comment 11

[Sam Folk-Williams]

Attachment: draft2

Thanks Colin - good eye. Fixed all that. I used a bad "<section" tag as my copy paste template :( so had a lot of those to fix.

-Sam

Comment 12

[Sam Folk-Williams]

Attachment: draft3

made an enhancement to the groups description and finally removed the <code> tags

Comment 13

[Frédéric Buclin]

Comment on attachment 301330 [details] [diff] [review]
draft3 

>Index: xml/administration.xml

>+                For example, if the "Bugzilla Configuration" page 
>+                of the documentation is
>+                <filename>http://www.foo.com/bugzilla/docs/parameters.html</filename>, 
>+                set the <quote>docs_urlbase</quote>
>+                to <filename>http://www.foo.com/bugzilla/docs/</filename>.

Nit: would be better to write docs/html/ rather than docs/ alone as the former is more likely to happen.


>+                <filename>http://www.foo.com/bugzilla/</filename>, the 
>+                <command>cookiepath</command> should be set to 
>+                <filename>/bugzilla</filename>.

Should be /bugzilla/ rather than /bugzilla.


This is a great patch! Beautiful! r=LpSolit

Comment 14

[Frédéric Buclin]

A sentence or two is not applicable to 3.0 (such as the Administration page not yet existing, mention of InnoDB which is for 3.2 only, and duplicate_or_move_bug_status is only for 3.2 and above; I think that's all). Backport needed.

Comment 15

[Frédéric Buclin]

tip:

Checking in docs/xml/administration.xml;
/cvsroot/mozilla/webtools/bugzilla/docs/xml/administration.xml,v  <--  administration.xml
new revision: 1.84; previous revision: 1.83
done
Checking in docs/xml/installation.xml;
/cvsroot/mozilla/webtools/bugzilla/docs/xml/installation.xml,v  <--  installation.xml
new revision: 1.153; previous revision: 1.152
done

Comment 16

[Sam Folk-Williams]

Attachment: backport to 3.0

i think this should do it. I couldn't find "duplicate_or_move_bug_status" in here.

Comment 17

[Frédéric Buclin]

Comment on attachment 301791 [details] [diff] [review]
backport to 3.0

Doesn't compile:

jade:../xml/administration.xml:552:21:E: ID "bzldap" déjà défini
jade:../xml/installation.xml:1508:17: ID "bzldap" défini pour la première fois ici
jade:../xml/administration.xml:614:30:E: ID "param-LDAPserver" déjà défini
jade:../xml/installation.xml:1567:26: ID "param-LDAPserver" défini pour la première fois ici
jade:../xml/administration.xml:636:31:E: ID "param-LDAPbinddn" déjà défini
jade:../xml/installation.xml:1589:27: ID "param-LDAPbinddn" défini pour la première fois ici
jade:../xml/administration.xml:648:31:E: ID "param-LDAPBaseDN" déjà défini
jade:../xml/installation.xml:1601:27: ID "param-LDAPBaseDN" défini pour la première fois ici
jade:../xml/administration.xml:659:31:E: ID "param-LDAPuidattribute" déjà défini
jade:../xml/installation.xml:1612:27: ID "param-LDAPuidattribute" défini pour la première fois ici
jade:../xml/administration.xml:671:31:E: ID "param-LDAPmailattribute" déjà défini
jade:../xml/installation.xml:1624:27: ID "param-LDAPmailattribute" défini pour la première fois ici

Comment 18

[Frédéric Buclin]

Comment on attachment 301330 [details] [diff] [review]
draft3 

This one is not obsolete as it has been checked in.

Comment 19

[Sam Folk-Williams]

Attachment: draft2 3.0 backport

OK looks like I forgot to remove the stuff from install that I have moved to admin, should work now. Also added an xref that I had missed before to the patch viewer.

Comment 20

[Frédéric Buclin]

Comment on attachment 302277 [details] [diff] [review]
draft2 3.0 backport

>Index: xml/administration.xml

>+            <term>
>+              maintainer
>+              <para> 
>+              The address need not be that of a valid Bugzilla account.

Not true. The maintainer doesn't need to have a Bugzilla account.


>+            <term>
>+              docs_urlbase
>+              <para>
>+                Defines the fully qualified domain name and web 

Incomplete. It can also be a path relative to urlbase, e.g. docs/html/.


>+          <title>Attachments</title>
>           <para>
>+            and whether to allow uploading of remote files via a URI.

Note that you cannot upload files using this feature, but only point to an external file.


>+          <title>Bug Change Policies</title>
>+            Set policy on default behavior for bug change events. For example,
>+            choose which status to set a bug to when it is marked as a duplicate,

No, this parameter doesn't exist on 3.0.


>+          <title>LDAP Authentication</title>

Before this section, you have to describe "Localization", which exists in 3.0 but no longer exists in 3.2 (which is probably the reason why you missed it here).


>+          <title>RADIUS Authentication</title>

RADIUS is not available in 3.0.

Comment 21

[Frédéric Buclin]

Comment on attachment 302277 [details] [diff] [review]
draft2 3.0 backport

>Index: xml/installation.xml

>-    PerlSwitches -I/var/www/html/bugzilla -w -T
>+    PerlSwitches -I/var/www/html/bugzilla -I/var/www/html/bugzilla/lib -w -T

One more thing: undo this change. bugzilla/lib doesn't exist in 3.0.

Comment 22

[Sam Folk-Williams]

(In reply to comment #20)
> (From update of attachment 302277 [details] [diff] [review])
> >Index: xml/administration.xml
> 
> >+            <term>
> >+              maintainer
> >+              <para> 
> >+              The address need not be that of a valid Bugzilla account.
> 
> Not true. The maintainer doesn't need to have a Bugzilla account.
> 

Your comment and the patch say the same thing :-)

This bit is not changed in the patch (just moved i believe)

Comment 23

[Sam Folk-Williams]

Attachment: new draft3 3.0 backport

i think this should cover it..

Comment 24

[Frédéric Buclin]

(In reply to comment #22)
> > Not true. The maintainer doesn't need to have a Bugzilla account.
> > 
> 
> Your comment and the patch say the same thing :-)

Ah yes, sorry, I misread your sentence. :)

Comment 25

[Frédéric Buclin]

Comment on attachment 303161 [details] [diff] [review]
new draft3 3.0 backport

>+        <section id="param-bug-change-policies">
>+          <title>Bug Change Policies</title>

>+            choose which status to set a bug to when it is marked as a duplicate,

No, as I said in my previous review, this parameter doesn't exist in 3.0. This is a 3.2-only feature.

Everything else looks fine.

Comment 26

[Sam Folk-Williams]

Attachment: draft 4 3.0

OK i think this should do it

Comment 27

[Frédéric Buclin]

Comment on attachment 303717 [details] [diff] [review]
draft 4 3.0

Changes in installation.xml are missing.

Comment 28

[Sam Folk-Williams]

Attachment: draft 5 of 3.0 backport

Man, I am bad at patches.

Comment 29

[Frédéric Buclin]

Comment on attachment 303730 [details] [diff] [review]
draft 5 of 3.0 backport

Thanks. r=LpSolit

Comment 30

[Frédéric Buclin]

3.0.3:

Checking in xml/administration.xml;
/cvsroot/mozilla/webtools/bugzilla/docs/xml/administration.xml,v  <--  administration.xml
new revision: 1.70.2.10; previous revision: 1.70.2.9
done
Checking in xml/installation.xml;
/cvsroot/mozilla/webtools/bugzilla/docs/xml/installation.xml,v  <--  installation.xml
new revision: 1.136.2.10; previous revision: 1.136.2.9
done

Comment 31

[Frédéric Buclin]

Attachment: small fixes for tip

Here are 2 small fixes for tip, taken from my previous reviews for 3.0.

Comment 32

[Frédéric Buclin]

small fixes for tip:

Checking in docs/xml/administration.xml;
/cvsroot/mozilla/webtools/bugzilla/docs/xml/administration.xml,v  <--  administration.xml
new revision: 1.87; previous revision: 1.86
done