Re: Patch formalization

Nikos,

The manual on the site is rendered to HTML, PDF and other formats from  
a DocBook XML file, userguide.xml available on Kannel's source code.  
Its content has been updated a lot of times.

Regards,

Alejandro Guerrieri

El 21/11/2008, a las 11:40 p.m., Nikos Balkanas escribió:

> Hi Alej
>
> I knew of only the HTML manual in the site, some ~8y old. Is there a  
> more recent version in XML?
>
> BR,
> Nikos
> ----- Original Message ----- From: "Alejandro Guerrieri" <[email protected] 
> >
> To: "Nikos Balkanas" <[email protected]>
> Cc: "Stipe Tolj" <[email protected]>; <[email protected]>
> Sent: Saturday, November 22, 2008 2:23 AM
> Subject: Re: Patch formalization
>
>
> Well, for the last few years, though maybe not a strict policy,
> patches that modified the functionality were always suggested to have
> a patch to the documentation XML as well.
>
> I remember many patches that were put on hold until a proper
> documentation patch was in place as well.
>
> I also agree with that: Patches that modify user-interface, implement
> new functionality or modify what the manual says in any way should
> always include a patch for documentation.
>
> The quality of the documentation being added is as important as the
> patch itself IMO. Otherwise, we'd end having to check the source code
> to figure out functionality, completely missing the point of having
> documentation on the first place.
>
> Regards,
>
> Alejandro Guerrieri
>
> El 21/11/2008, a las 10:08 p.m., Nikos Balkanas escribió:
>
>> Hi Stipe,
>>
>> Very nicely done, especially the mantis system. But you are  
>> missing  a very important point. What I was driving at was that any  
>> submitted  patch should include a patch also of the manual. This is  
>> already in  HTML form and needs to be in the CVS, if not already.
>>
>> It might take some time to setup mantis and the HTML, time that the  
>> manual shouldn't have to wait. The manual can be implemented as  
>> soon  as a decision is reached.
>>
>> BR,
>> Nikos
>>
>> ----- Original Message ----- From: "Stipe Tolj" <[email protected]>
>> Cc: <[email protected]>
>> Sent: Saturday, November 22, 2008 1:33 AM
>> Subject: Re: Patch formalization
>>
>>
>>> Nikos Balkanas schrieb:
>>>> Hi,
>>>>
>>>> I see a lot of patches going around on this group. I would like to
>>>> propose not to accept patches unless the relevant points are   
>>>> updated in
>>>> the documentation. Furthermore I suggest that this should be a
>>>> distributed effort by each submitter. Too much I think has  
>>>> fallen  on the
>>>> shoulders of Alex trying to verify the code, to be able to   
>>>> maintain the
>>>> documentation as well. Of course that would mean that documentation
>>>> needs to get in the CVS if not already there. And definitely this
>>>> applies only to new features/improvements, not to bug fixes.
>>>>
>>>> This should facilitate also traffic in the group, inasmuch new   
>>>> users,
>>>> like me, ask, over and over again, a lot of questions that are   
>>>> either
>>>> outdated or nonexistent in the manual. A searchable mail list   
>>>> would be
>>>> an improvement but could not substitute for a current manual.
>>>>
>>>> Any comments?
>>>
>>> agreed.
>>>
>>> We have those 'formal guidelines' for [PATCH] submission, but I   
>>> guess it
>>> wouldn't hurt to setup a simple .html page on the web site to  
>>> make  them more
>>> universal available.
>>>
>>> Main policy items, IMO:
>>>
>>> 1. where to submit: devel@ list.
>>> 2. subject prefixing: [PATCH] my foobar patch that does
>>> 3. form of the patch: diff -u against CVS HEAD at 'gateway' root
>>> 4. form of source code: gateway/doc/CodingStyle should be obeyed
>>> 5. explanation of the patch: the more the reviewers "understand"   
>>> the easier to
>>> review, and then vote. This enhances the patch post to commit cycle
>>> 6. all 'open' patches should be maintained in mantis (bug tracking  
>>> system) too,
>>> at least as reference (i.e. via the mailing list Msg-Id) and the   
>>> patch itself
>>> attachment. This helps us to maintain a single point of view to  
>>> see  what pathces
>>> are still pending.
>>> 7. any patch that introduces a behavior change needs votes, hence  
>>> consensus of
>>> the group.
>>> 8. obvious bug fixes can be committed directly, but should be   
>>> noticeable to the
>>> devel@ list with the same subject prefixing.
>>>
>>> any more? or comments on these?
>>>
>>> Stipe
>>>
>>> -- 
>>> -------------------------------------------------------------------
>>> Kölner Landstrasse 419
>>> 40589 DΓΌsseldorf, NRW, Germany
>>>
>>> tolj.org system architecture      Kannel Software Foundation (KSF)
>>> http://www.tolj.org/              http://www.kannel.org/
>>>
>>> mailto:st_{at}_tolj.org           mailto:stolj_{at}_kannel.org
>>> -------------------------------------------------------------------
>>
>>
>