Differences

This shows you the differences between two versions of the page.

--- versioncontrol:subversionrepositorylayout [2006/09/19 20:59] – NikClayton
+++ versioncontrol:subversionrepositorylayout [2022/10/07 03:04] (current) – Move bakeoff stuff under a single namespace KubilayKocak
@@ Line 135: / Line 135: @@
 Mirroring ''%%freebsd/%%'' would be like fetching ''%%src-all%%'', ''%%ports-all%%'', ''%%doc-all%%'', and ''%%www%%'' using CVSup.
-Now, at the moment we don't branch trees like ''%%ports/%%''.  That's (I think) more to do with the time and effort this takes to manage branches under CVS than because we couldn't benefit from branched ports.  However, even if we decide not to branch ports (or the other trees) right now, we should probably still use the ''%%trunk/%%'' subdirectory.  It keeps things like directory depth consistent, which makes it much easier to automate things, or describe the repo.
+Now, at the moment we don't branch trees like ''%%ports/%%''.  That's (I think) more to do with the time and effort this takes to manage branches under CVS than because we couldn't benefit from branched ports.  However, even if we decide not to branch ports (or the other trees) right now, we should probably still use the ''%%trunk/%%'' subdirectory.  It keeps things like directory depth consistent, which makes it much easier to automate things, or describe the repo in general terms instead of having to include special cases.
 This scheme allows the four component parts of the project to branch and tag at different times.  This is common during the release process, where, for example, ''%%ports/%%'' will have a change freeze that has different dates to the ''%%src/%%'' code freeze.
