diff options
Diffstat (limited to 'documentation/content/en/articles/committers-guide/_index.adoc')
| -rw-r--r-- | documentation/content/en/articles/committers-guide/_index.adoc | 54 |
1 files changed, 42 insertions, 12 deletions
diff --git a/documentation/content/en/articles/committers-guide/_index.adoc b/documentation/content/en/articles/committers-guide/_index.adoc index bd16cc3585..26bb41e98b 100644 --- a/documentation/content/en/articles/committers-guide/_index.adoc +++ b/documentation/content/en/articles/committers-guide/_index.adoc @@ -188,8 +188,7 @@ Rather than suggest a single way, here are some links to sites that describe var Protect the private key and passphrase. If either the private key or passphrase may have been compromised or disclosed, immediately notify mailto:accounts@FreeBSD.org[accounts@FreeBSD.org] and revoke the key. -Committing the new key is shown in crossref:committers-guide[commit-steps, Steps -for New Committers]. +Committing the new key is shown in crossref:committers-guide[commit-steps, Steps for New Committers]. [[kerberos-ldap]] == Kerberos and LDAP web Password for FreeBSD Cluster @@ -199,7 +198,6 @@ The Kerberos password also serves as the LDAP web password, since LDAP is proxyi Some of the services which require this include: * https://bugs.freebsd.org/bugzilla[Bugzilla] -* https://ci.freebsd.org[Jenkins] To create a new Kerberos account in the FreeBSD cluster, or to reset a Kerberos password for an existing account using a random password generator: @@ -834,8 +832,10 @@ To abort and get back to the state before "git rebase", run "git rebase --abort" Could not apply 646e0f9cda11... no color ls .... which looks scary. + If you bring up an editor, you will see it is a typical 3-way merge conflict resolution that you may be familiar with from other source code systems (the rest of ls.c has been omitted): [source,shell] +.... <<<<<<< HEAD #ifdef COLORLS_NEW #include <terminfo.h> @@ -845,7 +845,9 @@ If you bring up an editor, you will see it is a typical 3-way merge conflict res #include <termcap.h> >>>>>>> 646e0f9cda11... no color ls .... + The new code is first, and your code is second. + The right fix here is to just add a #undef COLORLS_NEW before #ifdef and then delete the old changes: [source,shell] .... @@ -854,6 +856,7 @@ The right fix here is to just add a #undef COLORLS_NEW before #ifdef and then de #include <terminfo.h> .... save the file. + The rebase was interrupted, so you have to complete it: [source,shell] .... @@ -1392,7 +1395,7 @@ Here 'good' means: . All the right files, and none of the wrong ones, were merged into contrib/glorbnitz. . No other changes are in the tree. . The commit messages look crossref:committers-guide[commit-log-message,good]. It should contain a summary of what's changed since the last merge to the FreeBSD `main` branch and any caveats. -. UPDATING should be updated if there is anything of note, such as user visible changes, important upgrade concerns, etc. +. `RELNOTES` and `UPDATING` should be updated if there is anything of note, such as user visible changes, important upgrade concerns, etc. [NOTE] ==== @@ -1609,9 +1612,9 @@ The following answer assumes you committed to `main` and want to create a branch [source,shell] .... -% git branch issue # Create the 'issue' branch -% git reset --hard freebsd/main # Reset 'main' back to the official tip -% git checkout issue # Back to where you were +% git checkout -b issue # Create the 'issue' branch +% git checkout -B main freebsd/main # Reset main to upstream +% git checkout issue # Back to where you were .... ===== Ooops! I committed something to the wrong branch! @@ -1632,8 +1635,15 @@ It also assumes that it's the last commit on wilma (hence using wilma in the `gi % git reset --hard HEAD^ # move what wilma refers to back 1 commit .... -Git experts would first rewind the wilma branch by 1 commit, switch over to fred and then use `git reflog` to see what that 1 deleted commit was and -cherry-pick it over. +If it is not the last commit, you can cherry-pick that one change from wilma onto fred, then use `git rebase -i` to remove the change from wilma. + +[source,shell] +.... +# We're on branch wilma +% git checkout fred # move to fred branch +% git cherry-pick HASH_OF_CHANGE # copy the misplaced commit +% git rebase -i main wilma # drop the cherry-picked change +.... **Q:** But what if I want to commit a few changes to `main`, but keep the rest in `wilma` for some reason? @@ -1748,6 +1758,8 @@ How do I recover? **A:** This can happen when you invoke the pull with your development branch checked out. +Many developers use `git pull --rebase` to avoid this situation. + Right after the pull, you will have the new merge commit checked out. Git supports a `HEAD^#` syntax to examine the parents of a merge commit: @@ -1762,9 +1774,11 @@ Then you simply reset your branch to the corresponding `HEAD^#`: [source,shell] .... -git reset --hard HEAD^2 +git reset --hard HEAD^1 .... +In addition, a `git pull --rebase` at this stage will rebase your changes to 'main' to the latest 'freebsd/main'. + **Q:** But I also need to fix my `main` branch. How do I do that? **A:** Git keeps track of the remote repository branches in a `freebsd/` namespace. @@ -1877,6 +1891,14 @@ Once you're done, `git commit` and you'll have the remainder in your tree. You can run it multiple times as well, and even over multiple files (though I find it easier to do one file at a time and use the `git rebase -i` to fold the related commits together). +===== Joining the FreeBSD GitHub oranization. + +**Q:** How do I join the FreeBSD GitHub organization? + +**A:** Please see https://wiki.freebsd.org/GitHub#Joining_the_Organisation[our GitHub Wiki Info] page for details. +Briefly, all FreeBSD committers may join. +Those who are not committers who request joining will be considered on a case by case basis. + ==== Cloning and Mirroring **Q:** I'd like to mirror the entire Git repository, how do I do that? @@ -2462,15 +2484,16 @@ The subject should, by itself, allow the reader to quickly determine if the chan The subject line should be as short as possible while still retaining the required information. This is to make browsing Git log more efficient, and so that git log --oneline can display the short hash and subject on a single 80-column line. -A good rule of thumb is to stay below 63 characters, and aim for about 50 or fewer if possible. +A good rule of thumb is to stay below 67 characters, and aim for about 50 or fewer if possible. === Prefix the subject line with a component, if applicable If the change relates to a specific component the subject line may be prefixed with that component name and a colon (:). +If applicable, try to use the same prefix used in previous commits to the same files. ✓ `foo: Add -k option to keep temporary data` -Include the prefix in the 63-character limit suggested above, so that `git log --oneline` avoids wrapping. +Include the prefix in the 67-character limit suggested above, so that `git log --oneline` avoids wrapping. === Capitalize the first letter of the subject @@ -2630,6 +2653,10 @@ We include the commit title so that the referenced commit can be located even in |`Relnotes:` |If the change is a candidate for inclusion in the release notes for the next release from the branch, set to `yes`. +|Candidates are user-visible changes, new features, compatibility breaks, etc.. +|If you forget to set this line, or want to provide more details, add an entry to the `RELNOTES` file in the root of the src tree. +|The `RELNOTES` file is used to generate release notes for the next release. +|Do not use the `Relnotes:` line to describe the change: its only valid value is `yes`. |`Security:` |If the change is related to a security vulnerability or security exposure, include one or more references or a description of the issue. If possible, include a VuXML URL or a CVE ID. @@ -2953,6 +2980,9 @@ You can find out more about Bugzilla at: The FreeBSD Project utilizes https://reviews.freebsd.org[Phabricator] for code review requests. See the https://wiki.freebsd.org/Phabricator[Phabricator wiki page] for details. +Please use the `git arc` command provided by `devel/freebsd-git-devtools` (install the port or package, then type `git help arc` for documentation) to create and update Phabricator reviews. +This will make it easier for others to review and test your patches. + Committers with non-``FreeBSD.org`` Phabricator accounts can have the old account renamed to the ``FreeBSD.org`` account by following these steps: [.procedure] |