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

Jan Schneider jan at horde.org
Thu Aug 4 07:39:07 UTC 2011 

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

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

More information about the dev mailing list