[dev] [commits] Horde branch master updated. 4fd2c31bf65accb6717f1330cbd8cc2b3ef1c9ba

Gunnar Wrobel wrobel at horde.org
Thu Aug 4 09:22:31 UTC 2011 

Quoting Jan Schneider <jan at horde.org>:

> Zitat von Gunnar Wrobel <wrobel at horde.org>:
>
>> Quoting Jan Schneider <jan at horde.org>:
>>
>>> Zitat von Gunnar Wrobel <wrobel at horde.org>:
>>>
>>>> Quoting Michael J Rubinsky <mrubinsk at horde.org>:
>>>>
>>>>> Quoting Michael M Slusarz <slusarz at horde.org>:
>>>>>
>>>>>> Quoting Michael J Rubinsky <mrubinsk at horde.org>:
>>>>>>
>>>>>>> Quoting Chuck Hagenbuch <chuck at horde.org>:
>>>>>>>
>>>>>>>> Quoting Jan Schneider <jan at horde.org>:
>>>>>>>>
>>>>>>>>> Please add a changelog and bump the minor api and package version.
>>>>>>>>
>>>>>>>> Sure thing. Can someone refresh me on the current best  
>>>>>>>> practice for doing so (package vs. horde CHANGES), and if  
>>>>>>>> there's a components helper to do so?
>>>>>>>
>>>>>>> Application changes go into both the app's package.xml _and_  
>>>>>>> the apps' CHANGES file. For framework libraries, the change  
>>>>>>> log goes into the package's package.xml file as well as the  
>>>>>>> base horde app's CHANGES file.
>>>>>>
>>>>>> I (still) vehemently disagree with the latter statement.  It is  
>>>>>> tremendously confusing to put changelog entries in horde for  
>>>>>> things that don't live in horde.
>>>>
>>>> I agree here.
>>>>
>>>>>>
>>>>>> Sure enough, I was completely confused by a recent changelog  
>>>>>> entry that appeared in the horde changelog.  I think mjr fixed  
>>>>>> something in Horde_Imap_Client, but then put a changelog entry  
>>>>>> in Horde.  Besides the fact that this really makes no sense  
>>>>>> from a practical standpoint (Horde_Imap_Client is *completely*  
>>>>>> independent from Horde the application), it also made no sense  
>>>>>> because the fix affected nothing in Horde.  It affected nothing  
>>>>>> in framework for that matter (outside of the Imap Client  
>>>>>> package).  I spent a good amount of time trying to figure out  
>>>>>> what this fixed in Horde, and I'm probably the person most  
>>>>>> familiar with the imap code.  That is a terrible sign if that  
>>>>>> occurs.
>>>>>
>>>>>> I understand the motive to put everything into a single, easily  
>>>>>> discoverable location.  But you simply CAN'T do this if the  
>>>>>> underlying theory is unsound.  Which it is here.  We made the  
>>>>>> decision to make framework packages != horde the application.   
>>>>>> So we can't use the Horde changelog for these entries.  That is  
>>>>>> the unfortunate, but necessary, side effect of that decision.
>>>>>
>>>>> I agree with what you are saying to a certain extent. I find  
>>>>> myself sometimes getting confused regarding our releases. We  
>>>>> release framework packages independently - with version numbers  
>>>>> that do not relate to the version of Horde as a whole - when the  
>>>>> situation demands it. On the other hand we also talk about  
>>>>> "Horde 4" (or 4.1 or 5 or ...) in the context of a coordinated  
>>>>> release that contains all the framework packages. We also use  
>>>>> this coordinated version number as a way of  
>>>>> determining/enforcing BC.
>>>>>
>>>>> When building releases, or even discussing bugs/missing  
>>>>> functionality with our users, it is EXTREMELY helpful to have a  
>>>>> single place to include these changes. If you are looking for  
>>>>> the authoritative changelog for a single package, look at  
>>>>> package.xml. If you are looking for an overview of what has  
>>>>> changed in "Horde 5", look in CHANGES.
>>>>>
>>>>>> A possible alternative: a script that gathers all changelog  
>>>>>> entries from packages relied on by an application that have  
>>>>>> changed since the previous release date of the prior  
>>>>>> application version.  But these entries must be  
>>>>>> logically/physically distinguished from the changes made in the  
>>>>>> horde application itself (i.e. files living under horde/ in the  
>>>>>> master repo).
>>>>>
>>>>> I'm not sure I would agree with putting these entries in _every_  
>>>>> application. This would still lead to having to look in multiple  
>>>>> CHANGES files, as well as potentially having the same entry  
>>>>> appear in _every_ application. How about introducing a new  
>>>>> changelog file, that lives in Horde that contains only framework  
>>>>> related changes?  Still not ideal, but maybe a compromise that  
>>>>> we can all live with?
>>>>
>>>> But in principle this list still wouldn't apply to "horde". If  
>>>> something is fixed in Horde_Date_Parser this may be relevant for  
>>>> a user that installed "kronolith", but not for a user that  
>>>> installed only "imp". Combining *everything* in "horde" would  
>>>> clutter the log to some extent.
>>>>
>>>> In addition we do not force users to upgrade single PEAR  
>>>> packages. It is the default mode when running "pear upgrade" but  
>>>> in principle you could upgrade "kronolith" without upgrading the  
>>>> dependencies. So a combined log might always be somewhat incorrect.
>>>>
>>>> Getting a change log that is really "correct" will only be  
>>>> possible by generating it from the users installation.
>>>>
>>>> One could add the functionality to Horde_Pear with another script  
>>>> in "horde" that aggregates a changelog from a users installation.  
>>>>  We could add a note to the CHANGES files that framework changes  
>>>> can be obtained with the command "horde-changes" or some such. Or  
>>>> we include instruction on how to run this script as an optional  
>>>> step in our upgrade instructions - it would then compile a change  
>>>> log in the installation. Maybe PEAR would also allow us to  
>>>> suggest this as a post-install-script after upgrade - though I  
>>>> don't know if that is available for upgrades.
>>>>
>>>> I'm not certain this is the best solution as it would mean  
>>>> additional work on the users side just to get the change log  
>>>> which not every user/admin might actually look at. So aggregating  
>>>> the change log on our side - even if it is somewhat cluttered or  
>>>> incorrect - might still be the better variant. I just wanted to  
>>>> suggest this alternative option.
>>>>
>>>> In any case the aggregation should be automated. If it happens on  
>>>> our side the "release" helper of components would be the right  
>>>> place for it.
>>>
>>> How about something like this:  
>>> http://git.horde.org/horde-git/-/commit/fec2ad46dd2d13fe3503742ee6d2bfee9ad28bcd
>>
>> It helps indicating that these log entries are something other than  
>> the main list of changes and is in line what you do for the  
>> bundles. For now this looks like a reasonable way to do it.
>>
>> In the long run I would still like to add a script that collects a  
>> change log on the user side. And maybe we could add a note in the  
>> CHANGES file on how to use this script to get a precise log for the  
>> actual installation.
>
> I don't like that idea. I'm pretty sure that most users won't check  
> the CHANGES files often after upgrading, but rather before, either  
> from the application docs on the website, or from changelog link in  
> the announcement message.

