From owner-freebsd-doc@FreeBSD.ORG Sat Oct 29 07:52:12 2011 Return-Path: Delivered-To: freebsd-doc@freebsd.org Received: from mx2.freebsd.org (mx2.freebsd.org [IPv6:2001:4f8:fff6::35]) by hub.freebsd.org (Postfix) with ESMTP id 6536B106566B; Sat, 29 Oct 2011 07:52:12 +0000 (UTC) (envelope-from dougb@FreeBSD.org) Received: from 172-17-198-245.globalsuite.net (hub.freebsd.org [IPv6:2001:4f8:fff6::36]) by mx2.freebsd.org (Postfix) with ESMTP id 1154C15724D; Sat, 29 Oct 2011 07:52:12 +0000 (UTC) Message-ID: <4EABB0AB.9070808@FreeBSD.org> Date: Sat, 29 Oct 2011 00:52:11 -0700 From: Doug Barton Organization: http://SupersetSolutions.com/ User-Agent: Mozilla/5.0 (X11; FreeBSD amd64; rv:7.0.1) Gecko/20111001 Thunderbird/7.0.1 MIME-Version: 1.0 To: John Baldwin References: <20111007141312.GJ26743@acme.spoerlein.net> <201110240827.50750.jhb@freebsd.org> <4EA5E122.8030303@FreeBSD.org> <201110251405.46493.jhb@freebsd.org> In-Reply-To: <201110251405.46493.jhb@freebsd.org> X-Enigmail-Version: undefined OpenPGP: id=1A1ABC84 Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: 7bit Cc: "Simon L. B. Nielsen" , freebsd-doc@freebsd.org, doc@freebsd.org, doceng@freebsd.org, =?ISO-8859-1?Q?Sp=F6rlein?= Subject: Re: Conversion to SVN X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 29 Oct 2011 07:52:12 -0000 On 10/25/2011 11:05, John Baldwin wrote: > On Monday, October 24, 2011 6:05:22 pm Doug Barton wrote: >> On 10/24/2011 05:27, John Baldwin wrote: >>> On Saturday, October 22, 2011 12:00:10 am Doug Barton wrote: >>>> On 10/10/2011 10:01, John Baldwin wrote: >>>>> On Saturday, October 08, 2011 12:16:59 pm Simon L. B. Nielsen wrote: >>>>>>>> I'm not really sure where you would fit doc into the current repo... >>>>>>>> head/ etc. is on the top level. >>>>>>> >>>>>>> /doc and /www would be the obvious choices. Ed even jokingly (??) said >>>>>> >>>>>> Well, that seems like a bit of a mess as you mainly have branches at that level... >>>>>> >>>>>>> we should just rename /head to /src ... not sure I concur. >>>>>> >>>>>> Considering we have stable etc. on the same level that seems like a bad thing to do... >>>>> >>>>> I agree with both of these. The layout in svn currently is src-centric and >>>>> only setup to handle src. >>>> >>>> Right now under base/ we have: >>>> >>>> cvs2svn >>>> head >>>> projects >>>> release >>>> releng >>>> stable >>>> svnadmin >>>> user >>>> vendor >>>> vendor-crypto >>>> vendory-sys >>>> ROADMAP.TXT >>>> >>>> Those categories are primarily source-related, but not exclusively. >>> >>> The branches are certainly very src-centric. For example, where would you >>> put doc release tags? >> >> What prevents them from being put under release/ ? > > So right now what happens is that a release is tagged by re@ doing > 'svn cp stable/9 releng/9.0' and eventually 'svn cp releng/9.0 release/9.0'. > > Are you foreseeing having re@ add extra steps to do a fixup so that, say, > you do 'svn cp doc releng/9.0/doc' or 'svn cp doc release/9.0/doc' after the > initial copy? No, that would be silly. :) Something more along the lines of: svn cp doc/foo/bar release/9.0-doc I don't see any value in duplicating the src process line by line, only the bits that are relevant. > I also think it might do some very bizarre things in our downstream CVS repo > (or possibly require substantial hackery to our existing SVN -> CVS > conversion scripts). If that turns out to be true then obviously we need to figure out the right way to handle it. > Keep in mind that we don't have an svn replacement for > cvsup (esp. in checkout mode) which many users still depend on, so we can't > just ignore that entirely (though perhaps we could choose to not replicate > the release version of docs to CVS, or tolerate them showing up as 'src/doc' > in CVS instead). However we'd need to think about the full implications of > doing any approach in this regard. I'm not sure we need to duplicate all the features we have for cvs in an svn world. We haven't needed to do that for src, so saying "we need to solve this for doc" in this context is a red herring. >> The question is not how can we continue to do what we've always done, >> but how can we do better? > > But the solution has to actually be better. I thinking having docs in SVN vs > CVS might be better (changesets, etc.), but I'm not convinced that having them > in the same SVN as src is any better than a dedicated repository. And my point is that having them in the same repo is certainly no worse, and gives us the opportunity to do something better. >>>>> Also, I think the discontinuous history idea is a compelling reason to not put >>>>> the doc/www history into source svn. Right now svn changes move forward >>>>> continuously with time (so change N + 1 is "newer" than change N), but >>>>> importing doc+www history as changes that are subsequent to the current top of >>>>> tree would break that. OTOH, renumbering the current tree to put the doc+www >>>>> history in the "right" place is simply not workable now. >>>> >>>> I don't understand any of what you wrote above, but I'd like to. What >>>> I'm thinking is that the cvs->svn converter would simply start with the >>>> next available revision number and that would be the first revision for >>>> the oldest doc commit. When the import was done, the revision numbers >>>> would continue to increase monotonically regardless of whether it was a >>>> doc or src commit. Are you saying that this is not how it would work? >>> >>> I'm saying that humans would find it confusing that revision N would be >>> from today and revision N+1 would be from 1996. >> >> I think you're dramatically overestimating how confused people would be >> by this. Just like the fact that version numbers increase over the whole >> repo, this is something that people would just get used to over time. > > Maybe so. Still, I depend on this implicit stuff a good bit when dealing > with historical info in the form of commit logs via 'annotate', etc. > (which I actually do a lot in src). Since the doc and src bits wouldn't > actually overlap, perhaps that would not matter for someone in the future > who is looking at past history since the streams should not cross. Exactly. We've learned to cope with subsequent revisions to a given file being 10's of thousands of revision numbers apart, the numbers are just numbers. As long as they increase monotonically the numbers themselves are not relevant. They are merely conveniently-unique symbolic representations of the given change set. Git actually sort of gets this right, it's just that their unfortunate choice of using a checksum doesn't allow for the use of a VCS $Id. > However, if the plan is to allow concurrent changes to manpages and docs > (which can be a valid reason to merge), then you can get the odd behavior > where revision N of a doc file is "older" than revision M (where M < N) > of some change in a manpage and if you are walking back in history > because you are investigating a change in the future made to both files > that might be a bit confusing. I can see how what you're describing could happen, but I don't see why anyone would care. If you're updating a file in the doc tree in the same change set as a file in the src tree, the numbers of the current revisions of the files are (almost certainly) going to be different. The fact that the revision number for a file which is chronologically older is numerically higher than the other is a useless piece of trivia. Doug -- Nothin' ever doesn't change, but nothin' changes much. -- OK Go Breadth of IT experience, and depth of knowledge in the DNS. Yours for the right price. :) http://SupersetSolutions.com/