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

[Gunnar Wrobel]

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.

Cheers,

Gunnar


>
>
> -- 
> mike
>
> The Horde Project (www.horde.org)
> mrubinsk at horde.org
>
> -- 
> 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