httpd-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Luca Toscano <toscano.l...@gmail.com>
Subject Re: Proposal: add a permanent "Bugfix checklist" section to all manual pages
Date Fri, 22 Apr 2016 06:19:17 GMT
+docs@

2016-04-20 23:25 GMT+02:00 Marion & Christophe JAILLET <
christophe.jaillet@wanadoo.fr>:

> Le 20/04/2016 19:37, Luca Toscano a écrit :
>
>
>
> 2016-04-18 21:46 GMT+02:00 Luca Toscano <toscano.luca@gmail.com>:
>
>>
>>
>> 2016-04-12 11:38 GMT+02:00 Luca Toscano < <toscano.luca@gmail.com>
>> toscano.luca@gmail.com>:
>>
>>> Hi docs@!
>>>
>>> I have been thinking a way to inform users about our best practices when
>>> finding inconsistencies in the docs, namely checking CHANGES and Bugzilla
>>> first. Most of the times occasional users (or even experienced ones) tend
>>> to forget where the changelog is, if httpd uses bugzilla or not, etc.. so
>>> it would be great in my opinion to add a "reminder" in our manual pages.
>>> The attached patch will add a little section in the right column (right
>>> below "See also") to provide the aforementioned links.
>>>
>>> Position, wording, etc.. can be changed of course, this email is only
>>> meant to discuss the idea. If you don't like it, just state it out loud and
>>> I'll drop it :)
>>>
>>> Let me know your thoughts!
>>>
>>> Luca
>>>
>>>
>> Restarted from the first email to avoid a quoting mess. I attached the
>> final patch that would basically add the "Bugfix checklist" section before
>> "see also" on each module's page. I wanted to restrict the scope of this
>> patch to the places in which occasional users will benefit more rather than
>> adding it to the whole documentation.
>>
>> Christophe, André, Rich: if you want to review the patch it would be
>> really great. If anybody feels very strong against it I'll drop it.
>>
>
> Committed in trunk, you can see some examples in:
>
> https://httpd.apache.org/docs/trunk/mod/event.html
> https://httpd.apache.org/docs/trunk/mod/mod_lua.html
>
> Some comments made so far:
>
> - add the module's name to the bugzilla link (Open bugs) to visualize only
> relevant bugs
>
> +1
> Having a link that shows 1567 bugs, some opened in 2004 is just bad, IMHO.
> But having, from the doc, a link to only corresponding items would be,
> still IMHO, great.
>

I agree, the list of 1567 bugs is bad but at least it was a starting point
to let the user know about bugzilla and what to set in the search bar to
find the httpd bugs (I know straightforward but still..). Thanks to Jacob
Champion I have a working version that produces links for modules only
(using {name} in the xsl), but I need to resolve a couple of issues:

1) doc pages like "event" are tagged as "mpm_event" in bugzilla, but the
{name} is event. So I'll need to check corner cases and evaluate some
workaround to make everything works correctly. Don't expect to be a lot of
work.

2) make sure that all the modules have a related component in bugzilla.


> - move Httpd to HTTPD
>
> Having it consistent in the doc would indeed be nice. (we currently have
> many ways to give the name of our web server)
>

Definitely, I thought that Httpd was fine but HTTPD sounds better.


>
>
> - think about moving "Bugfix checkilist" to "Developer Resources" (still
> thinking about this one because I'd like to keep something that connect the
> user looking for a bug to these links).
>
> Or maybe just remove the tittle and move it just before "Comment"?
>

Could be an option, I wanted to display something that connects the thought
of "ah httpd has a bug!" with "ah I need to check this link probably" while
browsing a doc page. We'll see, the final version is far from complete!


> Maybe, use httpd.docs entity instead of hard coded 2.4 (or equivalent) and
> maybe even have a special case for trunk (link not displayed? Link to 2.4
> CHANGES?)
>
> Linking to http://httpd.apache.org/dev/dist/ may be bad. Are we sure that
> this folder always have a CHANGES_2.4 file? What about trunk doc? (or even
> 2.2 ?)
> Maybe http://www.apache.org/dist/httpd/CHANGED_2.<version> would be
> better (this is the one used on the main httpd.a.o page)
>

You are completely right, I will study a better solution. The initial
thought was to avoid applying the change to 2.2 concentrating on 2.4, this
is why I have hardcoded.


>
> Maybe "Known issues" would be better that "open(ed) bugs" ?
>

+1


>
> While at it, maybe add a link to report a bug fir this module ?
>

+1 great idea!

Thanks a lot for the great feedback! Really appreciated! I'll start working
on your suggestion as soon as possible and report back to this thread once
I'll have an update :)

Luca

Mime
View raw message