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

Thu Aug 4 11:57:42 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 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?

Because 1) of historical reasons. In the past the framework packages  
were bundled with Horde, so it made sense to log the changes there.  
This is just keeping the old status quo, though we don't bundle  
anymore. And 2) it would create a lot of duplicate entries if we  
logged all dependencies in each application.

For the groupware bundles I simply aggregate all CHANGES from all  
updated applications since the last release. So sometimes entries for  
one application are missing, if it hasn't been released since then, or  
sometimes there are entries for two versions. And I manually remove  
duplicate entries, e.g. if some change has been implemented across all  
applications. This sounds more complicated than it is, so it doesn't  
need to be automated.

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

Jan.

-- 
Do you need professional PHP or Horde consulting?
http://horde.org/consulting/