-...
+So, for the moment, ''%%freebsd/src/trunk/%%'' corresponds to CVS HEAD.  What about releases, 6-stable, and 5-stable?
-XXX - nik plans to pick this up later
+==== Major releases ====
+A major release (and focusing just on the ''%%src/%%'' tree for the moment) is one that is cut from ''%%trunk/%%'' (aka CVS HEAD).  Here's how it would work for %%FreeBSD%% 8.0.
+<code>
+# First, snapshot the src tree on to a branch from which the release will be cut.
+% svn copy $REPO/freebsd/src/trunk $REPO/freebsd/src/branches/8.x
+# Now prepare 1..n release candidates.  In CVS we do not tag release candidates.
+# With Subversion's cheap tagging it becomes possible to do that.  This step, is,
+# of course, optional.
+% svn copy $REPO/freebsd/src/branches/8.x $REPO/freebsd/src/tags/8.0rc1
+# A similar process takes place on the ports/ and doc/ trees to tag their own
+# files for 8.0rc1.
+# The release engineer(s) prepare a release from (src,doc,ports)/tags/8.0rc1
+# If the release candidate has problems, changes are made to src/branches/8.x
+# to rectify them, and copies of this directory are made to tags/8.0rcN as
+# necessary.
+# Eventually (say, after 3 attempts, so we're at 8.0rc3) the release is deemed
+# ready to go out the door.  So the RE copies the rc3 tag to a release tag.
+% svn copy $REPO/freebsd/src/tags/8.0rc3 $REPO/freebsd/src/tags/8.0-release
+# and carries out similar commands for the doc/ and ports/ trees
+# The final step is to create a branch just for this release -- this it the branch
+# to which security errata (or similar) commits would go
+% svn copy $REPO/freebsd/src/tags/8.0rc3 $REPO/freebsd/branches/8.0
+</code>
+==== MFCs ====
+Once release has been cut the tree looks like this (again, focusing just on src/ for the time being.
+<code>
+  freebsd / src / trunk
+                  branches / 8.x
+                           / 8.0
+                  tags     / 8.0-release
+                           / 8.0rc1
+                           / 8.0rc2
+                           / 8.0rc3}}}
+Those rc1, rc2, and rc3 tags can be removed -- but that's not necessary, and since it's deleting project history it might not be desirable.  They take up minimal extra space in the repository (although they do slightly clutter up the output of `svn ls $REPO/freebsd/src/tags`, which may or may not be a concern).
+In this structure, what we would currently call 8-stable corresponds to the `branches/8.x/` directory.  It's entirely possible that we would want to call this directory `8-stable/` instead of `8.x/`.  I'm not married to the name -- however, given the occasional outburst from the userbase on the -stable mailing list when -stable turns out not to be "stable", perhaps we should consider taking the opportunity to migrate away from the name.
+Anyway, I digress.  As is the nature of things, work continues on `src/trunk/`.  Work that will go in to 8.1 is merged from `src/trunk/` in to `src/branches/8.x`.
+=== Minor releases ===
+At some point it becomes time to cut a minor release.  This process is almost identical to that for a major release.  The difference is the source of the copy for the release candidate.  This is just like a major release, only without the initial copy from trunk.  All the release candidates are all taken from the 8.x branch.
+{{{
+    % svn copy $REPO/freebsd/src/branches/8.x $REPO/freebsd/src/tags/8.0rc1}}}
+These go through the same release candidate tagging cycle as before.
+=== Security releases ===
+Should it become necessary to cut a security release the process is very similar.  Recall that the code for each release is also tagged.
+So suppose that 8.1 has been released, and it only took one release candidate to do so.  That portion of the tree is going to look like this:
+{{{
+  freebsd / src / trunk
+                  branches / 8.x
+                           / 8.0
+                           / 8.1
+                  tags     / 8.0-release
+                           / 8.0rc1
+                           / 8.0rc2
+                           / 8.0rc3
+                           / 8.1-release
+                           / 8.1rc1}}}
+The security officer commits their changes to `branches/8.1`.  This means that anyone who is mirroring `branches/8.1` (to track security and other errata changes to otherwise frozen code) automatically picks up the fix.
+The SO can then release 8.1.1, following the same process as before.  The only difference is that the source of the intial copy is `branches/8.1`, instead of `trunk/` (for major releases) or `branches/8.x`, for minor releases.
+== Recap ==
+The structure so far replicates (as far as I can see) the same features that we get from CVS.
+|| '''CVS Tag/branch name''' || '''Subversion Path''' ||
+|| HEAD                      || `trunk/`              ||
+|| RELENG_8_0_0_RELEASE      || `tags/8.0`            ||
+|| RELENG_8                  || `branches/8.x`        ||
+|| RELENG_8_1                || `branches/8.1`        ||
+There's no need for the *_BP tags, as they're not necessary under Subversion's model.  A branch (i.e., a copy) carries with it the information about the path and revision from which it was copied, so this information does not need to be recorded separately.
+== Refinements ==
+Some possible refinements that we might want to make.
+ * Instead of `tags/8.0`, perhaps `releases/8.0` might make more sense.  On the one hand, it more accurately captures what's there.  On the other hand, there's an increasing amount of Subversion literature (and experience) that expects this directory to conventionally be called `tags/`.
+ * Looking back on what I've written so far I should have used version numbers of the form x.y.z everywhere.  Pretend I have.
+ * Instead of `branches/8.x`, perhaps `branches/8-stable` makes more sense.  Although, as I say earlier, the use of the word "stable" when we mean the APIs, and not the overall stability of the system has caused heated discussion on the mailing lists in the past, and this is an opportunity to get away from that mistake (if it's considered to be one).
+== Vendor ==
+As already discussed, the convention is to keep unmodified vendor code in its own space.  It's only the modified code that makes it in to the `freebsd/` tree.
+== Projects ==
+The top level `projects/` directory is reserved for long-lived projects.  The sort of thing that would currently be kept in the Perforce repository.  I imagine that each project would have a top-level directory under here, with at least a `trunk/` directory underneath.  If the project is particularly long lived, and perhaps cuts its own releases, then `tags/` and `branches/` subdirectories would also make sense.
+Under this model we could (if we wanted) move projects like PicoBSD under the main FreeBSD repo.
+I have no opinion on how space under `projects/` is handed out to requestors.
+== User ==
+The top level `user/` tree is where per-user directories can go.  Given that we have something like 300+ comitters at the moment I've shown the directory space subdivided by first character of the username.  That may or may not be warranted, I don't especially care.
+This is the space for users to conduct their own experiments before bringing them in to the main tree.  For example, a committer with 8 ports to their  name might want to use this space to do development on their ports.  Once the ports are ready the changes can be merged in to the main tree.
+== One repo?  Several repos?  Impact on mirrors ==
+A decision to be made is whether we want one big repo that has everything, or several smaller repos.
+One repo pros:
+ * One set of ACLs to administer
+ * Merging between different directories retains history -- for example, the aforementioned ports committer who prepares updates to their ports in their user directory, before merging the changes back to the ports trunk.  Or, merging between projects (e.g., TrustedBSD) and the main codebase.
+One repo cons:
+ * It's a lot more data to mirror.  2 of the 3 repo mirroring techniques (svnsync(1) and rsync'ing a snapshot of the repo backend) don't allow you to mirror individual subtrees.  To an extent this makes sense -- after all, what should happen if a single commit makes changes to files you are mirroring and files you aren't...  But this does place a greater load on the amount of data the mirrors need to host.  The third mirroring technique, SVN::Mirror, does allow you to only mirror subtrees, but as soon as you do that the revision numbers in the mirror are no longer in sync with the revision numbers in the master repo.
+Invert those pros and cons for the multi-repo case.
+</code>