69631 - Documentation fixes.

Status: VERIFIED FIXED

(Bugzilla :: Bugzilla-General, defect)

Description

[Matthew Tuck [:CodeMachine]]

Section 4 and 5 of the README are out of date.

Comment 1

[Matthew Tuck [:CodeMachine]]

Me take.

Comment 2

[Matthew Tuck [:CodeMachine]]

Attachment: First hit at cleaning the README.

Comment 3

[Matthew Tuck [:CodeMachine]]

Can I get a review of these changes, and possibly suggestions for further
changes, please?

The above patch basically consists of some textual cleanups (all full stops now
have two spaces after, all lines wrap no later than 78 columns) and a cleanup of
the two incorrect sections.

Comment 4

[Jacob Steenhagen]

Ok, applied that patch and did a quick read-through (I read more this time than
when I installed it ;)...

 1) In the section about running on NT, it might be good to make mention of bug
    17566.
 2) Somewhere around section 1.3, make mention of Bundle::Bugzilla (which should
    allow you to skip to step 1.9)
 3) In section 1.9, it might be worth mentioning that the default configuration 
    of apache restricts non-script files in the cgi-bin directory (at IIRC).
 4) Also in 1.9, srm.conf has been merged into httpd.conf in newer versions.
 5) The section where it first talks about ./checksetup.pl seems to read a bit
    rough (maybe it's just me)
 6) Near the end of section 4, it might be a good idea to mention that 
    ./checksetup.pl can be run at any time w/out causing harm.
 7) Somewhere in the apendix area, it may be good to mention DATABASE.txt and 
    the Query Cookbook - http://www.mozilla.org/projects/bugzilla/queries.html

Comment 5

[Jacob Steenhagen]

I just did a fresh-install of bugzilla and it asked for the maintainer on the
second run of ./checksetup.pl, not the first.

Comment 6

[Dave Miller [:justdave]]

Oh, first time all it did was create localconfig, right?  If so, then this is 
correct.  Because it can't even connect to the database until you've verified 
that localconfig is set up correctly, and it has to connect to the database to 
create the maintainer.

Comment 7

[Matthew Tuck [:CodeMachine]]

Attachment: Second hit at cleaning up the README.

Comment 8

[Matthew Tuck [:CodeMachine]]

OK, I fixed Jake's 6 and the mentioning of the admin account too early.

Jake, can you please do 2, 3, 4 & 7 yourself because I don't feel qualified to
do those.

As for the NT issues, should we refer to the Bugzilla guide instead?  I know
there's more than one NT bug currently filed.

Please comment more on 5, as I don't know whether you're referring to my
additions or the original text, or the interactions between the two.

Can anyone tell me if this paragraph is still relevant:

    If you have played with MySQL permissions, rather than just opening it
 wide open as described above, then you may need to tweak the Bugzilla
 code to connect appropriately.

given that most everything is handled in localconfig now.

Also, I'd like the start of the tweaking section to be thoroughly reviewed as I
wasn't totally comfortable with what I was doing there.

Comment 9

[Dave Miller [:justdave]]

you no longer have to tweak bugzilla code to get it to work with a database with 
a password.  It will handle it now.

Comment 10

[Jacob Steenhagen]

5 doesn't seem to be an issue anymore.  I think moving the maintainer creation
stuff must'av done it.

In Section 4, after the connection settings, here's my reccommended text:

Once you are happy with the settings, re-run ./checksetup.pl.  On this second
run, it will to the real work of creating the database.  It will also prompt you
to create an administrator account.

Should everything work, you'll have a nearly empty copy of the bug tracking
system along with one account for Administration.

Notes on ./checksetup.pl:
This script is designed so it can be run at any time without causing harm.  You
should run it after any upgrade to bugzilla.

This script requires that the filesystem it's running on fully support file
locking via flock().  It has been know to fail on NFS mounts after displaying
"Now regenerating the shadow database for all bugs."

---
Also, the part where it mentions flock() just before section 4 should be removed
(the lock-up is a second time+ issue, not a first time where it's mentioned now)

Is the bugzilla guide in its "final resting place"?  If it is, then we should be
able to link to it w/out a problem.

As far as the other things that are listed, I don't think it's that big a deal
if they don't make it for 2.12.

CC'ing the doc's guy to see if he has any additional input.

Comment 11

[Dave Miller [:justdave]]

moving to real milestones...

Comment 12

[Matthew Tuck [:CodeMachine]]

Attachment: Third hit (strike?) at cleaning up the Bugzilla README.

Comment 13

[Matthew Tuck [:CodeMachine]]

OK, I've taken the comments into account and done my own thing.

Please let me know if anything else needs to be done for 2.12 so we can get this
to a final review via Tara ASAP.

Comment 14

[Tara Hernandez]

Let me state for the record that the concept of a README patch just amused the
hell out of me.

:)

Reviewing now.

Comment 15

[Matthew Barnson]

Matty:
  I really want to get rid of having all the documentation in the root level folder.
  The README is largely incorporated into the Bugzilla Guide now.  I am checking
it in tonight (all 1MB+ of documentation), and will update it with the
information from this Diff.  I just want to make sure we are not at
cross-purposes.  Is now an appropriate time to simply modify the
$BUGZILLA_HOME/README file to say "The Bugzilla README can now be found in three
formats under docs/html/README.html, docs/txt/README.txt, and
docs/sgml/README.sgml"?

Comment 16

[Matthew Barnson]

The diff looks good.  Matty, I am going to take this bug from you so I can get
the fix in with my Bugzilla Guide and README checkin tonight or tomorrow
morning.  I had to make a change to reflect the detailed Windows NT
instructions; might as well apply these diffs too.

Comment 17

[Matthew Tuck [:CodeMachine]]

Personally, I have no problem with, and would prefer, incorporating the README
into the Bugzilla Guide and removing the documentation from the README file.

Editing text files is very annoying, and reading HTML is easier.

Comment 18

[Matthew Barnson]

This is done.
The README was left in for the 2.12 distribution, but when time permits I will
be moving the README contents to the Guide.  For now, the canonical UNIX
installation document remains the README.  I also undertook some general cleanup
of the file, and improved database instructions (I totally threw out that
abominable permissions suggestion in section 3 and replaced it with some
sensible defaults).

Comment 19

[Gervase Markham [:gerv]]

Doc bug - VERIFIED.

Gerv

Comment 20

[Dave Miller [:justdave]]

Moving closed bugs to Bugzilla product