Devmanual text on ChangeLogs

classic Classic list List threaded Threaded
50 messages Options
123
Reply | Threaded
Open this post in threaded view
|

Devmanual text on ChangeLogs

Petteri Räty-2
http://devmanual.gentoo.org/ebuild-writing/misc-files/changelog/index.html

There doesn't seem to be a common opinion on what the policy for
ChangeLog entries is. See:

http://archives.gentoo.org/gentoo-dev/msg_f829da2375f1ceab766a800913cc4998.xml

I propose a simple new text: "Every commit should have an entry in
ChangeLog." If we eventually autogenerate them from git logs this would
happen any way (unless some kind of filtering system is in the middle)
so we could already start now. I think it's better to have more than
less information available to users.

Regards,
Petteri


signature.asc (918 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Devmanual text on ChangeLogs

Samuli Suominen-4
On 04/30/2011 11:46 AM, Petteri Räty wrote:

> http://devmanual.gentoo.org/ebuild-writing/misc-files/changelog/index.html
>
> There doesn't seem to be a common opinion on what the policy for
> ChangeLog entries is. See:
>
> http://archives.gentoo.org/gentoo-dev/msg_f829da2375f1ceab766a800913cc4998.xml
>
> I propose a simple new text: "Every commit should have an entry in
> ChangeLog." If we eventually autogenerate them from git logs this would
> happen any way (unless some kind of filtering system is in the middle)
> so we could already start now. I think it's better to have more than
> less information available to users.
>
> Regards,
> Petteri
>

"Every new file, and modification to existing file should have an entry
in ChangeLog." to skip the proper ChangeLog-less removals.

Reply | Threaded
Open this post in threaded view
|

Re: Devmanual text on ChangeLogs

Ulrich Mueller-2
In reply to this post by Petteri Räty-2
>>>>> On Sat, 30 Apr 2011, Petteri Räty wrote:

> I propose a simple new text: "Every commit should have an entry in
> ChangeLog."

This would throw the baby out with the bath water.

I won't clutter ChangeLogs with useless entries for whitespace changes
or spelling fixes in comments, for example. They already account for a
considerable (too large?) percentage of the portage tree [1], and we
shouldn't blow them up further by adding useless information.

Ulrich

[1] http://blog.flameeyes.eu/2009/09/28/the-size-of-the-gentoo-tree
    (this is from 2009, so probably it's even worse now)

Reply | Threaded
Open this post in threaded view
|

Re: Devmanual text on ChangeLogs

Pacho Ramos
In reply to this post by Petteri Räty-2
El sáb, 30-04-2011 a las 11:46 +0300, Petteri Räty escribió:

> http://devmanual.gentoo.org/ebuild-writing/misc-files/changelog/index.html
>
> There doesn't seem to be a common opinion on what the policy for
> ChangeLog entries is. See:
>
> http://archives.gentoo.org/gentoo-dev/msg_f829da2375f1ceab766a800913cc4998.xml
>
> I propose a simple new text: "Every commit should have an entry in
> ChangeLog." If we eventually autogenerate them from git logs this would
> happen any way (unless some kind of filtering system is in the middle)
> so we could already start now. I think it's better to have more than
> less information available to users.
>
> Regards,
> Petteri
>
I don't have a strong opinion about what option is the one I think the
best but, either way, could
http://www.gentoo.org/proj/en/devrel/handbook/handbook.xml?part=2&chap=5#doc_chap8 be updated also with the final decision? That is the doc I periodically review to remember exact steps when cleaning old packages.

Thanks a lot

signature.asc (205 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Devmanual text on ChangeLogs

Panagiotis Christopoulos
In reply to this post by Ulrich Mueller-2
On 11:07 Sat 30 Apr     , Ulrich Mueller wrote:
> ...
> I won't clutter ChangeLogs with useless entries for whitespace changes
> or spelling fixes in comments, for example. They already account for a
> considerable (too large?) percentage of the portage tree [1], and we
> shouldn't blow them up further by adding useless information.
> ...

  Taking the latest portage snapshot from a mirror, the sum* of the apparent
sizes of all its files (forgetting directories, filesystems. overhead
etc.) is ~189Mb. The sum of ChangeLog files is ~66Mb, that is a ~35%
fraction.
  Yes, I know this doesn't say much and I don't know the internals of
the rsync protocol (someone can say that communication lines are now better,
and cpu processing/disk space costs less than water/oil etc. so what
are we talking about?), however it is a fact, if anyone cares. If I
find a 1-year old portage snapshot I may calculate better statistics based
on fixed number of ChangeLogs that existed then and now to see how they
increased over the time.

*doing very quick calculations
--
Panagiotis Christopoulos ( pchrist )
    ( Gentoo Lisp Project )

attachment0 (204 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Devmanual text on ChangeLogs

pva0xd
In reply to this post by Samuli Suominen-4
В Сбт, 30/04/2011 в 12:02 +0300, Samuli Suominen пишет:
> On 04/30/2011 11:46 AM, Petteri Räty wrote:
> > I propose a simple new text: "Every commit should have an entry in
> > ChangeLog."

Nonfunctional commits should not be recored in ChangeLog. Personally I
quite frequently add URLs of upstream bug reports in ChangeLog. I don't
think this addition should be recorded in ChangeLog.

> > If we eventually autogenerate them from git logs this would
> > happen any way (unless some kind of filtering system is in the middle)
> > so we could already start now.

Without filtering system ChangeLogs are useless. Also I need some way to
edit ChangeLogs manually.

> "Every new file, and modification to existing file should have an entry
> in ChangeLog." to skip the proper ChangeLog-less removals.

Removal is quite functional change so it should be recored.

--
Peter.


Reply | Threaded
Open this post in threaded view
|

Re: Devmanual text on ChangeLogs

Diego Elio Pettenò
In reply to this post by Ulrich Mueller-2
Il giorno sab, 30/04/2011 alle 11.07 +0200, Ulrich Mueller ha scritto:
>
> I won't clutter ChangeLogs with useless entries for whitespace changes
> or spelling fixes in comments, for example. They already account for a
> considerable (too large?) percentage of the portage tree [1], and we
> shouldn't blow them up further by adding useless information.

If you read the last paragraph in my suggestion was to cycle the logs...

--
Diego Elio Pettenò — Flameeyes
http://blog.flameeyes.eu/


Reply | Threaded
Open this post in threaded view
|

Re: Re: Devmanual text on ChangeLogs

Panagiotis Christopoulos
On 14:28 Sat 30 Apr     , Diego Elio Pettenò wrote:
> If you read the last paragraph in my suggestion was to cycle the logs...
Maybe this would be better together with a mechanism (automatic?) to keep the
complete ChangeLogs (as they are now) somewhere (but not in the main
tree). Sometimes, full history/ChangeLog can be useful, eg. when you
want to see quickly how old a package in the tree is, or find bug numbers of
fixes you may want to recheck etc etc.

--
Panagiotis Christopoulos ( pchrist )
    ( Gentoo Lisp Project )

attachment0 (204 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Devmanual text on ChangeLogs

Markos Chandras-2
In reply to this post by Samuli Suominen-4
On Sat, Apr 30, 2011 at 12:02:35PM +0300, Samuli Suominen wrote:

> On 04/30/2011 11:46 AM, Petteri Räty wrote:
> > http://devmanual.gentoo.org/ebuild-writing/misc-files/changelog/index.html
> >
> > There doesn't seem to be a common opinion on what the policy for
> > ChangeLog entries is. See:
> >
> > http://archives.gentoo.org/gentoo-dev/msg_f829da2375f1ceab766a800913cc4998.xml
> >
> > I propose a simple new text: "Every commit should have an entry in
> > ChangeLog." If we eventually autogenerate them from git logs this would
> > happen any way (unless some kind of filtering system is in the middle)
> > so we could already start now. I think it's better to have more than
> > less information available to users.
> >
> > Regards,
> > Petteri
> >
>
> "Every new file, and modification to existing file should have an entry
> in ChangeLog." to skip the proper ChangeLog-less removals.
>
I am actually with Samuli on this. Unless there is a particular reason
for removing a package, I don't see any point of documenting this change anywhere.
What difference would it make to you if you see an entry " -foo-1.0
old". It makes absolutely no sense.

Regards,
--
Markos Chandras / Gentoo Linux Developer / Key ID: B4AFF2C2

attachment0 (853 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Re: Devmanual text on ChangeLogs

Paweł Hajdan, Jr.
In reply to this post by Panagiotis Christopoulos
On 4/30/11 3:05 PM, Panagiotis Christopoulos wrote:
> On 14:28 Sat 30 Apr     , Diego Elio Pettenò wrote:
>> If you read the last paragraph in my suggestion was to cycle the logs...
> Maybe this would be better together with a mechanism (automatic?) to keep the
> complete ChangeLogs (as they are now) somewhere (but not in the main
> tree). Sometimes, full history/ChangeLog can be useful, eg. when you
> want to see quickly how old a package in the tree is, or find bug numbers of
> fixes you may want to recheck etc etc.

Seconded. I sometimes read entire ChangeLogs, for example for abandoned
packages or packages I suspect to be abandoned, sometimes I read them
for fun, and so on.

I'm fine with shipping a trimmed down versions to users, but I think the
full version must be easy to access.

A possible solution would be to truncate the logs in the cvs->rsync
migration.


signature.asc (201 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Re: Devmanual text on ChangeLogs

Rich Freeman
On Sat, Apr 30, 2011 at 9:44 AM, "Paweł Hajdan, Jr."
<[hidden email]> wrote:
> I'm fine with shipping a trimmed down versions to users, but I think the
> full version must be easy to access.

If the changelogs were accessible via a predicable URL then a simple
command-line tool or portage option might display them on request.
echangeinfo cat/pkg is probably no harder for the average end-user to
type than less /usr/portage/cat/pkg/ChangeLog.

Rich

Reply | Threaded
Open this post in threaded view
|

Re: Devmanual text on ChangeLogs

Brian Harring-2
In reply to this post by Markos Chandras-2
On Sat, Apr 30, 2011 at 02:42:08PM +0100, Markos Chandras wrote:
> I am actually with Samuli on this. Unless there is a particular reason
> for removing a package, I don't see any point of documenting this change anywhere.
> What difference would it make to you if you see an entry " -foo-1.0
> old". It makes absolutely no sense.

Removing versions has implications for the depgraph which make having
it documented locally fairly required.  Broken dependencies is the
usual example, (consider developmental profiles), but it gets nastier
than that; consider a pkg depping on
|| ( =foo-1.0 !block-some-other-crap )

Yes that's a screwed up dep, but people come up with some weird
stuff- the point either way is that removal of 1.0 can have
implications beyond just the perceived cleanup.  Usage of --force in
conjunction with it makes it worse.

Not opposed to pruning the logs (every few years we seem to go cleanup
the offenders), but removals *matter* for the depgraph, thus
have been required to be documented long term.

~harrng

attachment0 (205 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Devmanual text on ChangeLogs

Alex Alexander
In reply to this post by Markos Chandras-2
On Sat, Apr 30, 2011 at 02:42:08PM +0100, Markos Chandras wrote:

> On Sat, Apr 30, 2011 at 12:02:35PM +0300, Samuli Suominen wrote:
> > On 04/30/2011 11:46 AM, Petteri Räty wrote:
> > > http://devmanual.gentoo.org/ebuild-writing/misc-files/changelog/index.html
> > >
> > > There doesn't seem to be a common opinion on what the policy for
> > > ChangeLog entries is. See:
> > >
> > > http://archives.gentoo.org/gentoo-dev/msg_f829da2375f1ceab766a800913cc4998.xml
> > >
> > > I propose a simple new text: "Every commit should have an entry in
> > > ChangeLog." If we eventually autogenerate them from git logs this would
> > > happen any way (unless some kind of filtering system is in the middle)
> > > so we could already start now. I think it's better to have more than
> > > less information available to users.
> > >
> > > Regards,
> > > Petteri
> > >
> >
> > "Every new file, and modification to existing file should have an entry
> > in ChangeLog." to skip the proper ChangeLog-less removals.
> >
> I am actually with Samuli on this. Unless there is a particular reason
> for removing a package, I don't see any point of documenting this change anywhere.
> What difference would it make to you if you see an entry " -foo-1.0
> old". It makes absolutely no sense.
There are times when you need to know where a version went. That alone
is enough to warrant updating the ChangeLog.

Having to check a second place through a slow interface sucks :)

--
Alex Alexander | wired
+ Gentoo Linux Developer
++ www.linuxized.com

attachment0 (853 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Devmanual text on ChangeLogs

Panagiotis Christopoulos
In reply to this post by Samuli Suominen-4
On 12:02 Sat 30 Apr     , Samuli Suominen wrote:
>
> "Every new file, and modification to existing file should have an entry
> in ChangeLog." to skip the proper ChangeLog-less removals.

There is something I can't undestand reading all the previous
discussions. You disagree with logging removals only because you don't
like the idea (you think it's useless information) or also because if
this becomes a policy, it will increase more the size of ChangeLogs? You
(and others) would still be negative if the problem with sizes etc. was
solved somehow?

--
Panagiotis Christopoulos ( pchrist )
    ( Gentoo Lisp Project )

attachment0 (204 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Devmanual text on ChangeLogs

Samuli Suominen-4
On 04/30/2011 11:39 PM, Panagiotis Christopoulos wrote:

> On 12:02 Sat 30 Apr     , Samuli Suominen wrote:
>>
>> "Every new file, and modification to existing file should have an entry
>> in ChangeLog." to skip the proper ChangeLog-less removals.
>
> There is something I can't undestand reading all the previous
> discussions. You disagree with logging removals only because you don't
> like the idea (you think it's useless information) or also because if
> this becomes a policy, it will increase more the size of ChangeLogs? You
> (and others) would still be negative if the problem with sizes etc. was
> solved somehow?
>

No, but because of the quantity of commits[1] as a result of maintaining
subset of issues tree wide at once (like libpng, jpeg, libnotify, *kit,
u{disks,power}, lcms, fixing missing includes due to toolchain changes,
adding some consts, imagine the rest ...)

... the time alone if you have to stop on each package to wait for
echangelog to get done just doubles the amount of time you have to put
into committing them. That's just not worth the effort.

So not only they are rather useless, and information you can easily get
from sources.gentoo.org, they take your time as well.

Reply | Threaded
Open this post in threaded view
|

Re: Devmanual text on ChangeLogs

Fabian Groffen-2
In reply to this post by Petteri Räty-2
On 30-04-2011 11:46:37 +0300, Petteri Räty wrote:

> http://devmanual.gentoo.org/ebuild-writing/misc-files/changelog/index.html
>
> There doesn't seem to be a common opinion on what the policy for
> ChangeLog entries is. See:
>
> http://archives.gentoo.org/gentoo-dev/msg_f829da2375f1ceab766a800913cc4998.xml
>
> I propose a simple new text: "Every commit should have an entry in
> ChangeLog." If we eventually autogenerate them from git logs this would
> happen any way (unless some kind of filtering system is in the middle)
> so we could already start now. I think it's better to have more than
> less information available to users.
Because everytime we need something more sophisticated people come up
with the holy git grail, here is the script to generate a
echangelog-style ChangeLog from CVS, right here, right now.

It's a naive implementation, but the output shows the differences
between the committed log, and what would be generated from CVS.  (The
usernames could be looked up easily, but I was too lazy to do that.)
People can use this to judge if "autogeneration from VCS" is a good
thing or not.

My conclusion is that you probably want to maintain the ChangeLog
manually.

I also attached a sample of the script output for net-p2p/transmission
for convenience.


--
Fabian Groffen
Gentoo on a different level

cvsps2changelog.sh (2K) Download Attachment
ChangeLog.gen (26K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

git? [was: Re: Devmanual text on ChangeLogs]

Eray Aslan-2
In reply to this post by Samuli Suominen-4
On Sun, May 01, 2011 at 12:06:47PM +0300, Samuli Suominen wrote:
> ... the time alone if you have to stop on each package to wait for
> echangelog to get done just doubles the amount of time you have to put
> into committing them. That's just not worth the effort.

Won't moving the tree to git will make this a moot discussion?  These and
similar solutions look more and more lika a band-aid to the defecencies
of cvs.

What is it really that is holding us up?  A dev to spearhead the move?

--
Eray Aslan
Developer, Gentoo Linux       eras <at> gentoo.org

Reply | Threaded
Open this post in threaded view
|

Re: Devmanual text on ChangeLogs

Fabian Groffen-2
In reply to this post by Samuli Suominen-4
On 01-05-2011 12:06:47 +0300, Samuli Suominen wrote:
> ... the time alone if you have to stop on each package to wait for
> echangelog to get done just doubles the amount of time you have to put
> into committing them. That's just not worth the effort.

Dude, you should have stuck with your argument that you just think
removal information isn't useful to anyone.  This argument is too funny
to be taken serious.


--
Fabian Groffen
Gentoo on a different level

Reply | Threaded
Open this post in threaded view
|

Re: Devmanual text on ChangeLogs

Panagiotis Christopoulos
In reply to this post by Samuli Suominen-4
On 12:06 Sun 01 May     , Samuli Suominen wrote:
> So not only they are rather useless, and information you can easily get
> from sources.gentoo.org, they take your time as well.

Then, let's change it to:
<snip>
"Every new file, and modification to existing file should have an entry
in ChangeLog. Though not mandatory, it is highly recommended that file
removals are also recorded the same way."
</snip>
to keep everyone happy until we deal with changelogs another way or
improve the committing process. I suppose most removals happen together
with additions, so it's not a big deal.
When only a removal happens, it will be in the developer's decision how
to handle the ChangeLog (as it was always). Don't get me wrong here. I
believe that removals should be recorded. Searching in ChangeLogs for
changes is much easier than visiting sources.gentoo.org, it's more
formal and you have a complete history of your package. However, I can
undestand what Samuli says, it can be frustrating and slow to deal with
echangelog when there is a "big commit load". But again, Can it be
slower than doing keywording/stabilizations? I don't remember any arch
tester to have complained about that but we complain about removals?
Maybe it's just my memory.

--
Panagiotis Christopoulos ( pchrist )
    ( Gentoo Lisp Project )

attachment0 (204 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: git?

Panagiotis Christopoulos
In reply to this post by Eray Aslan-2
On 13:09 Sun 01 May     , Eray Aslan wrote:
> What is it really that is holding us up?  A dev to spearhead the move?

I had the same question yesterday but after checking [1], I can tell
that it's not so simple as it seems when you first think of it.

[1] https://bugs.gentoo.org/show_bug.cgi?id=333531

--
Panagiotis Christopoulos ( pchrist )
    ( Gentoo Lisp Project )

attachment0 (204 bytes) Download Attachment
123