Ah, I didn't see this use case for the CHANGES file before. In fact I  
was asking myself in which way the file is primarily being used but  
didn't take the time to consider the various options. What you say  
makes a lot of sense. Now I totally agreee that the entries should be  
in there.

If "horde" gets the change log entries from the dependencies why are  
they lacking from the applications and only reappear in the bundles?

> If this list is going to be built automatically somewhere, it has to  
> happen during release time. But then again, if we use such a  
> separation like I suggest in CHANGES, this could already be done  
> easily with the "horde-components changes" command.

Yes, probably be the best way. I wouldn't mind if each framework  
change log entry in horde/docs/CHANGES would be annotated with the  
corresponding framework package version. But that would get too  
complex as the final version number is only know when the release is  
being pushed.

Cheers,

Gunnar



>
>> But as far as I know no user complained about the change log so far  
>> and so this does not seem too urgent.
>>
>> Cheers,
>>
>> Gunnar
>>
>>>
>>> Jan.
>>>
>>> -- 
>>> Do you need professional PHP or Horde consulting?
>>> http://horde.org/consulting/
>>>
>>> -- 
>>> Horde developers mailing list
>>> Frequently Asked Questions: http://horde.org/faq/
>>> To unsubscribe, mail: dev-unsubscribe at lists.horde.org
>>
>> -- 
>> Core Developer
>> The Horde Project
>>
>> e: wrobel at horde.org
>> t: +49 700 6245 0000
>> w: http://www.horde.org
>>
>> pgp: 9703 43BE
>> tweets: http://twitter.com/pardus_de
>> blog: http://log.pardus.de
>
>
> Jan.
>
> -- 
> Do you need professional PHP or Horde consulting?
> http://horde.org/consulting/
>
> -- 
> Horde developers mailing list
> Frequently Asked Questions: http://horde.org/faq/
> To unsubscribe, mail: dev-unsubscribe at lists.horde.org

-- 
Core Developer
The Horde Project

e: wrobel at horde.org
t: +49 700 6245 0000
w: http://www.horde.org

pgp: 9703 43BE
tweets: http://twitter.com/pardus_de
blog: http://log.pardus.de

More information about the dev mailing list