Introduction & question / comment regarding source tree documentation

[Peter Looyenga]

Hi guys,

Disclaimer: I went over the mailinglist archives a little bit but it doesn't
help that I don't necessarily like mailinglists and personally prefer the
comforts of a web forum. But I'll cope :)

I've been using FreeBSD for quite a few years now, I more or less switched
from Solaris to FreeBSD. That is: I also have my share of Linux usage, but
in general I always considered Linux a decent way of keeping my Solaris
experiences fresh (before you could purchase Solaris/x86). Well, we all know
what happened to Sun I assume, and that made me fully move onto FreeBSD. I
literally never looked back. 

I'm a bit on and off on the FreeBSD forums, already wrote a decent (?) share
of guides, and right now I hope that I can help contribute a bit more to the
documentation project. Because one thing which I always admired on FreeBSD
was its set of very mature and good to follow documentation. But I'm also
starting to spot some issues, so yeah: instead of "complaining" about those
I'd like to try and help address those.

My current drive: I can't help feel that the steps required to obtain the
source tree aren't very well explained, and as a result several people and
up confused. To put it more blunt, this thread is what drove me to try and
take more action:

https://forums.freebsd.org/threads/59919/

I know that 23.4 in the handbook explains how to track the development
branches. But what bugs me is that the actual SVN url's are very deeply
buried away. A regular user will have to take a lot of effort before
realizing that svn://svn.freebsd.org/base/stable is actually pointing to a
developer snapshot instead of a stable version of the whole thing. Also:
svn://svn.freebsd/base/current isn't even directly mentioned (only -CURRENT,
yet without the associated URL) which I think is also adding up to confusing
users.

I also think it doesn't help that section A.3 (Using subversion) still talks
about stable/9 and stable/10 even though 9 is already EOL (see here:
https://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/svn.html#svn-mirr
ors). Although I can absolutely agree that it does serve well as a general
example.

But I also think it's an oversight not to include examples on how to check
out the current stable (RELENG) source tree in the chapter about using
Subversion.

As such I read up on the procedures which one needs to follow and I'm
already getting my hands behind the documentation source. 

My only concern (and actual question): Is this already work in progress by
any chance? I don't mind spending a good amount of time on writing up some
documentation, but I have a little bit of a problem with setting something
up only to find out that it wasn't needed at all.

Note: I don't mind if I send in suggestions and then see them not getting
accepted, that's all part of the game. But it would be bad for me when I
start working on this, only to discover that someone else was already
working on it so I basically ended up wasting my time.

Hope you guys can give me some pointers on this.


And thanks in advance for any comments you can give me!

Kind regards, Peter

--
.\\ OpenPGP public key: http://www.catslair.org/shelluser.asc
    +- S/MIME semi-private Root CA: http://ssl.catslair.org/catslair.crt