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

[Michael J Rubinsky]

Quoting 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.

As I replied before, I agree. This seems like a great compromise.

> 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.

Don't agree here. At least, not as an authoritative CHANGES file goes.  
This would generate different CHANGES files on different  
installations. I think we should maintain an authoritative CHANGES  
file. Plus, the main reason (IMO) for a changelog from a user's point  
of view is to see what changed *before* you install/upgrade your  
software. This would be generated after the fact, correct?

-- 
mike

The Horde Project (www.horde.org)
mrubinsk at horde.org