git: b67169a01d - main - Make `git format-patch` preferred way of generating patches.

The branch main has been updated by delphij:

URL: https://cgit.FreeBSD.org/doc/commit/?id=b67169a01da91ceea6304f1dd67971fff283af61

commit b67169a01da91ceea6304f1dd67971fff283af61
Author:     Xin LI <delphij@FreeBSD.org>
AuthorDate: 2021-12-28 01:56:29 +0000
Commit:     Xin LI <delphij@FreeBSD.org>
CommitDate: 2021-12-28 03:00:21 +0000

    Make `git format-patch` preferred way of generating patches.
    
    git format-patch would generate patchsets that can be applied with
    `git am` and preserve author identity like name and email.
    
    Reviewed by:    imp, emaste
    Differential Revision: https://reviews.freebsd.org/D33678
---
 .../content/en/articles/problem-reports/_index.adoc   |  8 +++++++-
 .../books/porters-handbook/quick-porting/_index.adoc  | 16 ++++++++++++++--
 .../en/books/porters-handbook/upgrading/_index.adoc   | 19 +++++++++++--------
 3 files changed, 32 insertions(+), 11 deletions(-)

diff --git a/documentation/content/en/articles/problem-reports/_index.adoc b/documentation/content/en/articles/problem-reports/_index.adoc
index 2353ac2740..71c814a258 100644
--- a/documentation/content/en/articles/problem-reports/_index.adoc
+++ b/documentation/content/en/articles/problem-reports/_index.adoc
@@ -171,7 +171,13 @@ Finally, if the submission is lengthy, prepare the work offline so that nothing
 [[pr-writing-attaching-patches]]
 == Attaching Patches or Files
 
-When attaching a patch, be sure to use either `git diff` or man:diff[1] with the `-u` option to create a unified diff and make sure to specify the Git hash and branch of the repository against which you modified files, so the developers who read your report will be able to apply them easily.
+In principal, we recommend using `git format-patch` to generate one or a series of unified diff against the base
+branch (e.g. `origin/main`).
+Patches generated this way would include the Git hashes and will include your name and email address, making it
+easier for committers to apply your patch and properly credit you as the author (using `git am`).
+For minor changes where you prefer not to use git, please be sure to use man:diff[1] with the `-u` option to
+create a unified diff, as this would give developers more context and are more readable than other diff formats.
+
 For problems with the kernel or the base utilities, a patch against FreeBSD-CURRENT (the main Git branch) is preferred since all new code should be applied and tested there first.
 After appropriate or substantial testing has been done, the code will be merged/migrated to the FreeBSD-STABLE branch.
 
diff --git a/documentation/content/en/books/porters-handbook/quick-porting/_index.adoc b/documentation/content/en/books/porters-handbook/quick-porting/_index.adoc
index 0f0f639c00..18cd48110c 100644
--- a/documentation/content/en/books/porters-handbook/quick-porting/_index.adoc
+++ b/documentation/content/en/books/porters-handbook/quick-porting/_index.adoc
@@ -276,14 +276,26 @@ Assuming the port is called `oneko` and is in the `games` category.
 .Creating a [.filename]#.diff# for a New Port
 [example]
 ====
-Add all the files with `git add .`, then generate the diff with `git diff`. For example:
+Add all the files with `git add .`, then review the diff with `git diff`. For example:
 
 [source,shell]
 ....
 % git add .
-% git diff --staged > oneko.diff
+% git diff --staged
 ....
 
+Make sure that all required files are included, then commit the change to your local branch and generate a
+patch with `git format-patch`
+
+[source,shell]
+....
+% git commit
+% git format-patch origin/main
+....
+
+Patch generated with `git format-patch` will include author identity and email addresses, making it
+easier for developers to apply (with `git am`) and give proper credit.
+
 [IMPORTANT]
 ****
 To make it easier for committers to apply the patch on their working copy of the ports tree, please generate the [.filename]#.diff# from the base of your ports tree.
diff --git a/documentation/content/en/books/porters-handbook/upgrading/_index.adoc b/documentation/content/en/books/porters-handbook/upgrading/_index.adoc
index e420cb5b6b..3cd5e01f68 100644
--- a/documentation/content/en/books/porters-handbook/upgrading/_index.adoc
+++ b/documentation/content/en/books/porters-handbook/upgrading/_index.adoc
@@ -179,14 +179,6 @@ Check the changes staged for the patch:
 
 The last step is to make an unified diff or patch of the changes:
 
-To generate an unified diff with man:git-diff[1]:
-[source,shell]
-....
-% git diff --staged > ../`make -VPKGNAME`.diff
-....
-This will generate a diff named like `foo-1.2.3.diff`.
-Where `foo` is replaced with the first line of the commit message, i.e., the subject of the commit message.
-
 To generate a patch with man:git-format-patch[1]:
 [source,shell]
 ....
@@ -196,6 +188,17 @@ To generate a patch with man:git-format-patch[1]:
 ....
 
 This will generate a patch named like `0001-foo.patch`.
+This is the preferred way as it would include author identity,
+and it is also easier when you are making a series of changes that
+are not meant to be squashed together.
+
+Alternatively, to generate an unified diff with man:git-diff[1]:
+[source,shell]
+....
+% git diff --staged > ../`make -VPKGNAME`.diff
+....
+This will generate a diff named like `foo-1.2.3.diff`.
+Where `foo` is replaced with the first line of the commit message, i.e., the subject of the commit message.
 
 After patch has been created, you can switch to the main branch for starting other developments.
 [source,shell]