Fix a number of typos. Note why one would prefer publishing a repo over
phabricator. Try to minimize use of contractions. Clarify the mysterious 'source
of truth' phrase.
Noticed by: Pau Amma (except the contractions)
This chapter follows the convention that the `freebsd` origin is the source of truth. If you use a different convention, replace `freebsd` with your name as appopriate.
This chapter follows the convention that the `freebsd` origin is the origin name for the official FreeBSD git repository.
If you use a different convention, replace `freebsd` with the name you use instead in the examples below.
====
We'll explore an example for updating NetBSD's mtree that's in our
tree. The vendor branch for this is `vendor/NetBSD/mtree`.
We will explore an example for updating NetBSD's mtree that is in our tree.
The vendor branch for this is `vendor/NetBSD/mtree`.
==== Updating an old vendor import
Since the trees we have in vendor branches are usually a tiny subset of
the FreeBSD, it's best to do them with work trees since the process is
quite fast. Make sure that whatever directory you choose (the
`../mtree`) argument is empty and doesn't conflict.
The vendor trees usually have only the subset of the third-party software that is appropriate to FreeBSD.
These trees are usually tiny in comparison to the FreeBSD tree.
Git workrees are thus quite small and fast and the preferred method to use.
Make sure that whatever directory you choose below (the `../mtree`) does not currently exist.
[source,shell]
....
% git worktree add ../mtree vendor/NetBSD/mtree
@ -272,10 +273,9 @@ quite fast. Make sure that whatever directory you choose (the
Prepare a full, clean tree of the vendor sources. Import everything but merge only what is needed.
I have my copy of NetBSD checked out from their GitHub mirror in
`~/git/NetBSD`, so I'll update from there: Note that "upstream" might
have added or removed files, so we want to make sure deletions are
propagated as well. rsync(1) is commonly installed, so I'll use that.
This example assumes the NetBSD checked out from their GitHub mirror in `~/git/NetBSD`.
Note that "upstream" might have added or removed files, so we want to make sure deletions are propagated as well.
rsync(1) is commonly installed, so I'll use that.
[source,shell]
....
% cd ../mtree
@ -295,9 +295,9 @@ Note: I run the `git diff` and `git status` commands to make sure nothing weird
was present. Also I used `-m` to illustrate, but you should compose a proper
message in an editor (using a commit message template).
It's also important to create an annotated tag, otherwise the push
It is also important to create an annotated tag, otherwise the push
will be rejected. Only annotated tags are allowed to be pushed. The
annoated tag gives you a chance to enter a commit message. Enter
annotated tag gives you a chance to enter a commit message. Enter
the version you are importing, along with any salient new features
or fixes in that version.
@ -336,7 +336,7 @@ The easiest way to do this would be to create a side branch with the **contents*
% git merge freebsd/main
....
Typically, there would be no merge conflicts here (because developers tends to work on different components).
Typically, there would be no merge conflicts here (because developers tend to work on different components).
In the worst case scenario, you would still have to resolve merge conflicts, if there was any, but this
should be really rare.
@ -359,9 +359,9 @@ Examine the tree against `merge_result` to make sure that you haven't missed del
% git diff merge_result
....
==== Pushing the changes
Once you are sure that you have a set of deltas you think is good, you can push it to
a fork off github or gitlab for others to review. Once nice thin about Git is that it
allows you to publish rough drafts of your work for others to review.
Once you are sure that you have a set of deltas you think is good, you can push it to a fork off github or gitlab for others to review.
Once nice thing about Git is that it allows you to publish rough drafts of your work for others to review.
While phabricator is good for content review, publishing the updated vendor branch and merge commits lets others check the details as they will eventually appear in the repository.
After review, when you are sure it is a good change, you can push it to the FreeBSD repo:
[source,shell]
@ -370,11 +370,11 @@ After review, when you are sure it is a good change, you can push it to the Free
....
=== Creating a new vendor branch
There's a number of ways to create a new vendor branch. The recommended way is
to create a new repository and then merge that with FreeBSD. Let's say
we're importing `glorbnitz` into the FreeBSD tree, release 3.1415. For
the sake of simplicity, we'll not trim this release. It's a user
command that puts the nitz device into different magical glorb states.
There are a number of ways to create a new vendor branch.
The recommended way is to create a new repository and then merge that with FreeBSD.
If one is importing `glorbnitz` into the FreeBSD tree, release 3.1415.
For the sake of simplicity, we will not trim this release.
It is a simple user command that puts the nitz device into different magical glorb states and is small enough trimming will not save much.
==== Create the repo
[source,shell]
@ -388,13 +388,11 @@ command that puts the nitz device into different magical glorb states.
At this point, you have a new repo, where all new commits will go on
the `vendor/glorbnitz` branch.
(Git professionals can also do this right in their FreeBSD clone, if they know
how to create a new root commit that's not attached to anything, e.g.
`git checkout --orphan vendor/glorbnitz`)
Git experts can also do this right in their FreeBSD clone, using `git checkout --orphan vendor/glorbnitz` if they are more comfortable with that.
==== Copy the sources in
Since this is a new import, you can just cp the sources in, or use tar or
even rsync as shown above. And we'll add everything, assuming no dot files.
Since this is a new import, you can just cp the sources in, or use tar or even rsync as shown above.
And we will add everything, assuming no dot files.
[source,shell]
....
% cp -r ~/glorbnitz/* .
@ -425,14 +423,14 @@ to an end.
==== Tag and push
Steps from here on out are much the same as they are in the case of
updating a vendor branch, though w/o the updating the vendor
updating a vendor branch, though without the updating the vendor
Warner Losh
3 years ago