Subject: Re: New NetBSD Guide chapter: Obtaining the sources
To: Greg Troxel <gdt@ir.bbn.com>
From: Rui Paulo <rpaulo@NetBSD.org>
List: netbsd-docs
Date: 08/08/2005 23:11:44
On 2005.08.08 08:34:47 +0000, Greg Troxel wrote:
|   Before starting to fetch or download the required files, you may
|   want to know the definitions of ?Formal releases?,
| 
| This should be stronger, making the point that one must choose a
| branch or release first.

I agree.

|   CVS is usually quite fast for fetching sources if you have decent
|   internet connectivity. However, in a case you are using a modem, you
|   may wish to compress data for the update. In that case use the -z
|   option. For example:
| 
| "decent" is not precise.  I suggest giving guidance for when to use
| -z3 and -z9 based on pipe size.  I would think that -z3 is appropriate
| for <= 128 kb/s, and -z9 never.

I will.

| I would explain how to get tarballs first, and explain (if true) that
| one can unpack tarballs and then use cvs.

That's explained in the tarballs section.

|   CVS also supports several connection methods. If you want to use the
|   ?external? method (only available with ssh(1)) you should do:
| 
| Given new users, this should explain how to make this choice.  Perhaps
| even call ssh the 'normal way', and discourage pserver use.  (Or the
| other way, for server load - what I really mean is to get expert
| consensus and teach that.)
| 
| Seeing csh examples rubs me the wrong way, since while I started to
| use csh under BSD after V7, I went back to a Bourne-style shell in
| 1990, and object to scripts in csh.  One thought is to show both sh
| and csh style variable setting, and to avoid environment variables
| when possible.

Well, I don't see how can that csh examples be bad. Get someone to change
the default user shell on NetBSD and I promise you I'll change the whole
guide. ;)


| In particular, I object to setting CVSROOT (and
| prohibit it within my research group) since when using multiple
| repositories it is often wrong.  So I'd say:
| 
|   cvs -d :ext:anoncvs@anoncvs.NetBSD.org:/cvsroot co src
| 
| because once checked out, there is no need to have CVSROOT set.

No one is saying the oposite. Setting CVSROOT is only to avoid
typing the same in all the examples... do you really want to do that?

| In general, I would omit prompts so that text from the guide can be
| cut/pasted into a shell.

That's not a common all over the guide. How do you expect a user to
detect a set of commands easily (by eye) without a prompt ?

|   Where <BRANCH> is the release branch to be checked out, for example,
|   ?netbsd-2-0-RELEASE?, ?netbsd-2-1-RELEASE? or ?netbsd-3-0-RELEASE?. If
|   you want to fetch a different patchlevel, you would use
|   ?netbsd-2-0-1-RELEASE? or ?netbsd-2-0-2-RELEASE?.
| 
| This blurs branches and point tags.  While perhaps a fine point, this
| is very confusing to most people, and I advise being clear from the
| beginning.  Having a sentence "A release is a set of particular
| versions of source files, and once released does not change over
| time." would perhaps help to explain this.  Then, do not use the word
| branch in this section.

I agree.

|   For example, if you want to fetch the stable version of ?netbsd-2?,
|   you just need to use that tag:
| 
| Not the stable version of netbsd-2, but the *most recent* version of
| netbsd-2 (which points out that netbsd-2 changes over time).
| (netbsd-2 is a stable branch, but there aren't stable versions of that
| branch.)

http://www.netbsd.org/Releases/release-map.html
<quote>
Starting with NetBSD 2.0, maintenance branches come in two flavours:

   1. Maintenance branches which will develop into the next minor release, 
      which we call stable branches, and which is reflected in the version 
      designation along this branch, e.g. 2.0_STABLE, which will evolve 
      into 2.1. The corresponding CVS branch is the same branch that was 
      created from NetBSD-current and which gave rise to the corresponding
      previous major release.
</quote>

By stable I mean x.y.z_STABLE or x.y_STABLE.


| Explain what -P means.  I had not seen it used on checkout before, and
| it seems clear that it is intended to not checkout empty directories
| in order to avoid build breakage.  This is subtle.

I missed that... really.

|   To know the pkgsrc branches for the current year, run:
| 
| "Once you have some version of pkgsrc checked out"
| 
| This advice is problematic, since it can lead to people using the
| next, not yet debugged branch while the old is still active.  But
| given pkgsrc resources, it's probably 98% good advice.

Please explain yourelf. What do you mean by "next, not yet debugged branch" ?

| I'd like to see an explanation of how to get a copy of the repository
| (sup, cvsup or rsync, I think), and guidance on the advantages and
| disadvantages of each, both for the user and the servers.

Isn't that a bit of out-of-scope for the NetBSD guide ? I mean, normally,
only developers, companies using/developing NetBSD and mirrors need
to do that. Documentation/mirror.html explains a bit of each.

| Probably
| this is advanced for most users, and perhaps duplicatesa
| 
|   http://www.netbsd.org/Documentation/current/#using-anoncvs
| 
| Perhaps that page can be stripped down to bare bones information and
| refer to the guide.  By bare bones, I mean written for someone who
| knows how to use CVS, and just needs to be given the CVSROOT value and
| the set of modules to check out.

I think that's the idea. Anyway, you probaly only need the $CVSROOT, since
you can checkout "CVSROOT" and see the modules file or go to
http://cvsweb.netbsd.org/.

Thank you!

		-- Rui Paulo