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 Sun, 24 Apr 2016 21:18:55 GMT
2016-04-22 8:19 GMT+02:00 Luca Toscano <toscano.luca@gmail.com>:

> +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 :)
>
>
New version just committed, examples:

https://httpd.apache.org/docs/trunk/mod/mod_lua.html
https://httpd.apache.org/docs/trunk/mod/event.html

Luca

Mime
View raw message