Conversion to SVN

[Ulrich Spörlein]

On Fri, 2011-10-07 at 18:27:31 +0200, Niclas Zeising wrote:
> On 10/07/11 17:33, Glen Barber wrote:
> > Hi,
> >
> > On 10/7/11 10:13 AM, Ulrich Spörlein wrote:
> >> What I, personally, would like to see is us using the same svn repo as
> >> src. That means we would have to stop svn.freebsd.org for the
> >> conversion, turn off email sending, dump 50k revisions into it (under
> >> /doc and /www perhaps? where should branches/tags end up?), then turn
> >> everything back on.
> >>
> >
> > The following is something that I have been kicking around in my head
> > for quite some time, but haven't found the right time to bring it up:
> >
> > What I would like to see "someday" is a development workflow that more
> > closely matches src.
> >
> > What do I mean by that?
> >
> > I think it would be beneficial to provide a "versioned" FreeBSD
> > Handbook.  The PostgreSQL documentation folks do this [1] - you can find
> > documentation that was specific to a particular release, so you can
> > determine if something you have found in the docs appropriately matches
> > the version you are running. [2]
> >
> > A bigger reason I think this would be a good thing is actually a rather
> > obvious one:  those of us (doc folks) tracking -CURRENT can document
> > things as they happen.  More specifically, we would not have to wait
> > until we are nearing a release to begin updating documentation that is
> > relevant to that release.  This way, doc/www HEAD (well, not necessarily
> > www for this case...) would be as up-to-date as possible with -CURRENT,
> > which I believe will benefit all of us (especially our users) when
> > release time is near.
> >
> > I have not yet put much more thought into the layout.  As I said, I was
> > waiting for the "right time" to bring this up and ask for opinions,
> > feedback, etc.  Since the topic of moving to subversion has been brought
> > up, now seems to be as good a time as any, since this would probably be
> > easier to juggle with subversion.
> >
> > [1] - http://www.postgresql.org/docs/
> > [2] - For the record, yes, I am volunteering to do the work that would
> > be required to make this happen, too.
> >
> > Just my $0.02.  :-)
> >
> 
> I don't care very much about whether we use the existing svn repo or 
> not, as long as we get one. Using a versioned handbook (and possibly 
> other docs as well) sounds like a really good idea, and I don't think it 
> will incur that much administrative overhead for either us doc people 
> nor the freebsd.org admins. This will also make it possible to rip out 
> some old stuff from the current handbook (such as ISDN information) and 
> just point people to earlier handbooks where it is present, thus making 
> the handbook more closely match what is in the release it tries to document.

I'm not sure that having a versioned handbook is such a good idea. I'd
rather have one page/one source to go to for looking up how things are
done. You immediately see what has changed between the releases and
don't have to compare docs to see if doing foo on 9.0 works the same as
on 8.3.

I have no good idea on how to fit stuff like -CURRENT becoming a release
into this scheme, however. Perhaps some special tags can be introduced
that only make content visible, once we have released 9.0. That way you
can write

On FreeBSD 6.0 and below you have to use foo.
On versions 7.x and 8.x you need to do bar.
<magic>Starting with 9.0 you need to use baz.</magic>


This will also make it clearer to the users that information might be
stale. Something you don't get with versioned handbooks.

I also think that doing the MFCs is tedious and stuff will get stale on
older branches as people forget to MFC stuff. We'd also need to support
multiple versions of building the docs.

Please note that I'm speaking as a user of the documentation, I don't
actually do much of doc work, so feel free to ignore my opinion.

Let's focus on bringing the history into SVN first and keep possible
branching of the doc tree in mind.

Cheers,
Uli