[COMING SOON] Vendor branches with Mercurial

Vendor branches with Mercurial

Create a new vendor branch
Find our local patches
Prepare a legacy vendor branch from CVS
Import a new version on a vendor branch

Vendor branches with Mercurial

WORK IN PROGRESS -- NOT TESTED OR REVIEWED YET

Create a new vendor branch

You want to import a copy of Acme Widgetmaker. It is Apache2-licensed. It will live in src/external/apache2/widgetmaker, and we will track upstream releases on the vendor branch “vendor/widgetmaker”.

Create a shared repository clone (requires “share” extension):
```
$ hg share -U src src-vendor
```
This is another working tree for the same underlying repository data, so all the same changesets and branches are available. (Not strictly necessary, but it's much faster than waiting for “hg update” to create or delete gigabytes of data across hundreds of thousands of files as you switch between the vendor branch and trunk, and it takes much less disk space than regular “hg clone”.) The “-U” option leaves the working tree empty, checked out at the null revision, to start the vendor branch on its own history; if you forget it, you can do “hg update null” instead.

Unpack the distribution into the right path in the shared repository:

$ cd ../src-vendor
$ mkdir -p external/apache2/widgetmaker/dist
$ tar -C external/apache2/widgetmaker/dist \
    --strip-components=1 \
    -xvzf /path/to/widgetmaker-1.23.tar.gz

Commit it on the vendor branch:

$ hg branch vendor/widgetmaker
$ hg addremove
$ hg commit -m 'Import widgetmaker-1.23'

Merge the vendor branch into trunk—this will populate external/apache2/widgetmaker/dist/ on trunk with the content of Acme Widgetmaker 1.23 on the vendor branch:
```
$ cd ../src
$ hg update trunk
$ hg merge vendor/widgetmaker
$ hg commit -m 'Merge widgetmaker-1.23'
```
Tag it for reference:
```
$ hg tag vendor/widgetmaker-1.23
```

Find our local patches

Developers can commit on trunk to files under external/apache2/widgetmaker/dist/, creating local patches. Local patches incur a maintenance burden and may create bugs, so we should generally try to keep them to a minimum and/or submit them back upstream if applicable. To find the local patches on trunk:

$ cd src/external/apache2/widgetmaker/dist
$ hg diff --from vendor/widgetmaker

A release branch such as “netbsd-11” may not be on the latest version. In that case, you can consult doc/3RDPARTY to find which version it's on, and use the tag to diff:

$ hg diff --from vendor/widgetmaker-1.23

Alternatively, you can diff from the latest revision of the branch that has been merged into the current branch:

$ hg diff --from 'max(ancestors(.) & branch("vendor/widgetmaker"))'

Prepare a legacy vendor branch from CVS

XXX Explain the scenario.

XXX Clear the vendor branch of stray files.
XXX Merge with “-t :local” to tell hg that the vendor branch is already fully merged.
XXX Commit and verify the changeset has no changes from trunk as p1, but has the vendor branch as p2.

Import a new version on a vendor branch

When Acme Widgetmaker 1.24 is released, it may be time for us to import a new version—and make sure we don't lose any local patches we made, in case they are still applicable.

Create a shared repository for the vendor work tree if you haven't already:
```
$ hg share -U src src-vendor
```

Switch to the vendor branch and replace its content wholesale (except for .hgtags, which is where the previous tag is stored):

$ cd src-vendor
$ hg update vendor/widgetmaker
$ hg revert -r null -C --all -X .hgtags
$ mkdir -p external/apache2/widgetmaker/dist
$ tar -C external/apache2/widgetmaker/dist \
    --strip-components=1 \
    -xvzf /path/to/widgetmaker-1.24.tar.gz

Auto-detect additions, removals, and renames; then commit and tag it for reference:
```
$ hg addremove
$ hg commit -m 'Import widgetmaker-1.24'
$ hg tag vendor/widgetmaker-1.24
```
Note: You can also use, for example, “hg addremove -s 80” to auto-detect renames with 80% similarity; the default is to detect renames only if they have 100% similarity, i.e., if they are byte-for-byte identical. If you lower the similarity threshold, you should verify the renames are correct; somteimes automatic rename detection goes awry, especially with long blocks of copying terms copied and pasted into many files.

Merge the vendor branch into trunk:

$ cd ../src
$ hg merge vendor/widgetmaker

If there are merge conflicts, resolve them and mark them resolved with “hg resolve”:
```
$ edit sys/kern/sys_descrip.c
$ hg resolve -m sys/kern/kern_descrip.c
```
You can also use it to re-merge with different merge tools, e.g. “-t :local” to take our local version and discard upstream changes, or “-t :other” to take the upstream version and discard local changes.
Review the new changes being imported, and review our local changes from upstream:
```
$ hg diff
$ hg diff --from 'p2()'
```
Commit the merge, and push it:
```
$ hg diff
$ hg commit -m 'Merge widgetmaker-1.24'
$ hg push
```
(You can also push it to a draft topic for review first.)