[gentoo-dev] Portage, SLOT, functionality, documentation, ChangeLog

[gentoo-dev] Portage, SLOT, functionality, documentation, ChangeLog

[Stewart Honsberger]

I've talked about this several times, but I wanted to get it out in the 
open;

Portage has an abhorrent lack of documentation, I'd like to see that 
changed. Possibly
(especially) before a 1.4 release.

There are dozens upon dozens of facets of key functionality that are 
simply not
explained, or not clearly explained. If they are, they're given a 
sentence here and there,
scattered all about the Gentoo website, man/info pages, CVS, etc.

Also, and I can't stress this enough, a ChangeLog is *required*. When 
key functionality
is introduced, updated, removed, or significantly altered, it is 
imperative that users
and developers alike can be easily appraised of it in a common location.

A roadmap would also help a lot of people rest easy at night. Whether it 
is the case or
not, it seems as if major changes take place in Portage on a whim. If 
they are planned,
the general userbase has no foreknowledge of said plans and these 
changes come as
a complete surprise when finally marked stable in the tree (if people 
even know they
exist, due to the aforementioned lack of documentation).

Thoughts? Ideas?

-- 
Stewart Honsberger
http://blackdeath.snerk.org/
"Capitalists, by nature, organize to protect themselves.
-- Geeks, by nature, resist organizaion."


--
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] Portage, SLOT, functionality, documentation, ChangeLog

[Grant Goodyear]

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

> Portage has an abhorrent lack of documentation, I'd like to see that 
> changed. Possibly
> (especially) before a 1.4 release.

I don't think there's a snowball's chance in Death Valley of that
happening, just due to time restrictions.  It's certainly true, though,
that we do need to consolidate and improve the portage docs.

> Also, and I can't stress this enough, a ChangeLog is *required*. When 
> key functionality
> is introduced, updated, removed, or significantly altered, it is 
> imperative that users
> and developers alike can be easily appraised of it in a common location.

You'll find that the ChangeLog gets installed in
/usr/share/doc/portage-x.y.z.  Of course, it might be nice to know
what's changed before you upgrade.  The ChangeLog in sys-apps/portage
incorrectly points people to viewcvs on cvs.g.o, although that's simple
enough to fix.  Slightly more difficult is the fact that gentoo-src is
no longer linked to viewcvs.  Since portage and rc scripts are developed
there, having web access is really handy.  Can we fix that?  (Numerous
cheers, by the way, for the prompt return of viewcvs.  Thanks!!!)

> A roadmap would also help a lot of people rest easy at night. Whether it 
> is the case or
> not, it seems as if major changes take place in Portage on a whim. If 
> they are planned,
> the general userbase has no foreknowledge of said plans and these 
> changes come as
> a complete surprise when finally marked stable in the tree (if people 
> even know they
> exist, due to the aforementioned lack of documentation).

*Grin*  The roadmap _used_ to be a "TODO" block in portage.py.  Having a
somewhat more formal roadmap would be a nice idea, and I don't know if
one exists or not, although I'd be rather surprised if one didn't.

Best,
g2boojum
-- 
Grant Goodyear <g2boojum@gentoo.org>

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

[gentoo-dev] Re: [gentoo-core] Portage, SLOT, functionality, documentation, ChangeLog

[Nick Jones]

> Portage has an abhorrent lack of documentation, I'd like to see
> that changed. Possibly (especially) before a 1.4 release.

This is mentioned every once in a while, but to 'see that changed'
really does not help. SpanKY and a few other (greatly appreciated
individuals) make great contributions towards documenting all the
little bits that are missing, but, as you note, there is a lot that 
needs to be worked out. Time and I are not great friends, but I try
to keep up with what I make changes to (albeit most are only noted
in the changelog, make.conf, and emerge --help).

Care to help?

> A roadmap would also help a lot of people rest easy at night.
> Whether it is the case or not, it seems as if major changes take
> place in Portage on a whim. If they are planned, the general
> userbase has no foreknowledge of said plans and these changes
> come as a complete surprise when finally marked stable in the
> tree (if people even know they exist, due to the aforementioned
> lack of documentation).

