Re: Patch formalization

Dear Alejandro,

I cannot point all the differences since I didn't have the chance to go 
through the cvs manual in detail. In the main link for the User Manual you 
have a "Stable" and "Development" version, with the "Stable" more recent 
than the development.

I am thinking that "Development" should become "Latest CVS" and be updated 
daily. I don't know what need there is for "old" "unstable" versions like 
1.3.2, but if there is, a link to archives should be provided for old 
documentation and sources.

Here is the list of differences that made me suspect discrepancies between 
1.4.1 docs and CVS source. It is not exchaustive, since I stopped using it 
once I discovered it. Mind you it was not easy or pleasant, since i had to 
walk the source code with the debugger to resolve them.

1) Table 3.1. Core group variables. store-file. Bearebox when it starts 
states that it is deprecated and to use store-location and store-type. OK, 
so I used them, except that I didn't know what values to put for store-type 
and bearerbox would give me an error: unknown "store-type" found. Thinking 
that store-type variable was not supported, I even send an email to the 
list. Had to figure it out from the sources.

2) To use ppg one has to specify smsbox-id. Once you specify smsbox-id you 
have to specify smsbox-routing. I was getting error messages from bearerbox 
like "Empty lists" etc. I had to find about smsbox-routing searching the 
web. The CVS document needs also to be updated for that.

Table 6-7. smsbox-routing variables and example. Variables listed are 
"smsc-ids" and "shortcut". When tried either one I would get "unsupported 
variable "smsc-ids" in line...". I had again to go through the debugger to 
make it work.

Bottom line. I didn't trust the documentation and didn't know of anything 
better to use until I saw your email. With help from the list not very 
dependable, I was thinking that I had to go through the sources every single 
time. Not very pleasant prospect.

BR,
Nikos
----- Original Message ----- 
From: "Alejandro Guerrieri" <[email protected]>
To: "Nikos Balkanas" <[email protected]>
Cc: "Kannel Devel" <[email protected]>
Sent: Monday, November 24, 2008 3:41 PM
Subject: Re: Patch formalization


Nikos,

Could you please point out what differences between 1.4.1
functionality and what manual's says did you find? There shouldn't be
any.

Regarding documentation for the CVS code, check on 
http://www.kannel.org/download.shtml
, on section "Daily Snapshots". You'll find it there.

Regards,

Alejandro

El 24/11/2008, a las 04:42 a.m., Nikos Balkanas escribiΓ³:

> Dear Alejandro,
>
> Unfortunately not having docbook on my minimal server to generate  the 
> latest User Manual, I opted for the HTML version in the site. A  month ago 
> it was version 1.4.0, now it is renamed to 1.4.1. I  believe it must be 4 
> yrs old. It is labeled as "more current" than  the development. Not 
> finding anything else, I figured out that it  was the latest.
>
> It caused me a lot of grief. I tried to configure my box using the  wrong 
> manual and had to resort to the source code many times over.  Thanks for 
> pointing out the more current XML sources, it would be  even nicer to get 
> the CVS manual out to the web (CVS, Stable,  Development).
>
> BR,
> Nikos
>
> ----- Original Message ----- From: "Alejandro Guerrieri" 
> <[email protected]
> >
> To: "Nikos Balkanas" <[email protected]>
> Cc: "Kannel Devel" <[email protected]>
> Sent: Saturday, November 22, 2008 4:04 AM
> Subject: 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
>>>> -------------------------------------------------------------------
>>>
>>>
>>
>