[gentoo-dev] Devmanual text on ChangeLogs

[gentoo-dev] Devmanual text on ChangeLogs

[Petteri Räty]

[-- Attachment #1: Type: text/plain, Size: 600 bytes --]

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


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 900 bytes --]

Re: [gentoo-dev] Devmanual text on ChangeLogs

[Samuli Suominen]

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.

Re: [gentoo-dev] Devmanual text on ChangeLogs

[Peter Volkov]

В Сбт, 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.

Re: [gentoo-dev] Devmanual text on ChangeLogs

[Jeroen Roovers]

On Sat, 30 Apr 2011 16:12:01 +0400
Peter Volkov <pva@gentoo.org> wrote:

> В Сбт, 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.

To put it differently, commits that only change the ChangeLog should
not be recorded in the ChangeLog (or we would never get anything
done ;-).


     jer

Re: [gentoo-dev] Devmanual text on ChangeLogs

[Markos Chandras]

[-- Attachment #1: Type: text/plain, Size: 1262 bytes --]

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

[-- Attachment #2: Type: application/pgp-signature, Size: 836 bytes --]

Re: [gentoo-dev] Devmanual text on ChangeLogs

[Brian Harring]

[-- Attachment #1: Type: text/plain, Size: 1065 bytes --]

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

[-- Attachment #2: Type: application/pgp-signature, Size: 198 bytes --]

Re: [gentoo-dev] Devmanual text on ChangeLogs

[Alex Alexander]

[-- Attachment #1: Type: text/plain, Size: 1569 bytes --]

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

[-- Attachment #2: Type: application/pgp-signature, Size: 836 bytes --]

Re: [gentoo-dev] Devmanual text on ChangeLogs

[Panagiotis Christopoulos]

[-- Attachment #1: Type: text/plain, Size: 637 bytes --]

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 )

[-- Attachment #2: Type: application/pgp-signature, Size: 197 bytes --]

Re: [gentoo-dev] Devmanual text on ChangeLogs

[Samuli Suominen]

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.

[gentoo-dev] git? [was: Re: Devmanual text on ChangeLogs]

[Eray Aslan]

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

Re: [gentoo-dev] git?

[Panagiotis Christopoulos]

[-- Attachment #1: Type: text/plain, Size: 385 bytes --]

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 )

[-- Attachment #2: Type: application/pgp-signature, Size: 197 bytes --]

Re: [gentoo-dev] git?

[Andreas K. Huettel]

[-- Attachment #1: Type: Text/Plain, Size: 607 bytes --]

Am Sonntag 01 Mai 2011, 12:54:52 schrieb Panagiotis Christopoulos:
> > 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

Anyway it would be very nice to get some sort of status update. Apart from one 
comment by you, all these bugs have not been touched since september...


-- 

Andreas K. Huettel
Gentoo Linux developer 
dilfridge@gentoo.org
http://www.akhuettel.de/


[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 198 bytes --]

Re: [gentoo-dev] git? [was: Re: Devmanual text on ChangeLogs]

[Maciej Mrozowski]

[-- Attachment #1: Type: Text/Plain, Size: 867 bytes --]

On Sunday 01 of May 2011 12:09:15 Eray Aslan wrote:
> 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.

No, because ChangeLogs could be dropped even now (and generated for rsync 
using cvs2cl tool) since ebuild history is already available in CVS 
(sources.gentoo.org). This discussion is about what tree changes are and which 
aren't relevant enough for users to be redundantly documented in ChangeLog 
files assuming they're to be kept for now.

-- 
regards
MM

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 198 bytes --]

Re: [gentoo-dev] Devmanual text on ChangeLogs

[Fabian Groffen]

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

Re: [gentoo-dev] Devmanual text on ChangeLogs

[Panagiotis Christopoulos]

[-- Attachment #1: Type: text/plain, Size: 1342 bytes --]

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 )

[-- Attachment #2: Type: application/pgp-signature, Size: 197 bytes --]

Re: [gentoo-dev] Devmanual text on ChangeLogs

[Peter Volkov]

В Вск, 01/05/2011 в 13:44 +0300, Panagiotis Christopoulos пишет:
> 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>
> "Though not mandatory, it is highly recommended that file removals are
> also recorded the same way."
> </snip> 

Panagiotis, there is no use in ChangeLog if information there is not
reliable. With policy you suggest one will have to check ChangeLog first
and then in half cases go to sources.gentoo.org to find out when ebuild
was removed. Two actions instead of one: either look ChangeLog or go to
web for cvs history.

Also, repoman commit is even slower then echangelog and thus nobody
waits for it to finish: just call it in console and switch to other
deals then just return back to check. If there are very many commits it
possible to script them. The only thing Samuli needs to do is to use
ecommit() hook:

ecommit() {
	echangelog "$@"
	repoman commit -m "$@"
}

But Samuli knows this very well and Fabian's answer describes situation
best.

-- 
Peter.

Re: [gentoo-dev] Devmanual text on ChangeLogs

[Andreas K. Huettel]

[-- Attachment #1: Type: Text/Plain, Size: 415 bytes --]

Am Sonntag 01 Mai 2011, 11:06:47 schrieb Samuli Suominen:
> ... 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.

Ever heard of opening a second terminal? :D


-- 

Andreas K. Huettel
Gentoo Linux developer 
dilfridge@gentoo.org
http://www.akhuettel.de/


[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 198 bytes --]

Re: [gentoo-dev] Devmanual text on ChangeLogs

[Brian Harring]

[-- Attachment #1: Type: text/plain, Size: 1528 bytes --]

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.

This argument sucks; if the tool is problematic... fix the tool.  
Simple example, why is is it interactive?

Add a -m <message> option to it; no longer have to watch it, just fire 
the command in a term (or in screen) w/ the message given to it 
already.

Beyond that... I suspect *everyone* would appreciate optimization done 
to echangelog.  From a quick look... seems like it's cvs status, than 
a cvs diff.  Trying to collapse that into a single op, falling back to 
status might not be a bad thing (or parallelizing the requests so the 
slowness of cvs doesn't cause sequentially stack up).

Either way.. fix the tool, rather than just doing the wrong thing.


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

I think the dial up users would have a real issue with your "easily 
get from sources.g.o" statement- same for users like myself when I'm 
in public transit/flying/working somewhere than work and at home (I 
actually do use those logs when I'm checking depgraph/pcheck issues).

Either way, fix the tool, or prove that the tool can't go any faster, 
and *then* it's a potential discussion.  Right now it really isn't, 
imo.
~brian

[-- Attachment #2: Type: application/pgp-signature, Size: 198 bytes --]

Re: [gentoo-dev] Devmanual text on ChangeLogs

[Jeroen Roovers]

On Sun, 1 May 2011 13:43:25 -0700
Brian Harring <ferringb@gmail.com> wrote:

> Beyond that... I suspect *everyone* would appreciate optimization
> done to echangelog.  From a quick look... seems like it's cvs status,
> than a cvs diff.  Trying to collapse that into a single op, falling
> back to status might not be a bad thing (or parallelizing the
> requests so the slowness of cvs doesn't cause sequentially stack up).
> 
> Either way.. fix the tool, rather than just doing the wrong thing.

I couldn't figure out what could possibly make echangelog slow, but then
I figured that this fix is easy and outside the scope of echangelog:

ssh -f -n -N master-cvs.gentoo.org

Doing only one of the cvs commands might help too, of course.


     jer

Re: [gentoo-dev] Devmanual text on ChangeLogs

[Ulrich Mueller]

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

Re: [gentoo-dev] Devmanual text on ChangeLogs

[Panagiotis Christopoulos]

[-- Attachment #1: Type: text/plain, Size: 1151 bytes --]

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 )

[-- Attachment #2: Type: application/pgp-signature, Size: 197 bytes --]

Re: [gentoo-dev] Devmanual text on ChangeLogs

[Jeroen Roovers]

On Sat, 30 Apr 2011 14:21:37 +0300
Panagiotis Christopoulos <pchrist@gentoo.org> wrote:

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

Anyone with a real problem with that could just do this?

PORTAGE_RSYNC_EXTRA_OPTS="--exclude='ChangeLog'"


     jer

[gentoo-dev] Re: Devmanual text on ChangeLogs

[Diego Elio Pettenò]

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/

Re: [gentoo-dev] Re: Devmanual text on ChangeLogs

[Panagiotis Christopoulos]

[-- Attachment #1: Type: text/plain, Size: 540 bytes --]

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 )

[-- Attachment #2: Type: application/pgp-signature, Size: 197 bytes --]

Re: [gentoo-dev] Re: Devmanual text on ChangeLogs

["Paweł Hajdan, Jr."]

[-- Attachment #1: Type: text/plain, Size: 899 bytes --]

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.


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 194 bytes --]

Re: [gentoo-dev] Re: Devmanual text on ChangeLogs

[Rich Freeman]

On Sat, Apr 30, 2011 at 9:44 AM, "Paweł Hajdan, Jr."
<phajdan.jr@gentoo.org> 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

Re: [gentoo-dev] Devmanual text on ChangeLogs

[Pacho Ramos]

[-- Attachment #1: Type: text/plain, Size: 1032 bytes --]

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 

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 198 bytes --]

Re: [gentoo-dev] Devmanual text on ChangeLogs

[Fabian Groffen]

[-- Attachment #1: Type: text/plain, Size: 1367 bytes --]

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

[-- Attachment #2: cvsps2changelog.sh --]
[-- Type: application/x-sh, Size: 2274 bytes --]

[-- Attachment #3: ChangeLog.gen --]
[-- Type: chemical/x-genbank, Size: 25388 bytes --]

[gentoo-dev] Re: Devmanual text on ChangeLogs

[Duncan]

Fabian Groffen posted on Sun, 01 May 2011 12:00:17 +0200 as excerpted:

> Attachment not shown: MIME type chemical/x-genbank; filename
> ChangeLog.gen

Had to laugh at that one. =:^)

-- 
Duncan - List replies preferred.   No HTML msgs.
"Every nonfree program has a lord, a master --
and if you use the program, he is your master."  Richard Stallman

Re: [gentoo-dev] Re: Devmanual text on ChangeLogs

[Fabian Groffen]

On 01-05-2011 14:55:24 +0000, Duncan wrote:
> Fabian Groffen posted on Sun, 01 May 2011 12:00:17 +0200 as excerpted:
> 
> > Attachment not shown: MIME type chemical/x-genbank; filename
> > ChangeLog.gen
> 
> Had to laugh at that one. =:^)

Apologies, the .gen extension apparently made the MIME match to this
thing I'd never heard before.  You can just open it as normal text file,
though.


-- 
Fabian Groffen
Gentoo on a different level

Re: [gentoo-dev] Devmanual text on ChangeLogs

[Markos Chandras]

[-- Attachment #1: Type: text/plain, Size: 2086 bytes --]

On Sun, May 01, 2011 at 12:00:17PM +0200, Fabian Groffen wrote:
> 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

Since most ( if not all ) of us use the same message on the Changelog
and on the commit log, it probably worth the effort of having the rsync
servers create the Changelogs before populate the portage tree. Having
the servers do that, will also allow us to provide cut down Changelogs
( lets say keep that last 10 entries ) so we can provide a more minimal
portage tree, size wise. A huge portage tree might not be a problem for
most of us but it sure is for embedded and all kind of similar systems.

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

[-- Attachment #2: Type: application/pgp-signature, Size: 836 bytes --]

Re: [gentoo-dev] Devmanual text on ChangeLogs

[Brian Harring]

On Sun, May 01, 2011 at 10:08:31PM +0100, Markos Chandras wrote:
> Since most ( if not all ) of us use the same message on the Changelog
> and on the commit log, it probably worth the effort of having the rsync
> servers create the Changelogs before populate the portage tree. Having
> the servers do that, will also allow us to provide cut down Changelogs
> ( lets say keep that last 10 entries ) so we can provide a more minimal
> portage tree, size wise. A huge portage tree might not be a problem for
> most of us but it sure is for embedded and all kind of similar systems.

This opens up a bit of nastyness; either the service would have to 
resign all manifests (which defeats a fair bit of the signing intent), 
or ChangeLog's would have to pulled in full from cvs, generated 
strictly server side (else manifest will have stale chksums for it), 
and ChangeLog will have to exist outside of all validation.

So... either resigning everywhere for regen, or having no validation 
asserted on the ChangeLog- meaning certain men in the middle have a 
nice area to inject some unfriendly things for anyone who happens to 
read it.

~harring

Re: [gentoo-dev] Devmanual text on ChangeLogs

[Markos Chandras]

[-- Attachment #1: Type: text/plain, Size: 2099 bytes --]

On Sun, May 01, 2011 at 03:33:25PM -0700, Brian Harring wrote:
> On Sun, May 01, 2011 at 10:08:31PM +0100, Markos Chandras wrote:
> > Since most ( if not all ) of us use the same message on the Changelog
> > and on the commit log, it probably worth the effort of having the rsync
> > servers create the Changelogs before populate the portage tree. Having
> > the servers do that, will also allow us to provide cut down Changelogs
> > ( lets say keep that last 10 entries ) so we can provide a more minimal
> > portage tree, size wise. A huge portage tree might not be a problem for
> > most of us but it sure is for embedded and all kind of similar systems.
> 
> This opens up a bit of nastyness; either the service would have to 
> resign all manifests (which defeats a fair bit of the signing intent), 
> or ChangeLog's would have to pulled in full from cvs, generated 
> strictly server side (else manifest will have stale chksums for it), 
> and ChangeLog will have to exist outside of all validation.
> 
> So... either resigning everywhere for regen, or having no validation 
> asserted on the ChangeLog- meaning certain men in the middle have a 
> nice area to inject some unfriendly things for anyone who happens to 
> read it.
> 
> ~harring
> 

Thats a fair point but the way I see it we need to make a balanced
choice. Obviously is not feasible to have the rsync servers 
resign everything. This would require having all the gpg keys on the rsync
servers, fetch the developer's name from the last cvs commit and use his
key to resign it. It doesn't look that smart to me.
	Leaving Changelogs unprotected might be a bit of a trouble but it
certainly is not that big a deal. Nothing serious can happen if someone
hijacks a plain text file.
	In case people want to ensure
end-to-end point integrity, we can use a separate GPG key for the rsync
server. However, this will make our GPG keys useless, and having a
single key to sing 10.000 Manifest files does not look good either.

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

[-- Attachment #2: Type: application/pgp-signature, Size: 836 bytes --]

[gentoo-dev] Re: Devmanual text on ChangeLogs

[Duncan]

Markos Chandras posted on Sun, 01 May 2011 23:49:06 +0100 as excerpted:

> On Sun, May 01, 2011 at 03:33:25PM -0700, Brian Harring wrote:
>> On Sun, May 01, 2011 at 10:08:31PM +0100, Markos Chandras wrote:
>>> Since most ( if not all ) of us use the same message on the Changelog
>>> and on the commit log, it probably worth the effort of having the
>>> rsync servers create the Changelogs before populate the portage tree.

>> This opens up a bit of nastyness; either the service would have to
>> resign all manifests (which defeats a fair bit of the signing intent),
>> or ChangeLog's would have to pulled in full from cvs, generated
>> strictly server side (else manifest will have stale chksums for it),
>> and ChangeLog will have to exist outside of all validation.

> Thats a fair point but the way I see it we need to make a balanced
> choice. Obviously is not feasible to have the rsync servers resign
> everything. [But] having all the gpg keys on the rsync servers [...]
> doesn't look that smart to me.

> Leaving Changelogs unprotected might be a bit of a trouble but it
> certainly is not that big a deal. Nothing serious can happen if someone
> hijacks a plain text file.

> In case people want to ensure end-to-end point integrity, we can use
> a separate GPG key for the rsync server. However, this will make our GPG
> keys useless, and having a single key to sing 10.000 Manifest files does
> not look good either.

What about having a dedicated server-based changlog-signing key?  That's 
still a lot of signing with a single key, but as you observed, the hazards 
of a loss of integrity there aren't as high as with most of the tree 
content.  It'd require changes, but I don't believe they're out of line 
with that required for the rest of the proposal.

-- 
Duncan - List replies preferred.   No HTML msgs.
"Every nonfree program has a lord, a master --
and if you use the program, he is your master."  Richard Stallman

Re: [gentoo-dev] Re: Devmanual text on ChangeLogs

[Brian Harring]

[-- Attachment #1: Type: text/plain, Size: 1052 bytes --]

On Sun, May 01, 2011 at 11:23:40PM +0000, Duncan wrote:
> What about having a dedicated server-based changlog-signing key?  That's 
> still a lot of signing with a single key, but as you observed, the hazards 
> of a loss of integrity there aren't as high as with most of the tree 
> content.  It'd require changes, but I don't believe they're out of line 
> with that required for the rest of the proposal.

It means the only real trust that clients can level is on that key- 
since it will be the last signer (thus /the/ signer) across all pkgs.

Get at that key, and you've got the tree, versus the current form, 
crack all signing keys and you've got the tree.

Mind you this is ignoring eclasses, but getting eclasses sorted will 
be mildly pointless if the rest of the solution has been 
weakened/gutted since.

Point is, it's not *just* about having a signature on it- it's about 
mapping the trust of that signature back, and sectioning/containing 
compromises.  What y'all are suggesting guts that layered defense.
~brian

[-- Attachment #2: Type: application/pgp-signature, Size: 198 bytes --]

Re: [gentoo-dev] Re: Devmanual text on ChangeLogs

[Rich Freeman]

On Sun, May 1, 2011 at 7:31 PM, Brian Harring <ferringb@gmail.com> wrote:
> Get at that key, and you've got the tree, versus the current form,
> crack all signing keys and you've got the tree.

Well, more like get any one of the keys and you get the tree, since
portage only validates that a trusted key signed a package, and not
that the key belonged to the package maintainer.

In any case, the whole way that manifest signing works does not really
preserve a signature from end-to-end.  If I sign three files and
somebody else signs two files, they end up overwriting my signature.

So, if a mirror checks all the sigs, makes a change, and re-signs with
its own key that isn't much less secure than what we have now.  I
wouldn't actually distribute the work all the way to the mirrors
though - I'd have a central server generate the changelogs, sign them,
and then propagate that to the mirror network.  You just need to
protect that one server really well then.

If you really want to have dev->user trust with no broken links then
the signatures would need to be associated with each file - not just
the whole manifest.  Plus, the local portage would need to check the
metadata cache for consistency.

In any case, I see manifest signing as a relatively minor issue here.
It seems like the more fundamental debate is how much metadata we
really should be distributing all the way to end-user systems, vs
keeping it in a repository like a cvs log.  Sure, offline access is
useful, but the question is whether it is useful enough.

My personal feeling is that we should keep the changelogs as-is, and
include removals, until we're on git.  Then we should re-evaluate.

Rich

Re: [gentoo-dev] Re: Devmanual text on ChangeLogs

[Markos Chandras]

[-- Attachment #1: Type: text/plain, Size: 654 bytes --]

On Sun, May 01, 2011 at 07:43:48PM -0400, Rich Freeman wrote:
> On Sun, May 1, 2011 at 7:31 PM, Brian Harring <ferringb@gmail.com> wrote:
> > Get at that key, and you've got the tree, versus the current form,
> > crack all signing keys and you've got the tree.
> 
> My personal feeling is that we should keep the changelogs as-is, and
> include removals, until we're on git.  Then we should re-evaluate.
> 
> Rich
> 
Git migration won't happen anytime soon. Why postpone the problem
instead of mitigating it? The solution can easily be migrated to git if
needed.

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

[-- Attachment #2: Type: application/pgp-signature, Size: 836 bytes --]

[gentoo-dev] Re: Devmanual text on ChangeLogs

[Duncan]

Rich Freeman posted on Sun, 01 May 2011 19:43:48 -0400 as excerpted:

> On Sun, May 1, 2011 at 7:31 PM, Brian Harring <ferringb@gmail.com>
> wrote:
>> Get at that key, and you've got the tree, versus the current form,
>> crack all signing keys and you've got the tree.
> 
> Well, more like get any one of the keys and you get the tree, since
> portage only validates that a trusted key signed a package, and not that
> the key belonged to the package maintainer.

OK, so everything in a manifest signs together, and if the changelog as-is 
gets server-signed, so does the rest of the manifest.

I see the problem there, but there are ways around it.  As I said, changes 
may be necessary, but they aren't huge compared to the scope of the whole 
idea.

What about having the server-generated changelogs separate from the rest 
of the package, say in a changelogs dir, one such dir per category with 
for example portage's changelog then located at 
sys-apps/changelogs/portage, thus preventing between-category naming 
collisions (we've been there!)?

Then the server could generate and sign the changelogs without interfering 
with the package manifests and their signatures.  The changelogs would all 
be signed by the same key, but it wouldn't be used for signing anything 
else, thus not interfering with actual package security at all.

-- 
Duncan - List replies preferred.   No HTML msgs.
"Every nonfree program has a lord, a master --
and if you use the program, he is your master."  Richard Stallman

Re: [gentoo-dev] Re: Devmanual text on ChangeLogs

[Fabian Groffen]

On 01-05-2011 19:43:48 -0400, Rich Freeman wrote:
> My personal feeling is that we should keep the changelogs as-is, and
> include removals, until we're on git.  Then we should re-evaluate.

git doesn't magically solve all the problems!


-- 
Fabian Groffen
Gentoo on a different level

Re: [gentoo-dev] Re: Devmanual text on ChangeLogs

[Markos Chandras]

[-- Attachment #1: Type: text/plain, Size: 1454 bytes --]

On Sun, May 01, 2011 at 04:31:08PM -0700, Brian Harring wrote:
> On Sun, May 01, 2011 at 11:23:40PM +0000, Duncan wrote:
> > What about having a dedicated server-based changlog-signing key?  That's 
> > still a lot of signing with a single key, but as you observed, the hazards 
> > of a loss of integrity there aren't as high as with most of the tree 
> > content.  It'd require changes, but I don't believe they're out of line 
> > with that required for the rest of the proposal.
> 
> It means the only real trust that clients can level is on that key- 
> since it will be the last signer (thus /the/ signer) across all pkgs.
> 
> Get at that key, and you've got the tree, versus the current form, 
> crack all signing keys and you've got the tree.
> 
> Mind you this is ignoring eclasses, but getting eclasses sorted will 
> be mildly pointless if the rest of the solution has been 
> weakened/gutted since.
> 
> Point is, it's not *just* about having a signature on it- it's about 
> mapping the trust of that signature back, and sectioning/containing 
> compromises.  What y'all are suggesting guts that layered defense.
> ~brian

Then the only choice here is to ignore Changelogs from Manifests and
live with that. You have your changelogs unprotected but you keep your
ebuilds safe(?). As I said, it is a balanced choice that has to be made.

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

[-- Attachment #2: Type: application/pgp-signature, Size: 836 bytes --]

Re: [gentoo-dev] Re: Devmanual text on ChangeLogs

[Arfrever Frehtes Taifersar Arahesis]

[-- Attachment #1: Type: Text/Plain, Size: 1730 bytes --]

2011-05-02 02:16:49 Markos Chandras napisał(a):
> On Sun, May 01, 2011 at 04:31:08PM -0700, Brian Harring wrote:
> > On Sun, May 01, 2011 at 11:23:40PM +0000, Duncan wrote:
> > > What about having a dedicated server-based changlog-signing key?  That's 
> > > still a lot of signing with a single key, but as you observed, the hazards 
> > > of a loss of integrity there aren't as high as with most of the tree 
> > > content.  It'd require changes, but I don't believe they're out of line 
> > > with that required for the rest of the proposal.
> > 
> > It means the only real trust that clients can level is on that key- 
> > since it will be the last signer (thus /the/ signer) across all pkgs.
> > 
> > Get at that key, and you've got the tree, versus the current form, 
> > crack all signing keys and you've got the tree.
> > 
> > Mind you this is ignoring eclasses, but getting eclasses sorted will 
> > be mildly pointless if the rest of the solution has been 
> > weakened/gutted since.
> > 
> > Point is, it's not *just* about having a signature on it- it's about 
> > mapping the trust of that signature back, and sectioning/containing 
> > compromises.  What y'all are suggesting guts that layered defense.
> > ~brian
> 
> Then the only choice here is to ignore Changelogs from Manifests and
> live with that. You have your changelogs unprotected but you keep your
> ebuilds safe(?). As I said, it is a balanced choice that has to be made.

Generated ChangeLogs could contain server-side-generated signatures for themselves
(gpg --sign --clearsign ChangeLog && mv ChangeLog.asc ChangeLog). 
(Manifests wouldn't contain entries for ChangeLogs.)

-- 
Arfrever Frehtes Taifersar Arahesis

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

[gentoo-dev] Re: Devmanual text on ChangeLogs

[Duncan]

Markos Chandras posted on Sun, 01 May 2011 22:08:31 +0100 as excerpted:

> Having the servers do that, will also allow us to provide cut down
> Changelogs ( lets say keep that last 10 entries ) so we can provide a
> more minimal portage tree, size wise.

What about cutting it to the largest whole number of entries that can fit 
in 4 KB, since many filesystems use 4 KB blocks anyway, with files always 
taking a whole number of blocks?

If the file's going to use 4 KB anyway, might as well take advantage of it.

Taking a look at the top of my last synced portage changelog as what's 
likely an example from the verbose end, that's thirteen entries, here, 
plus the header at the top.  For most packages I imagine it'd be something 
like 20 entries.

(Yes, I know some filesystems don't have that restriction and in fact use 
one myself, but if we're going for some arbitrary file size, 4 KB is about 
as reasonable a choice as it gets, precisely /because/ that's the default 
block size for so many widely used fss.)

-- 
Duncan - List replies preferred.   No HTML msgs.
"Every nonfree program has a lord, a master --
and if you use the program, he is your master."  Richard Stallman

Re: [gentoo-dev] Devmanual text on ChangeLogs

[Ulrich Mueller]

>>>>> On Sun, 1 May 2011, Markos Chandras wrote:

> Since most ( if not all ) of us use the same message on the
> Changelog and on the commit log, it probably worth the effort of
> having the rsync servers create the Changelogs before populate the
> portage tree.

A separate ChangeLog has the advantage that entries for trivial
changes can be omitted. Most people wouldn't want to read entries
about comment changes, for example. Also entries can be edited, which
is not possible if the ChangeLog is generated from commit messages.

> Having the servers do that, will also allow us to provide cut down
> Changelogs ( lets say keep that last 10 entries ) so we can provide
> a more minimal portage tree, size wise.

Ten is way too small. Chances are that after one round of
stabilisations the ChangeLog entry for the last real change to the
package will be gone. We should keep at least one year (better two)
of history, because our aim is that users' systems should still be
upgradeable after this time. And IMHO emerge -l should give the user
the full list of changes since his last update.

Ulrich

Re: [gentoo-dev] Devmanual text on ChangeLogs

[Markos Chandras]

[-- Attachment #1: Type: text/plain, Size: 979 bytes --]

On Mon, May 02, 2011 at 02:04:57AM +0200, Ulrich Mueller wrote:
> >>>>> On Sun, 1 May 2011, Markos Chandras wrote:
> 
> Ten is way too small. Chances are that after one round of
> stabilisations the ChangeLog entry for the last real change to the
> package will be gone. We should keep at least one year (better two)
> of history, because our aim is that users' systems should still be
> upgradeable after this time. And IMHO emerge -l should give the user
> the full list of changes since his last update.
> 
> Ulrich
> 

And how are you going to accomplish that assuming that you deliver a
trimmed down ChangeLog version? Would emerge -l fetch the full
changelog over the inet? And why do you even want to see the full history of
the package? Nobody cares about the ebuild changes that occurred in 2005. 
And if he does, this is just a corner case, and sources.g.o is your friend.

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

[-- Attachment #2: Type: application/pgp-signature, Size: 836 bytes --]

Re: [gentoo-dev] Devmanual text on ChangeLogs

[Nirbheek Chauhan]

On Mon, May 2, 2011 at 5:34 AM, Ulrich Mueller <ulm@gentoo.org> wrote:
>>>>>> On Sun, 1 May 2011, Markos Chandras wrote:
>
>> Since most ( if not all ) of us use the same message on the
>> Changelog and on the commit log, it probably worth the effort of
>> having the rsync servers create the Changelogs before populate the
>> portage tree.
>
> A separate ChangeLog has the advantage that entries for trivial
> changes can be omitted. Most people wouldn't want to read entries
> about comment changes, for example. Also entries can be edited, which
> is not possible if the ChangeLog is generated from commit messages.
>

Trivial commit messages can be omitted from the final ChangeLog very
easily. We just need to decide on a token to add to the commit message
— either [trivial] in the subject, or #trivial in the body, or similar

I don't get why someone would want to edit ChangeLogs. Could you list
some use-cases besides editing of typos?

-- 
~Nirbheek Chauhan

Gentoo GNOME+Mozilla

Re: [gentoo-dev] Devmanual text on ChangeLogs

[Robin H. Johnson]

On Mon, May 02, 2011 at 06:50:01AM +0530, Nirbheek Chauhan wrote:
> I don't get why someone would want to edit ChangeLogs. Could you list
> some use-cases besides editing of typos?
One that I have seen before was the change of a URL for users to migrate
their data, when upstream changed the URL. The URL in question was in
the ebuild and the changelog.

-- 
Robin Hugh Johnson
Gentoo Linux: Developer, Trustee & Infrastructure Lead
E-Mail     : robbat2@gentoo.org
GnuPG FP   : 11AC BA4F 4778 E3F6 E4ED  F38E B27B 944E 3488 4E85

Re: [gentoo-dev] Devmanual text on ChangeLogs

[Nirbheek Chauhan]

On Mon, May 2, 2011 at 6:54 AM, Robin H. Johnson <robbat2@gentoo.org> wrote:
> On Mon, May 02, 2011 at 06:50:01AM +0530, Nirbheek Chauhan wrote:
>> I don't get why someone would want to edit ChangeLogs. Could you list
>> some use-cases besides editing of typos?
> One that I have seen before was the change of a URL for users to migrate
> their data, when upstream changed the URL. The URL in question was in
> the ebuild and the changelog.
>

This is not a case for editing of ChangeLogs. I see three standard
ways for this information to be conveyed, in decreasing order of
likelihood of the user reading it:

(1) A Gentoo news file
(2) The ebuild itself via elog/ewarn
(3) The ChangeLog entry which changed the URL in the ebuild

In any case, ChangeLogs have always been historical records of the
changes that occurred in a package. What people seem to want is a
hybrid of ChangeLogs and NEWS files. I don't see how the costs of this
(inevitable merge conflicts, duplicated information, increased git
tree size) outweigh the benefits (the rare user who looks at the
ChangeLog but not the ebuild).


-- 
~Nirbheek Chauhan

Gentoo GNOME+Mozilla Team

Re: [gentoo-dev] Devmanual text on ChangeLogs

[Ulrich Mueller]

>>>>> On Mon, 2 May 2011, Nirbheek Chauhan wrote:

> I don't get why someone would want to edit ChangeLogs. Could you
> list some use-cases besides editing of typos?

Fixing typos should be enough reason alone. It also happened to me
more than once that I specified a wrong bug number, or that I added
credits for a user retroactively.

Ulrich

Re: [gentoo-dev] Devmanual text on ChangeLogs

[Fabian Groffen]

On 02-05-2011 02:04:57 +0200, Ulrich Mueller wrote:
> > Having the servers do that, will also allow us to provide cut down
> > Changelogs ( lets say keep that last 10 entries ) so we can provide
> > a more minimal portage tree, size wise.
> 
> Ten is way too small. Chances are that after one round of
> stabilisations the ChangeLog entry for the last real change to the
> package will be gone. We should keep at least one year (better two)
> of history, because our aim is that users' systems should still be
> upgradeable after this time. And IMHO emerge -l should give the user
> the full list of changes since his last update.

How about forgetting the time constraint, but just keeping all changelog
entries for all ebuilds that are in the tree?


-- 
Fabian Groffen
Gentoo on a different level

Re: [gentoo-dev] Devmanual text on ChangeLogs

[Gilles Dartiguelongue]

[-- Attachment #1: Type: text/plain, Size: 938 bytes --]

Le samedi 30 avril 2011 à 11:46 +0300, Petteri Räty a écrit :
> 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
> 

As in any other open source project, history (even of removed files)
matters just as much as the outcome. Please make it a policy to always
have a ChangeLog entry for any changes.

-- 
Gilles Dartiguelongue <eva@gentoo.org>
Gentoo

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 198 bytes --]