Differential D29610 Diff 86923 documentation/content/en/articles/committers-guide/_index.adoc

Changeset View

Standalone View

documentation/content/en/articles/committers-guide/_index.adoc

	Show First 20 Lines • Show All 2,013 Lines • ▼ Show 20 Lines

	[source,shell]			[source,shell]
	....			....
	git log refs/freebsd/vendor/zlib/1.2.10			git log refs/freebsd/vendor/zlib/1.2.10
	....			....

	would look at the log for the vendor branch for zlib starting at 1.2.10.			would look at the log for the vendor branch for zlib starting at 1.2.10.

	[[subversion-primer]]			[[vcs-history]]
	== Subversion Primer			== Version Control History

	New committers are assumed to already be familiar with the basic operation of Subversion.			The project has moved to <<git-primer,git>>.
	If not, start by reading the http://svnbook.red-bean.com/[Subversion Book].

	This section is relevant only for the ports tree. Information on Git is being worked into the handbook and other documents.
	A draft version can be found at https://github.com/bsdimp/freebsd-git-docs/blob/main/SUMMARY.adoc

	[[svn-intro]]
	=== Introduction

	The FreeBSD source repository switched from CVS to Subversion on May 31st, 2008.			The FreeBSD source repository switched from CVS to Subversion on May 31st, 2008.
	The first real SVN commit is __r179447__.			The first real SVN commit is __r179447__.
	The source repository switched from Subversion to Git on December 23rd, 2020.			The source repository switched from Subversion to Git on December 23rd, 2020.
	The last real svn commit is __r368820__.			The last real svn commit is __r368820__.
	The first real git commit hash is __5ef5f51d2bef80b0ede9b10ad5b0e9440b60518c__			The first real git commit hash is __5ef5f51d2bef80b0ede9b10ad5b0e9440b60518c__

	The FreeBSD `doc/www` repository switched from CVS to Subversion on May 19th, 2012.			The FreeBSD `doc/www` repository switched from CVS to Subversion on May 19th, 2012.
	The first real SVN commit is __r38821__.			The first real SVN commit is __r38821__.
	The documentation repository switched from Subversion to Git on December 8th, 2020.			The documentation repository switched from Subversion to Git on December 8th, 2020.
	The last SVN commit is __r54737__.			The last SVN commit is __r54737__.
	The first real git commit hash is __3be01a475855e7511ad755b2defd2e0da5d58bbe__.			The first real git commit hash is __3be01a475855e7511ad755b2defd2e0da5d58bbe__.

	The FreeBSD `ports` repository switched from CVS to Subversion on July 14th, 2012.			The FreeBSD `ports` repository switched from CVS to Subversion on July 14th, 2012.
	The first real SVN commit is __r300894__.			The first real SVN commit is __r300894__.
				The ports repository switched from Subversion to Git on March 31, 2021.
				lwhsuUnsubmitted Not Done Inline Actions We use the date of `This is the first Git commit` in doc and src so I think we want April 6, 2021 here. lwhsu: We use the date of `This is the first Git commit` in doc and src so I think we want April 6…
				The last SVN commit is __r569609__
				The first real git commit hash is __ed8d3eda309dd863fb66e04bccaa513eee255cbf__.

	Subversion can be installed from the FreeBSD Ports Collection by issuing these commands:

	[source,shell]
	....
	# pkg install subversion
	....

	[[svn-getting-started]]
	=== Getting Started

	There are a few ways to obtain a working copy of the tree from Subversion.
	This section will explain them.

	[[svn-getting-started-direct-checkout]]
	==== Direct Checkout

	The first is to check out directly from the main repository.
	For the `src` tree, use:

	[source,shell]
	....
	% svn checkout svn+ssh://repo.freebsd.org/base/head /usr/src
	....

	For the `doc` tree, use:

	[source,shell]
	....
	% svn checkout svn+ssh://repo.freebsd.org/doc/head /usr/doc
	....

	For the `ports` tree, use:

	[source,shell]
	....
	% svn checkout svn+ssh://repo.freebsd.org/ports/head /usr/ports
	....

	[NOTE]
	====
	Though the remaining examples in this document are written with the workflow of working with the `src` tree in mind, the underlying concepts are the same for working with the `doc` and the `ports` tree.
	Ports related Subversion operations are listed in <<ports>>.
	====

	The above command will check out a `CURRENT` source tree as [.filename]#/usr/src/#, which can be any target directory on the local filesystem.
	Omitting the final argument of that command causes the working copy, in this case, to be named "head", but that can be renamed safely.

	`svn+ssh` means the SVN protocol tunnelled over SSH.
	The name of the server is `repo.freebsd.org`, `base` is the path to the repository, and `head` is the subdirectory within the repository.

	If your FreeBSD login name is different from the login name used on the local machine, either include it in the URL (for example `svn+ssh://jarjar@repo.freebsd.org/base/head`), or add an entry to [.filename]#~/.ssh/config# in the form:

	[.programlisting]
	....
	Host repo.freebsd.org
	User jarjar
	....

	This is the simplest method, but it is hard to tell just yet how much load it will place on the repository.

	[NOTE]
	====
	The `svn diff` does not require access to the server as SVN stores a reference copy of every file in the working copy.
	This, however, means that Subversion working copies are very large in size.
	====

	[[git-getting-started-base-layout]]
	==== `RELENG_*` Branches and General Layout

	In `ssh://gitrepo.freebsd.org/src.git`, _src_ refers to the source tree.
	Similarly, _ports_ refers to the ports tree, and so on.
	These are separate repositories with their own change number sequences, access controls and commit mail.

	For the src repository, `main` refers to the -CURRENT tree.
	For example, [.filename]#head/bin/ls# is what would go into [.filename]#/usr/src/bin/ls# in a release.
	Some key branches are:

	* _main_ which corresponds to `HEAD`, also known as `-CURRENT`.
	* _stable/n_ which corresponds to `RELENG_n`.
	* _releng/n.n_ which corresponds to `RELENG_n_n`.
	* _release/n.n.n_ which corresponds to `RELENG_n_n_n_RELEASE`.
	* _vendor*_ is the vendor branch import work area.

	[[git-getting-started-doc-layout]]
	==== FreeBSD Documentation Project Branches and Layout

	In `ssh://gitrepo.freebsd.org/doc.git`, _doc_ refers to the repository of the documentation tree.

	In general, most FreeBSD Documentation Project work will be done within the `main` branch of the documentation source tree.

	FreeBSD documentation is written and/or translated to various languages, each in a separate directory in the `main` branch.

	Each translation set contains several subdirectories for the various parts of the FreeBSD Documentation Project.
	A few noteworthy directories are:

	* _documentation/_ contains all the source code for the documentation part of the tree.
	* _documentation/content/LANG/articles/_ contains the source code for articles written by various FreeBSD contributors.
	* _documentation/content/LANG/books/_ contains the source code for the different books, such as the FreeBSD Handbook.
	* _website/_ contains the source code for the FreeBSD website.

	LANG above is the two character language code.
	All document source is encoded using Unicode.

	[[git-getting-started-ports-layout]]
	==== FreeBSD Ports Tree Branches and Layout

	In `ssh://gitrepo.freebsd.org/ports.git`, _ports_ refers to the repository root of the ports tree.

	In general, most FreeBSD port work will be done within the `main` branch of the ports tree which is the actual ports tree used to install software.
	Some other key locations are:

	* `yyyyQn` (a branch), where `yyyy` represents the current year and `n` represents the current quarter (e.g. 2021Q2), which receives mostly security and bugfixes.
	* release/`x.y.z` (a tag), which represents a release tag of the ports tree.
	* `n`-eol (a tag), which represents the end of life tag of FreeBSD branch `n.X`.

	[[svn-daily-use]]
	=== Daily Use

	This section will explain how to perform common day-to-day operations with Subversion.

	[[svn-daily-use-help]]
	==== Help

	SVN has built in help documentation.
	It can be accessed by typing:

	[source,shell]
	....
	% svn help
	....

	Additional information can be found in the http://svnbook.red-bean.com/[Subversion Book].

	[[svn-daily-use-checkout]]
	==== Checkout

	As seen earlier, to check out the FreeBSD head branch:

	[source,shell]
	....
	% svn checkout svn+ssh://repo.freebsd.org/base/head /usr/src
	....

	At some point, more than just `HEAD` will probably be useful, for instance when merging changes to stable/7.
	Therefore, it may be useful to have a partial checkout of the complete tree (a full checkout would be very painful).

	To do this, first check out the root of the repository:

	[source,shell]
	....
	% svn checkout --depth=immediates svn+ssh://repo.freebsd.org/base
	....

	This will give `base` with all the files it contains (at the time of writing, just [.filename]#ROADMAP.txt#) and empty subdirectories for `head`, `stable`, `vendor` and so on.

	Expanding the working copy is possible.
	Just change the depth of the various subdirectories:

	[source,shell]
	....
	% svn up --set-depth=infinity base/head
	% svn up --set-depth=immediates base/release base/releng base/stable
	....

	The above command will pull down a full copy of `head`, plus empty copies of every `release` tag, every `releng` branch, and every `stable` branch.

	If at a later date merging to `7-STABLE` is required, expand the working copy:

	[source,shell]
	....
	% svn up --set-depth=infinity base/stable/7
	....

	Subtrees do not have to be expanded completely.
	For instance, expanding only `stable/7/sys` and then later expand the rest of `stable/7`:

	[source,shell]
	....
	% svn up --set-depth=infinity base/stable/7/sys
	% svn up --set-depth=infinity base/stable/7
	....

	Updating the tree with `svn update` will only update what was previously asked for (in this case, `head` and `stable/7`; it will not pull down the whole tree.

	[[svn-daily-use-anonymous-checkout]]
	==== Anonymous Checkout

	It is possible to anonymously check out the FreeBSD repository with Subversion.
	This will give access to a read-only tree that can be updated, but not committed back to the main repository.
	To do this, use:

	[source,shell]
	....
	% svn co https://svn.FreeBSD.org/base/head /usr/src
	....

	More details on using Subversion this way can be found in link:{handbook}#svn[Using Subversion].

	[[svn-daily-use-updating-the-tree]]
	==== Updating the Tree

	To update a working copy to either the latest revision, or a specific revision:

	[source,shell]
	....
	% svn update
	% svn update -r12345
	....

	[[svn-daily-use-status]]
	==== Status

	To view the local changes that have been made to the working copy:

	[source,shell]
	....
	% svn status
	....

	To show local changes and files that are out-of-date do:

	[source,shell]
	....
	% svn status --show-updates
	....

	[[svn-daily-use-editing-and-committing]]
	==== Editing and Committing

	SVN does not need to be told in advance about file editing.

	To commit all changes in the current directory and all subdirectories:

	[source,shell]
	....
	% svn commit
	....

	To commit all changes in, for example, [.filename]#lib/libfetch/# and [.filename]#usr/bin/fetch/# in a single operation:

	[source,shell]
	....
	% svn commit lib/libfetch usr/bin/fetch
	....

	[[svn-daily-use-adding-and-removing]]
	==== Adding and Removing Files

	[NOTE]
	====
	Before adding files, get a copy of https://people.FreeBSD.org/~peter/auto-props.txt[auto-props.txt] (there is also a https://people.FreeBSD.org/~beat/cvs2svn/auto-props.txt[ports tree specific version]) and add it to [.filename]#~/.subversion/config# according to the instructions in the file.
	If you added something before reading this, use `svn rm --keep-local` for just added files, fix your config file and re-add them again.
	The initial config file is created when you first run a svn command, even something as simple as `svn help`.
	====

	Files are added to a SVN repository with `svn add`.
	To add a file named __foo__, edit it, then:

	[source,shell]
	....
	% svn add foo
	....

	[NOTE]
	====
	Most new source files should include a `$FreeBSD$` string near the start of the file.
	On commit, `svn` will expand the `$FreeBSD$` string, adding the file path, revision number, date and time of commit, and the username of the committer.
	Files which cannot be modified may be committed without the `$FreeBSD$` string.
	====

	Files can be removed with `svn remove`:

	[source,shell]
	....
	% svn remove foo
	....

	Subversion does not require deleting the file before using `svn rm`, and indeed complains if that happens.

	It is possible to add directories with `svn add`:

	[source,shell]
	....
	% mkdir bar
	% svn add bar
	....

	Although `svn mkdir` makes this easier by combining the creation of the directory and the adding of it:

	[source,shell]
	....
	% svn mkdir bar
	....

	Like files, directories are removed with `svn rm`.
	There is no separate command specifically for removing directories.

	[source,shell]
	....
	% svn rm bar
	....

	[[svn-daily-use-copying-and-moving]]
	==== Copying and Moving Files

	This command creates a copy of [.filename]#foo.c# named [.filename]#bar.c#, with the new file also under version control and with the full history of [.filename]#foo.c#:

	[source,shell]
	....
	% svn copy foo.c bar.c
	....

	This is usually preferred to copying the file with `cp` and adding it to the repository with `svn add` because this way the new file does not inherit the original one's history.

	To move and rename a file:

	[source,shell]
	....
	% svn move foo.c bar.c
	....

	[[svn-daily-use-log-and-annotate]]
	==== Log and Annotate

	`svn log` shows revisions and commit messages, most recent first, for files or directories.
	When used on a directory, all revisions that affected the directory and files within that directory are shown.

	`svn annotate`, or equally `svn praise` or `svn blame`, shows the most recent revision number and who committed that revision for each line of a file.

	[[svn-daily-use-diffs]]
	==== Diffs

	`svn diff` displays changes to the working copy.
	Diffs generated by SVN are unified and include new files by default in the diff output.

	`svn diff` can show the changes between two revisions of the same file:

	[source,shell]
	....
	% svn diff -r179453:179454 ROADMAP.txt
	....

	It can also show all changes for a specific changeset.
	This command shows what changes were made to the current directory and all subdirectories in changeset 179454:

	[source,shell]
	....
	% svn diff -c179454 .
	....

	[[svn-daily-use-reverting]]
	==== Reverting

	Local changes (including additions and deletions) can be reverted using `svn revert`.
	It does not update out-of-date files, but just replaces them with pristine copies of the original version.

	[[svn-daily-use-conflicts]]
	==== Conflicts

	If an `svn update` resulted in a merge conflict, Subversion will remember which files have conflicts and refuse to commit any changes to those files until explicitly told that the conflicts have been resolved.
	The simple, not yet deprecated procedure is:

	[source,shell]
	....
	% svn resolved foo
	....

	However, the preferred procedure is:

	[source,shell]
	....
	% svn resolve --accept=working foo
	....

	The two examples are equivalent.
	Possible values for `--accept` are:

	* `working`: use the version in your working directory (which one presumes has been edited to resolve the conflicts).
	* `base`: use a pristine copy of the version you had before `svn update`, discarding your own changes, the conflicting changes, and possibly other intervening changes as well.
	* `mine-full`: use what you had before `svn update`, including your own changes, but discarding the conflicting changes, and possibly other intervening changes as well.
	* `theirs-full`: use the version that was retrieved when you did `svn update`, discarding your own changes.

	=== Advanced Use

	[[svn-advanced-use-sparse-checkouts]]
	==== Sparse Checkouts

	SVN allows __sparse__, or partial checkouts of a directory by adding `--depth` to a `svn checkout`.

	Valid arguments to `--depth` are:

	* `empty`: the directory itself without any of its contents.
	* `files`: the directory and any files it contains.
	* `immediates`: the directory and any files and directories it contains, but none of the subdirectories' contents.
	* `infinity`: anything.

	The `--depth` option applies to many other commands, including `svn commit`, `svn revert`, and `svn diff`.

	Since `--depth` is sticky, there is a `--set-depth` option for `svn update` that will change the selected depth.
	Thus, given the working copy produced by the previous example:

	[source,shell]
	....
	% cd ~/freebsd
	% svn update --set-depth=immediates .
	....

	The above command will populate the working copy in _~/freebsd_ with [.filename]#ROADMAP.txt# and empty subdirectories, and nothing will happen when `svn update` is executed on the subdirectories.
	However, this command will set the depth for _head_ (in this case) to infinity, and fully populate it:

	[source,shell]
	....
	% svn update --set-depth=infinity head
	....

	[[svn-advanced-use-direct-operation]]
	==== Direct Operation

	Certain operations can be performed directly on the repository without touching the working copy.
	Specifically, this applies to any operation that does not require editing a file, including:

	* `log`, `diff`
	* `mkdir`
	* `remove`, `copy`, `rename`
	* `propset`, `propedit`, `propdel`
	* `merge`

	Branching is very fast.
	This command would be used to branch `RELENG_8`:

	[source,shell]
	....
	% svn copy svn+ssh://repo.freebsd.org/base/head svn+ssh://repo.freebsd.org/base/stable/8
	....

	This is equivalent to these commands which take minutes and hours as opposed to seconds, depending on your network connection:

	[source,shell]
	....
	% svn checkout --depth=immediates svn+ssh://repo.freebsd.org/base
	% cd base
	% svn update --set-depth=infinity head
	% svn copy head stable/8
	% svn commit stable/8
	....

	[[svn-advanced-use-merging]]
	==== Merging with SVN

	This section deals with merging code from one branch to another (typically, from head to a stable branch).

	[NOTE]
	====
	In all examples below, `$FSVN` refers to the location of the FreeBSD Subversion repository, `svn+ssh://repo.freebsd.org/base/`.
	====

	===== About Merge Tracking

	From the user's perspective, merge tracking information (or mergeinfo) is stored in a property called `svn:mergeinfo`, which is a comma-separated list of revisions and ranges of revisions that have been merged.
	When set on a file, it applies only to that file.
	When set on a directory, it applies to that directory and its descendants (files and directories) except for those that have their own `svn:mergeinfo`.

	It is _not_ inherited.
	For instance, [.filename]#stable/6/contrib/openpam/# does not implicitly inherit mergeinfo from [.filename]#stable/6/#, or [.filename]#stable/6/contrib/#. Doing so would make partial checkouts very hard to manage.
	Instead, mergeinfo is explicitly propagated down the tree.
	For merging something into [.filename]#branch/foo/bar/#, these rules apply:

	. If [.filename]#branch/foo/bar/# does not already have a mergeinfo record, but a direct ancestor (for instance, [.filename]#branch/foo/#) does, then that record will be propagated down to [.filename]#branch/foo/bar/# before information about the current merge is recorded.
	. Information about the current merge will _not_ be propagated back up that ancestor.
	. If a direct descendant of [.filename]#branch/foo/bar/# (for instance, [.filename]#branch/foo/bar/baz/#) already has a mergeinfo record, information about the current merge will be propagated down to it.

	If you consider the case where a revision changes several separate parts of the tree (for example, [.filename]#branch/foo/bar/# and [.filename]#branch/foo/quux/#), but you only want to merge some of it (for example, [.filename]#branch/foo/bar/#), you will see that these rules make sense.
	If mergeinfo was propagated up, it would seem like that revision had also been merged to [.filename]#branch/foo/quux/#, when in fact it had not been.

	[[merge-source]]
	===== Selecting the Source and Target Branch When Merging

	Merging to `stable/` branches should originate from `head/`. For example:

	[source,shell]
	....
	% svn merge -c r123456 ^/head/ stable/11
	% svn commit stable/11
	....

	Merges to `releng/` branches should always originate from the corresponding `stable/` branch.
	For example:

	[source,shell]
	....
	% svn merge -c r123456 ^/stable/11 releng/11.0
	% svn commit releng/11.0
	....

	[NOTE]
	====
	Committers are only permitted to commit to the `releng/` branches during a release cycle after receiving approval from the Release Engineering Team, after which only the Security Officer may commit to a `releng/` branch for a Security Advisory or Errata Notice.
	====

	All merges are merged to and committed from the root of the branch. All merges look like:

	[source,shell]
	....
	% svn merge -c r123456 ^/head/ checkout
	% svn commit checkout
	....

	Note that _checkout_ must be a complete checkout of the branch to which the merge occurs.

	[source,shell]
	....
	% svn merge -c r123456 ^/stable/10 releng/10.0
	....

	===== Preparing the Merge Target

	Due to the mergeinfo propagation issues described earlier, it is very important to never merge changes into a sparse working copy.
	Always use a full checkout of the branch being merged into.
	For instance, when merging from HEAD to 7, use a full checkout of stable/7:

	[source,shell]
	....
	% cd stable/7
	% svn up --set-depth=infinity
	....

	The target directory must also be up-to-date and must not contain any uncommitted changes or stray files.

	===== Identifying Revisions

	Identifying revisions to be merged is a must.
	If the target already has complete mergeinfo, ask SVN for a list:

	[source,shell]
	....
	% cd stable/6/contrib/openpam
	% svn mergeinfo --show-revs=eligible $FSVN/head/contrib/openpam
	....

	If the target does not have complete mergeinfo, check the log for the merge source.

	===== Merging

	Now, let us start merging!

	====== The Principles

	For example, To merge:

	* revision `$R`
	* in directory $target in stable branch $B
	* from directory $source in head
	* $FSVN is `svn+ssh://repo.freebsd.org/base`

	Assuming that revisions $P and $Q have already been merged, and that the current directory is an up-to-date working copy of stable/$B, the existing mergeinfo looks like this:

	[source,shell]
	....
	% svn propget svn:mergeinfo -R $target
	$target - /head/$source:$P,$Q
	....

	Merging is done like so:

	[source,shell]
	....
	% svn merge -c$R $FSVN/head/$source $target
	....

	Checking the results of this is possible with `svn diff`.

	The svn:mergeinfo now looks like:

	[source,shell]
	....
	% svn propget svn:mergeinfo -R $target
	$target - head/$source:$P,$Q,$R
	....

	If the results are not exactly as shown, assistance may be required before committing as mistakes may have been made, or there may be something wrong with the existing mergeinfo, or there may be a bug in Subversion.

	====== Practical Example

	As a practical example, consider this scenario.
	The changes to [.filename]#netmap.4# in r238987 are to be merged from CURRENT to 9-STABLE.
	The file resides in [.filename]#head/shared/man/man4#. According to <<svn-advanced-use-merging>>, this is also where to do the merge.
	Note that in this example all paths are relative to the top of the svn repository.
	For more information on the directory layout, see <<svn-getting-started-base-layout>>.

	The first step is to inspect the existing mergeinfo.

	[source,shell]
	....
	% svn propget svn:mergeinfo -R stable/9/shared/man/man4
	....

	Take a quick note of how it looks before moving on to the next step; doing the actual merge:

	[source,shell]
	....
	% svn merge -c r238987 svn+ssh://repo.freebsd.org/base/head/shared/man/man4 stable/9/shared/man/man4
	--- Merging r238987 into 'stable/9/shared/man/man4':
	U stable/9/shared/man/man4/netmap.4
	--- Recording mergeinfo for merge of r238987 into
	'stable/9/shared/man/man4':
	U stable/9/shared/man/man4
	....

	Check that the revision number of the merged revision has been added.
	Once this is verified, the only thing left is the actual commit.

	[source,shell]
	....
	% svn commit stable/9/shared/man/man4
	....

	===== Precautions Before Committing

	As always, build world (or appropriate parts of it).

	Check the changes with svn diff and `svn stat`.
	Make sure all the files that should have been added or deleted were in fact added or deleted.

	Take a closer look at any property change (marked by a `M` in the second column of `svn stat`).
	Normally, no svn:mergeinfo properties should be anywhere except the target directory (or directories).

	If something looks fishy, ask for help.

	===== Committing

	Make sure to commit a top level directory to have the mergeinfo included as well.
	Do not specify individual files on the command line.
	For more information about committing files in general, see the relevant section of this primer.

	[[svn-advanced-use-reverting-a-commit]]
	==== Reverting a Commit

	Reverting a commit to a previous version is fairly easy:

	[source,shell]
	....
	% svn merge -r179454:179453 ROADMAP.txt
	% svn commit
	....

	Change number syntax, with negative meaning a reverse change, can also be used:

	[source,shell]
	....
	% svn merge -c -179454 ROADMAP.txt
	% svn commit
	....

	This can also be done directly in the repository:

	[source,shell]
	....
	% svn merge -r179454:179453 svn+ssh://repo.freebsd.org/base/ROADMAP.txt
	....

	[NOTE]
	====
	It is important to ensure that the mergeinfo is correct when reverting a file to permit `svn mergeinfo --eligible` to work as expected.
	====

	Reverting the deletion of a file is slightly different.
	Copying the version of the file that predates the deletion is required.
	For example, to restore a file that was deleted in revision N, restore version N-1:

	[source,shell]
	....
	% svn copy svn+ssh://repo.freebsd.org/base/ROADMAP.txt@179454
	% svn commit
	....

	or, equally:

	[source,shell]
	....
	% svn copy svn+ssh://repo.freebsd.org/base/ROADMAP.txt@179454 svn+ssh://repo.freebsd.org/base
	....

	Do _not_ simply recreate the file manually and `svn add` it-this will cause history to be lost.

	[[svn-advanced-use-fixing-mistakes]]
	==== Fixing Mistakes

	While we can do surgery in an emergency, do not plan on having mistakes fixed behind the scenes.
	Plan on mistakes remaining in the logs forever.
	Be sure to check the output of `svn status` and `svn diff` before committing.

	Mistakes will happen but, they can generally be fixed without disruption.

	Take a case of adding a file in the wrong location.
	The right thing to do is to `svn move` the file to the correct location and commit.
	This causes just a couple of lines of metadata in the repository journal, and the logs are all linked up correctly.

	The wrong thing to do is to delete the file and then `svn add` an independent copy in the correct location.
	Instead of a couple of lines of text, the repository journal grows an entire new copy of the file.
	This is a waste.

	[[svn-getting-started-checkout-from-a-mirror]]
	==== Using a Subversion Mirror

	There is a serious disadvantage to this method: every time something is to be committed, a `svn relocate` to the main repository has to be done, remembering to `svn relocate` back to the mirror after the commit.
	Also, since `svn relocate` only works between repositories that have the same UUID, some hacking of the local repository's UUID has to occur before it is possible to start using it.

	[[svn-advanced-checkout-from-mirror]]
	===== Checkout from a Mirror

	Check out a working copy from a mirror by substituting the mirror's URL for `svn+ssh://repo.freebsd.org/base`.
	This can be an official mirror or a mirror maintained by using `svnsync`.

	[[svn-advanced-use-setting-up-svnsync]]
	===== Setting up a svnsync Mirror

	Avoid setting up a svnsync mirror unless there is a very good reason for it.
	Most of the time a `git` mirror is a better alternative.
	Starting a fresh mirror from scratch takes a long time.
	Expect a minimum of 10 hours for high speed connectivity.
	If international links are involved, expect this to take four to ten times longer.

	One way to limit the time required is to grab a https://download.freebsd.org/ftp/development/subversion/[seed file].
	It is large (~1GB) but will consume less network traffic and take less time to fetch than svnsync will.

	Extract the file and update it:

	[source,shell]
	....
	% tar xf svnmirror-base-r261170.tar.xz
	% svnsync sync file:///home/svnmirror/base
	....

	Now, set that up to run from man:cron[8], do checkouts locally, set up a svnserve server for local machines to talk to, etc.

	The seed mirror is set to fetch from `svn://svn.freebsd.org/base`.
	The configuration for the mirror is stored in `revprop 0` on the local mirror.
	To see the configuration, try:

	[source,shell]
	....
	% svn proplist -v --revprop -r 0 file:///home/svnmirror/base
	....

	Use `svn propset` to change things.

	[[svn-advanced-use-committing-high-ascii-data]]
	==== Committing High-ASCII Data

	Files that have high-ASCII bits are considered binary files in SVN, so the pre-commit checks fail and indicate that the `mime-type` property should be set to `application/octet-stream`.
	However, the use of this is discouraged, so please do not set it.
	The best way is always avoiding high-ASCII data, so that it can be read everywhere with any text editor but if it is not avoidable, instead of changing the mime-type, set the `fbsd:notbinary` property with `propset`:

	[source,shell]
	....
	% svn propset fbsd:notbinary yes foo.data
	....

	[[svn-advanced-use-maintaining-a-project-branch]]
	==== Maintaining a Project Branch

	A project branch is one that is synced to head (or another branch) is used to develop a project then commit it back to head.
	In SVN, "dolphin" branching is used for this.
	A "dolphin" branch is one that diverges for a while and is finally committed back to the original branch.
	During development code migration in one direction (from head to the branch only).
	No code is committed back to head until the end.
	After the branch is committed back at the end, it is dead (although a new branch with the same name can be created after the dead one is deleted).

	As per https://people.FreeBSD.org/\~peter/svn_notes.txt[https://people.FreeBSD.org/~peter/svn_notes.txt], work that is intended to be merged back into HEAD should be in [.filename]#base/projects/#.
	If the work is beneficial to the FreeBSD community in some way but not intended to be merged directly back into HEAD then the proper location is [.filename]#base/user/username/#.
	https://svnweb.freebsd.org/base/projects/GUIDELINES.txt[This page] contains further details.

	To create a project branch:

	[source,shell]
	....
	% svn copy svn+ssh://repo.freebsd.org/base/head svn+ssh://repo.freebsd.org/base/projects/spif
	....

	To merge changes from HEAD back into the project branch:

	[source,shell]
	....
	% cd copy_of_spif
	% svn merge svn+ssh://repo.freebsd.org/base/head
	% svn commit
	....

	It is important to resolve any merge conflicts before committing.

	=== Some Tips

	In commit logs etc., "rev 179872" is spelled "r179872" as per convention.

	Speeding up svn is possible by adding these entries to [.filename]#~/.ssh/config#:

	[source,shell]
	....
	Host *
	ControlPath ~/.ssh/sockets/master-l-r@h:p
	ControlMaster auto
	ControlPersist yes
	....

	and then typing

	[source,shell]
	....
	mkdir ~/.ssh/sockets
	....

	Checking out a working copy with a stock Subversion client without FreeBSD-specific patches (`OPTIONS_SET=FREEBSD_TEMPLATE`) will mean that `$FreeBSD$` tags will not be expanded.
	Once the correct version has been installed, trick Subversion into expanding them like so:

	[source,shell]
	....
	% svn propdel -R svn:keywords .
	% svn revert -R .
	....

	This will wipe out uncommitted patches.

	It is possible to automatically fill the "Sponsored by" and "MFC after" commit log fields by setting "freebsd-sponsored-by" and "freebsd-mfc-after" fields in the "[miscellany]" section of the [.filename]#~/.subversion/config# configuration file.
	For example:

	[.programlisting]
	....
	freebsd-sponsored-by = The FreeBSD Foundation
	freebsd-mfc-after = 2 weeks
	....

	[[conventions]]			[[conventions]]
	== Setup, Conventions, and Traditions			== Setup, Conventions, and Traditions

	There are a number of things to do as a new developer.			There are a number of things to do as a new developer.
	The first set of steps is specific to committers only.			The first set of steps is specific to committers only.
	These steps must be done by a mentor for those who are not committers.			These steps must be done by a mentor for those who are not committers.

	[[conventions-committers]]			[[conventions-committers]]
	=== For New Committers			=== For New Committers

	Those who have been given commit rights to the FreeBSD repositories must follow these steps.			Those who have been given commit rights to the FreeBSD repositories must follow these steps.

	* Get mentor approval before committing each of these changes!			* Get mentor approval before committing each of these changes!
	* The [.filename]#.ent# and [.filename]#.xml# files mentioned below exist in the FreeBSD Documentation Project SVN repository at `svn+ssh://repo.FreeBSD.org/doc/`.			* The [.filename]#.ent# and [.filename]#.xml# files mentioned below exist in the FreeBSD Documentation Project SVN repository at `svn+ssh://repo.FreeBSD.org/doc/`.
	* New files that do not have the `FreeBSD=%H svn:keywords` property will be rejected when attempting to commit them to the repository. Be sure to read <<svn-daily-use-adding-and-removing>> regarding adding and removing files. Verify that [.filename]#~/.subversion/config# contains the necessary "auto-props" entries from [.filename]#auto-props.txt# mentioned there.
	* All [.filename]#src# commits go to FreeBSD-CURRENT first before being merged to FreeBSD-STABLE. The FreeBSD-STABLE branch must maintain ABI and API compatibility with earlier versions of that branch. Do not merge changes that break this compatibility.			* All [.filename]#src# commits go to FreeBSD-CURRENT first before being merged to FreeBSD-STABLE. The FreeBSD-STABLE branch must maintain ABI and API compatibility with earlier versions of that branch. Do not merge changes that break this compatibility.

	[[commit-steps]]			[[commit-steps]]
	[.procedure]			[.procedure]
	====			====
	Procedure 1. Steps for New Committers			Procedure 1. Steps for New Committers

	. Add an Author Entity			. Add an Author Entity
	▲ Show 20 Lines • Show All 1,570 Lines • Show Last 20 Lines