committer handbook: Fix typos and reformat
Fix a few typos and reformat a few paragraphs to one line per sentence style. Try to use repository insteast of 'repo' or even 'source of truth'. Clarify a few places and fix some grammar errors. Submitted by: Pau Amma
This commit is contained in:
Warner Losh
parent
a941df226d
commit
d5ea2ebac2
1 changed files with 50 additions and 70 deletions
|
|
@ -1393,22 +1393,15 @@ How so do that is specific to the software being imported and is beyond the scop
|
|||
|
||||
=== FreeBSD Src Committer Transition Guide
|
||||
|
||||
This section is designed to walk people through the conversion
|
||||
process from Subversion to Git, written from the source committer's point
|
||||
of view.
|
||||
This section is designed to walk people through the conversion process from Subversion to Git, written from the source committer's point of view.
|
||||
|
||||
==== Migrating from a Subversion tree
|
||||
|
||||
This section will cover a couple of common scenarios for migrating
|
||||
from using the FreeBSD Subversion repo to the FreeBSD source git repo. The
|
||||
FreeBSD Git conversion is still in beta status, so some minor things
|
||||
may change between this and going into production.
|
||||
|
||||
Before you git started, you'll need a copy of Git. Any Git will do,
|
||||
though the latest ones are always recommended. Either build it from
|
||||
ports, or install it using pkg (though some folks might use `su` or
|
||||
`doas` instead of `sudo`):
|
||||
This section will cover a couple of common scenarios for migrating from using the FreeBSD Subversion repo to the FreeBSD source git repo.
|
||||
The FreeBSD Git conversion is still in beta status, so some minor things may change between this and going into production.
|
||||
|
||||
The fist thing to do is install git. Any version of Git will do, though the latest one in ports / packages generally will be good.
|
||||
Either build it from ports, or install it using pkg (though some folks might use `su` or `doas` instead of `sudo`):
|
||||
|
||||
[source,shell]
|
||||
....
|
||||
|
|
@ -1417,87 +1410,79 @@ ports, or install it using pkg (though some folks might use `su` or
|
|||
|
||||
===== No staged changes migration
|
||||
|
||||
If you have no changes pending, the migration is straight forward. In
|
||||
this, you abandon the Subversion tree and clone the Git repo. It's
|
||||
likely best to retain your subversion tree, in case there's something
|
||||
you've forgotten about there. First, let's clone a repo:
|
||||
If you have no changes pending, the migration is straightforward.
|
||||
In this, you abandon the Subversion tree and clone the Git repoository.
|
||||
It's likely best to retain your subversion tree, in case there's something you've forgotten about there.
|
||||
First, let's clone the repository:
|
||||
[source,shell]
|
||||
....
|
||||
% git clone -o freebsd --config remote.freebsd.fetch='+refs/notes/*:refs/notes/*' https://git.freebsd.org/src.git freebsd-src
|
||||
....
|
||||
will create a clone of the FreeBSD src repo into a subdirectory called
|
||||
`freebsd-src` and include the 'notes' about the revisions.
|
||||
The current plan for GitHub mirroring is to mirror to
|
||||
https://github.com/freebsd/freebsd.git as well. When the transition
|
||||
starts, the github `master` branch will be frozen. We will be using the name `main` instead
|
||||
of `master` that was used in the beta version of the github.com mirror.
|
||||
The exact logistics of this are still being finalized, as there are over 2k forks and 5k stars.
|
||||
We will also mirror the repo to gitlab at https://gitlab.com/FreeBSD/src.git .
|
||||
Its transition plan is also being finalized.
|
||||
will create a clone of the FreeBSD src repository into a subdirectory called `freebsd-src` and include the 'notes' about the revisions.
|
||||
We are currently mirroring the source repository to https://github.com/freebsd/freebsd-src.git as well.
|
||||
https://github.com/freebsd/freebsd-legacy.git has the old github mirror with the old hashes should you need that for your migration.
|
||||
The github `master` branch has been frozen.
|
||||
As the default in git has change, we've shifted from `master` to `main`, the new repository uses `main`.
|
||||
We also mirror the repository to gitlab at https://gitlab.com/FreeBSD/src.git .
|
||||
|
||||
It's useful to have the old Subversion revisions available. This data is stored
|
||||
using Git notes, but Git doesn't fetch those by default. The --config
|
||||
and the argument above changed the default to fetch the notes. If
|
||||
you've cloned the repo without this, or wish to add notes to an
|
||||
previously clone repository, use the following commands:
|
||||
It's useful to have the old Subversion revisions available.
|
||||
This data is stored using Git notes, but Git doesn't fetch those by default.
|
||||
The --config and the argument above changed the default to fetch the notes.
|
||||
If you've cloned the repository without this, or wish to add notes to a previously clone repository, use the following commands:
|
||||
[source,shell]
|
||||
....
|
||||
% git config --add remote.freebsd.fetch "+refs/notes/*:refs/notes/*"
|
||||
% git fetch
|
||||
....
|
||||
At this point you have the src checked out into a Git tree, ready to
|
||||
do other things.
|
||||
At this point you have the src checked out into a Git tree, ready to do other things.
|
||||
|
||||
===== But I have changes that I've not committed
|
||||
|
||||
If you are migrating from a tree that has changes you've not yet
|
||||
committed to FreeBSD, you'll need to follow the steps from the
|
||||
previous section first, and then follow these.
|
||||
If you are migrating from a tree that has changes you've not yet committed to FreeBSD, you'll need to follow the steps from the previous section first, and then follow these.
|
||||
[source,shell]
|
||||
....
|
||||
% cd path-to-svn-checkout-tree
|
||||
% svn diff > /tmp/src.diff
|
||||
% cd mumble/freebsd-src
|
||||
% cd _mumble_/freebsd-src
|
||||
% git checkout -b working
|
||||
....
|
||||
This will create a diff of your current changes. The last command
|
||||
creates a branch called `working` though you can call it whatever you
|
||||
want.
|
||||
This will create a diff of your current changes.
|
||||
The last command creates a branch called `working` though you can call it whatever you want.
|
||||
|
||||
[source,shell]
|
||||
....
|
||||
% git apply /tmp/src.diff
|
||||
....
|
||||
this will apply all your pending changes to the working tree. This
|
||||
doesn't commit the change, so you'll need to make this permanent:
|
||||
this will apply all your pending changes to the working tree.
|
||||
This doesn't commit the change, so you'll need to make this permanent:
|
||||
|
||||
[source,shell]
|
||||
....
|
||||
% git add _files_
|
||||
% git commit
|
||||
....
|
||||
|
||||
The last command will commit these changes to the branch. The editor
|
||||
will prompt you for a commit message. Enter one as if you were
|
||||
committing to FreeBSD.
|
||||
The last command will commit these changes to the branch.
|
||||
The editor will prompt you for a commit message.
|
||||
Enter one as if you were committing to FreeBSD.
|
||||
|
||||
At this point, your work is preserved, and in the Git repo.
|
||||
At this point, your work is preserved, and in the Git repository.
|
||||
|
||||
===== Keeping current
|
||||
|
||||
So, time passes. It's time now to update the tree for the latest
|
||||
changes upstream. When you checkout `main` make sure that you have no
|
||||
diffs. It's a lot easier to commit those to a branch (or use `git
|
||||
stash`) before doing the following.
|
||||
So, time passes.
|
||||
It's time now to update the tree for the latest changes upstream.
|
||||
When you checkout `main` make sure that you have no diffs.
|
||||
It's a lot easier to commit those to a branch (or use `git stash`) before doing the following.
|
||||
|
||||
If you are used to `git pull`, I would strongly recommend using the
|
||||
`--ff-only` option, and further setting it as the default option.
|
||||
Alternatively, `git pull --rebase` is useful if you have changes staged
|
||||
in the main directory.
|
||||
If you are used to `git pull`, we strongly recommend using the `--ff-only` option, and further setting it as the default option.
|
||||
Alternatively, `git pull --rebase` is useful if you have changes staged in the main branch.
|
||||
|
||||
[source,shell]
|
||||
....
|
||||
% git config --global pull.ff only
|
||||
....
|
||||
You may need to omit the --global if you want this setting to only this repository.
|
||||
|
||||
[source,shell]
|
||||
....
|
||||
|
|
@ -1506,9 +1491,8 @@ in the main directory.
|
|||
% git pull (--ff-only|--rebase)
|
||||
....
|
||||
|
||||
There is a common trap, that the combination command `git pull` will
|
||||
try to perform a merge, which would sometimes creates a merge commit
|
||||
sha that didn't exist before. This can be harder to recover from.
|
||||
There is a common trap, that the combination command `git pull` will try to perform a merge, which would sometimes creates a merge commit sha that didn't exist before.
|
||||
This can be harder to recover from.
|
||||
|
||||
The longer form is also recommended.
|
||||
|
||||
|
|
@ -1551,19 +1535,16 @@ that they exactly match the passwd entry in FreeBSD cluster. Use
|
|||
....
|
||||
freefall% gen-gitconfig.sh
|
||||
....
|
||||
on freefall.freebsd.org to get recipe that you can use directly, assuming
|
||||
/usr/local/bin is in the PATH.
|
||||
on freefall.freebsd.org to get a recipe that you can use directly, assuming /usr/local/bin is in the PATH.
|
||||
|
||||
The below command merges the 'working' branch into the upstream main line.
|
||||
It's important that you curate your changes to be just
|
||||
like you want them in the FreeBSD source repo before doing this.
|
||||
It's important that you curate your changes to be just like you want them in the FreeBSD source repo before doing this.
|
||||
[source,shell]
|
||||
....
|
||||
% git push freebsd working:main
|
||||
....
|
||||
|
||||
If your push is rejected due to losing a commit race, rebase your branch
|
||||
before trying again:
|
||||
If your push is rejected due to losing a commit race, rebase your branch before trying again:
|
||||
[source,shell]
|
||||
....
|
||||
% git checkout working
|
||||
|
|
@ -1593,13 +1574,12 @@ hash you can use to refer to this commit.
|
|||
|
||||
==== Migrating from GitHub fork
|
||||
|
||||
Note: as of this writing, the https://github.com/freebsd/freebsd-src
|
||||
Note: as of this writing, https://github.com/freebsd/freebsd-src
|
||||
is mirroring all official branches, along with a `master` branch which
|
||||
is the leagcy svn2git result. The `master` branch will not be updated anymore,
|
||||
is the legacy svn2git result. The `master` branch will not be updated anymore,
|
||||
and the [last commit](https://github.com/freebsd/freebsd-src/commit/de1aa3dab23c06fec962a14da3e7b4755c5880cf)
|
||||
contains the instructions of migrating to new `main` branch.
|
||||
We'll likely retain the `master` branch for a certain time, but in the future
|
||||
it will only be kept in the
|
||||
contains the instructions for migrating to the new `main` branch.
|
||||
We'll retain the `master` branch for a certain time, but in the future it will only be kept in the
|
||||
[freebsd-legacy](https://github.com/freebsd/freebsd-legacy) repository.
|
||||
|
||||
When migrating branches from a github fork from the old github mirror
|
||||
|
|
@ -1616,15 +1596,15 @@ This also assumes a clean tree before starting...
|
|||
....
|
||||
|
||||
===== Rebase all your WIP branches.
|
||||
For each branch FOO, do the following after fetching the `freebsd` sources and creating a local `main` reference with the above checkout:
|
||||
For each branch FOO, do the following after fetching the `freebsd` sources and creating a local `main` branch with the above checkout:
|
||||
[source,shell]
|
||||
....
|
||||
% git rebase -i freebsd/master FOO --onto main
|
||||
....
|
||||
And you'll now be tracking the official source of truth.
|
||||
And you'll now be tracking the official repository.
|
||||
You can then follow the `Keeping Current` section above to stay up to date.
|
||||
|
||||
If you need to then commit work to FreeBSD, you can do so following the `Time to push changes upstream` instructions.
|
||||
If you need to then commit work to FreeBSD, you can do so following the `Time to push changes upstream` instructions.
|
||||
You'll need to do the following once to update the push URL if you are a FreeBSD committer:
|
||||
[source,shell]
|
||||
....
|
||||
|
|
|
|||
Loading…
Reference in a new issue