Well... It's not on a whim... But I'll be working on improving
(read: creating) the public project plan/roadmap... as most of
it is my written notes and bugs.gentoo.org.

--NJ

--
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] Re: [gentoo-core] Portage, SLOT, functionality, documentation, ChangeLog

[Mike Frysinger]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On Sunday 13 July 2003 16:39, Nick Jones wrote:
> > Portage has an abhorrent lack of documentation, I'd like to see
> > that changed. Possibly (especially) before a 1.4 release.
>
> This is mentioned every once in a while, but to 'see that changed'
> really does not help

agreed, you really have to tell us what is missing ...
as far as i know, the man pages are complete up to 2.0.48-r1 and ive started 
to add somethings that are new with -r3 ... and as far as the description 
sucking, once again you have to say 'the description of PV sucks, please do 
something about it' because imo the portage man pages are fine
- -mike
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.2 (GNU/Linux)

iQIVAwUBPxHmNkFjO5/oN/WBAQIMWQ//WoUBykNPJeFLwOXwuzky7WpEzbxSkx7F
Ra9m2m3JAXRGzuaZcwDOK5tVNPnZtK9vcwMPBTDk+NtVSMqD+ZHAtcRbp7cLWxal
M88hjuIutlLGVlz/y9AjXcSNm8xZvk1Tt31Ryv2n3CYax5GjuU90Hbuxa32DziiP
p+j4sxa4knXMABRvmbeCgcE7Y775xlu1iKt0nBhDGwxuukgyVT7lIHh0F47lhni7
hh/ltM9gF3qa5Rz30BdiaPq8fbNqLkf1WA1xtyuwxwuXFQAB2bVUlCjL/e0nkkca
2o2/lL0Ad+u5nM5QzEF+HDqk/lDQnJYACu/U4KqbkEYszB6tM4iN15M01OPgG4wr
wZglD4MTHewwOnVOw4xZpNX/CkGao4kiEiEwTdmWtbopsy7pufAOluEQ7XhUUGFC
sWO5eUmKLoIIu/XHnihT4zCiRegj9J9r8CTON3Xa3W5hFf2FKuF0+l06aT4Ig57p
VFvrrW+gOrDR1yaJ8j7j0trAZQVMoWpBDdXQHBHxm7RgvutAuPei8pmhgDE6WJNj
fSZRwL4acHK/0kXLM/kuM+foOpr3LtmO0xJbRneL+nBoFAlEF/gwRdDxcBDWF4YV
7BsL4fei/kUNOeh63+c97JIE2xNdU1iCfgk2F9eYpsDynC8y0L6/gdl8jGSEB5xH
gU0aBiL3qhQ=
=tbaI
-----END PGP SIGNATURE-----

--
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] Re: [gentoo-core] Portage, SLOT, functionality, documentation, ChangeLog

[Stewart Honsberger]

Nick Jones wrote:

> This is mentioned every once in a while, but to 'see that changed'
> really does not help. SpanKY and a few other (greatly appreciated
> individuals) make great contributions towards documenting all the
> little bits that are missing, but, as you note, there is a lot that 
> needs to be worked out. Time and I are not great friends, but I try
> to keep up with what I make changes to (albeit most are only noted
> in the changelog, make.conf, and emerge --help).
> 
> Care to help?

Absolutely. I was going to try to talk to you in person about it in 
#gentoo-dev, but alas you weren't there and I was also pressed for time.

I'll be working fewer hours this week, so I should have a better chance 
to get organized and I'd love to start by gathering all the existing 
documents, ChangeLogs, etc. as well as your written notes and the 
bugs.g.o entries together and seeing where we stand.

Is there a specific time you're (generally) available on IRC? During the 
day (~11AM-4PM EST) is the best time for me at the moment.

-- 
Stewart Honsberger
Gentoo Developer
http://www.snerk.org/


--
gentoo-dev@gentoo.org mailing list