git: 97655c6e49 - main - Upgrade how to create a diff patch in FDP overview chapter

The branch main has been updated by carlavilla:

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

commit 97655c6e49e1cbf1a340718ee3dcaadef808f1c8
Author:     Sergio Carlavilla Delgado <carlavilla@FreeBSD.org>
AuthorDate: 2022-04-08 20:57:53 +0000
Commit:     Sergio Carlavilla Delgado <carlavilla@FreeBSD.org>
CommitDate: 2022-04-08 20:57:53 +0000

    Upgrade how to create a diff patch in FDP overview chapter
    
    Reported by:    Pau Amma <pauamma (AT) gundo.com>
---
 .../en/books/fdp-primer/overview/_index.adoc       | 69 ++++++++++++++++++----
 1 file changed, 57 insertions(+), 12 deletions(-)

diff --git a/documentation/content/en/books/fdp-primer/overview/_index.adoc b/documentation/content/en/books/fdp-primer/overview/_index.adoc
index 6fe1fbb106..514ae7a06d 100644
--- a/documentation/content/en/books/fdp-primer/overview/_index.adoc
+++ b/documentation/content/en/books/fdp-primer/overview/_index.adoc
@@ -136,15 +136,31 @@ Repeat until all of the errors are resolved.
 % make
 ....
 +
-. When changes are complete and tested, generate a "diff file":
+. Add all the files with `git add .`, then review the diff with `git diff`. For example:
 +
 [source,shell]
 ....
-% cd ~/doc
-% git diff > bsdinstall.diff.txt
+% git add .
+% git diff --staged
 ....
 +
-Give the diff file a descriptive name.
+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 documentation tree,
+please generate the [.filename]#.diff# from the base of your documentation tree.
+======
++
 In the example above, changes have been made to the *bsdinstall* portion of the Handbook.
 +
 . Submit the diff file using the web-based https://bugs.FreeBSD.org/bugzilla/enter_bug.cgi?product=Documentation[Problem Report] system. If using the web form, enter a Summary of _[patch] short description of problem_. Select the Component `Documentation`. In the Description field, enter a short description of the changes and any important details about them. Use the btn:[Add an attachment] button to attach the diff file. Finally, use the btn:[Submit Bug] button to submit your diff to the problem report system.
@@ -188,15 +204,30 @@ Repeat until all of the errors are resolved.
 % bmake run LOCALBASE=/usr
 ....
 +
-. When changes are complete and tested, generate a diff file:
+. Add all the files with `git add .`, then review the diff with `git diff`. For example:
++
+[source,shell]
+....
+% git add .
+% 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]
 ....
-% cd ~/doc
-% git diff > bsdinstall.diff
+% git commit
+% git format-patch origin/main
 ....
 +
-Give the diff file a descriptive name.
+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 documentation tree,
+please generate the [.filename]#.diff# from the base of your documentation tree.
+======
 +
 . Submit the diff file using the web-based https://bugs.FreeBSD.org/bugzilla/enter_bug.cgi?product=Documentation[Problem Report] system.
 If using the web form, enter a Summary of _short description of problem_.
@@ -255,16 +286,30 @@ Repeat until all of the errors are resolved.
 ....
 $ bmake run LOCALBASE=/usr
 ....
+. Add all the files with `git add .`, then review the diff with `git diff`. For example:
++
+[source,shell]
+....
+% git add .
+% git diff --staged
+....
 +
-. When changes are complete and tested, generate a diff file:
+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]
 ....
-$ cd ~/doc
-$ git diff > bsdinstall.diff
+% git commit
+% git format-patch origin/main
 ....
 +
-Give the diff file a descriptive name.
+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 documentation tree,
+please generate the [.filename]#.diff# from the base of your documentation tree.
+======
 +
 . Submit the diff file using the web-based https://bugs.FreeBSD.org/bugzilla/enter_bug.cgi?product=Documentation[Problem Report] system.
 If using the web form, enter a Summary of _short description of problem_.