doc: Update patch procedure
authorTimo Ketola <timo@exertus.fi>
Tue, 17 Jan 2012 14:10:10 +0000 (16:10 +0200)
committerSpencer Oliver <spen@spen-soft.co.uk>
Wed, 18 Jan 2012 21:46:15 +0000 (21:46 +0000)
Change-Id: I3e50357b4ddaf483712bbac68b6427b31529f666
Signed-off-by: Timo Ketola <timo@exertus.fi>
Reviewed-on: http://openocd.zylin.com/387
Tested-by: jenkins
Reviewed-by: √ėyvind Harboe <oyvindharboe@gmail.com>
Reviewed-by: Spencer Oliver <spen@spen-soft.co.uk>
BUGS
Doxyfile.in
HACKING
Makefile.am
PATCHES.txt [deleted file]
doc/manual/primer/patches.txt [deleted file]
doc/openocd.texi

diff --git a/BUGS b/BUGS
index 2ed8bf6..4381c87 100644 (file)
--- a/BUGS
+++ b/BUGS
@@ -32,7 +32,7 @@ that may be important.
     http://www.kernel.org/pub/software/scm/git/docs/git-bisect.html
 
 If possible, please develop and attach a patch that helps to expose or
     http://www.kernel.org/pub/software/scm/git/docs/git-bisect.html
 
 If possible, please develop and attach a patch that helps to expose or
-solve the reported problem.  See the PATCHES.txt file for information
+solve the reported problem.  See the HACKING file for information
 about that process.
 
 Attach all files directly to your posting.  The mailing list knows to
 about that process.
 
 Attach all files directly to your posting.  The mailing list knows to
index 658f667..34a3706 100644 (file)
@@ -567,7 +567,7 @@ WARN_LOGFILE           =
 INPUT                  = @srcdir@/doc/manual \
                          @srcdir@/TODO \
                          @srcdir@/BUGS \
 INPUT                  = @srcdir@/doc/manual \
                          @srcdir@/TODO \
                          @srcdir@/BUGS \
-                         @srcdir@/PATCHES.txt \
+                         @srcdir@/HACKING \
                          @srcdir@/src \
                          @builddir@/config.h
 
                          @srcdir@/src \
                          @builddir@/config.h
 
diff --git a/HACKING b/HACKING
index ed97171..d6a6b5b 100644 (file)
--- a/HACKING
+++ b/HACKING
@@ -1,7 +1,14 @@
-NB! If you're behind a corporate wall with http only access to the
+// This file is part of the Doxygen Developer Manual
+/** @page patchguide Patch Guidelines
+
+@b NB! If you're behind a corporate wall with http only access to the
 world, you can still use these instructions!
 
 world, you can still use these instructions!
 
-Submitting patches to the OpenOCD Gerrit server:
+@b NB2! You can't send patches to the mailing list anymore at all. Nowadays
+you are expected to send patches to the OpenOCD Gerrit GIT server for a
+review.
+
+@section gerrit Submitting patches to the OpenOCD Gerrit server
 
 OpenOCD is to some extent a "self service" open source project, so to
 contribute, you must follow the standard procedures to have the best
 
 OpenOCD is to some extent a "self service" open source project, so to
 contribute, you must follow the standard procedures to have the best
@@ -14,118 +21,117 @@ The procedure to create a patch is essentially:
 - send the changes to the Gerrit server for review
 - correct the patch and re-send it according to review feedback
 
 - send the changes to the Gerrit server for review
 - correct the patch and re-send it according to review feedback
 
-
-0. Create a Gerrit account at:
-
-http://openocd.zylin.com
-
-- On subsequent sign ins, use the full URL prefaced with 'http://'
-  For example:
-
-       http://user_identifier.open_id_provider.com
-
-0.1. Add a username to your profile.
-
-After creating the Gerrit account and signing in, you will need to
-add a username to your profile. To do this, go to 'Settings', and
-add a username of your choice.
-
-Your username will be required in step 2 and substituted wherever
-the string 'USERNAME' is found.
-
-0.2. Add an SSH public key
-
-Following the directions for your specific platform:
-
-       for Windows: help.github.com/win-set-up-git/#_set_up_ssh_keys
-       for OSX:     help.github.com/mac-set-up-git/#_set_up_ssh_keys
-       for Linux:   help.github.com/linux-set-up-git/#_set_up_ssh_keys
-
-While these pages describe the setting up of git as well,
-you should scroll down the page till you get to the section:
-'Next: Set Up SSH Keys', and follow the steps described.
-
-1. Clone the git repository, rather than just
-download the source.
-
-git clone git://openocd.git.sourceforge.net/gitroot/openocd/openocd
-
-or if you have problems with the "git:" protocol, use
-the slower http protocol:
-
-git clone http://repo.or.cz/r/openocd.git
-
-2. Set up Gerrit with your local repository. All this does it
+Your patch (or commit) should be a "good patch": focus it on a single
+issue, and make it be easily reviewable. Don't make
+it so large that it's hard to review; split large
+patches into smaller ones. (That can also help
+track down bugs later on.) All patches should
+be "clean", which includes preserving the existing
+coding style and updating documentation as needed.
+
+Say in the commit message if it's a bugfix (describe the bug) or a new
+feature. Don't expect patches to merge immediately
+for the next release. Be ready to rework patches
+in response to feedback.
+
+Add yourself to the GPL copyright for non-trivial changes.
+
+@section stepbystep Step by step procedure
+
+-# Create a Gerrit account at: http://openocd.zylin.com
+  - On subsequent sign ins, use the full URL prefaced with 'http://'
+    For example: http://user_identifier.open_id_provider.com
+  -# Add a username to your profile.
+     After creating the Gerrit account and signing in, you will need to
+     add a username to your profile. To do this, go to 'Settings', and
+     add a username of your choice.
+     Your username will be required in step 3 and substituted wherever
+     the string 'USERNAME' is found.
+  -# Add an SSH public key following the directions for your specific platform:
+     - for Windows: http://help.github.com/win-set-up-git/#_set_up_ssh_keys
+     - for OSX: http://help.github.com/mac-set-up-git/#_set_up_ssh_keys
+     - for Linux: http://help.github.com/linux-set-up-git/#_set_up_ssh_keys<br>
+     .
+     While these pages describe the setting up of git as well,
+     you should scroll down the page till you get to the section:
+     <i>Next: Set Up SSH Keys</i>, and follow the steps described.
+-# Clone the git repository, rather than just download the source:
+ @code
+ git clone git://openocd.git.sourceforge.net/gitroot/openocd/openocd
+ @endcode
+   or if you have problems with the "git:" protocol, use
+   the slower http protocol:
+ @code
+ git clone http://repo.or.cz/r/openocd.git
+ @endcode
+-# Set up Gerrit with your local repository. All this does it
 to instruct git locally how to send off the changes.
 to instruct git locally how to send off the changes.
-
-Add a new remote to git using Gerrit username:
-
+  -# Add a new remote to git using Gerrit username:
+@code
 git remote add review ssh://USERNAME@openocd.zylin.com:29418/openocd.git
 git config remote.review.push HEAD:refs/for/master
 git remote add review ssh://USERNAME@openocd.zylin.com:29418/openocd.git
 git config remote.review.push HEAD:refs/for/master
-
-Or with http only:
-
+@endcode
+  Or with http only:
+@code
 git remote add review http://openocd.zylin.com/p/openocd.git
 git config remote.review.push HEAD:refs/for/master
 git remote add review http://openocd.zylin.com/p/openocd.git
 git config remote.review.push HEAD:refs/for/master
-
-You will need to install this hook, we will look into a better
-solution:
-
+@endcode
+  -# You will need to install this hook, we will look into a better solution:
+@code
 scp -p -P 29418 USERNAME@openocd.zylin.com:hooks/commit-msg .git/hooks/
 scp -p -P 29418 USERNAME@openocd.zylin.com:hooks/commit-msg .git/hooks/
-
-Or with http only:
-
+@endcode
+  Or with http only:
+@code
 wget http://openocd.zylin.com/tools/hooks/commit-msg
 mv commit-msg .git/hooks
 chmod +x .git/hooks/commit-msg
 wget http://openocd.zylin.com/tools/hooks/commit-msg
 mv commit-msg .git/hooks
 chmod +x .git/hooks/commit-msg
-
-3. Set up git with your name and email:
-
+@endcode
+-# Set up git with your name and email:
+@code
 git config --global user.name "John Smith"
 git config --global user.email "john@smith.org"
 git config --global user.name "John Smith"
 git config --global user.email "john@smith.org"
-
-4. Work on your patches. Split the work into
-multiple small patches that can be reviewed and
-applied seperately and safely to the OpenOCD
-repository.
-
+@endcode
+-# Work on your patches. Split the work into
+   multiple small patches that can be reviewed and
+   applied seperately and safely to the OpenOCD
+   repository.
+@code
 while(!done) {
   work - edit files using your favorite editor.
   run "git commit -s -a" to commit all changes.
   run tools/checkpatch.sh to verify your patch style is ok.
 }
 while(!done) {
   work - edit files using your favorite editor.
   run "git commit -s -a" to commit all changes.
   run tools/checkpatch.sh to verify your patch style is ok.
 }
-
-TIP! use "git add ." before commit to add new files.
-
+@endcode
+   @b TIP! use "git add ." before commit to add new files.
+@code
 --- example comment, notice the short first line w/topic ---
 topic: short comment
 <blank line>
 longer comments over several
 lines...
 --- example comment, notice the short first line w/topic ---
 topic: short comment
 <blank line>
 longer comments over several
 lines...
+<blank line>
+Signed-off-by: ...
 -----
 -----
-
-5. Next you need to make sure that your patches
-are on top of the latest stuff on the server and
-that there are no conflicts.
-
+@endcode
+-# Next you need to make sure that your patches
+   are on top of the latest stuff on the server and
+   that there are no conflicts:
+@code
 git pull --rebase origin/master
 git pull --rebase origin/master
-
-6. Send the patches to the Gerrit server for review.
-
+@endcode
+-# Send the patches to the Gerrit server for review:
+@code
 git push review
 git push review
-
-7. Forgot something, want to add more? Just make the changes and do:
-
+@endcode
+-# Forgot something, want to add more? Just make the changes and do:
+@code
 git commit --amend
 git push review
 git commit --amend
 git push review
+@endcode
 
 
-Further reading:
-
-http://www.coreboot.org/Git
-
+Further reading: http://www.coreboot.org/Git
 
 
-When can I expect my contribution to be committed?
-==================================================
+@section timeline When can I expect my contribution to be committed?
 
 The code review is intended to take as long as a week or two to allow
 maintainers and contributors who work on OpenOCD only in their spare
 
 The code review is intended to take as long as a week or two to allow
 maintainers and contributors who work on OpenOCD only in their spare
@@ -143,3 +149,7 @@ master branch will be much reduced.
 
 If a contributor pushes a patch, it is considered good form if another
 contributor actually approves and submits that patch.
 
 If a contributor pushes a patch, it is considered good form if another
 contributor actually approves and submits that patch.
+*/
+/** @file
+This file contains the @ref patchguide page.
+*/
index 0d20233..8de1dbd 100644 (file)
@@ -24,7 +24,6 @@ EXTRA_DIST = \
        BUGS \
        HACKING \
        NEWTAPS \
        BUGS \
        HACKING \
        NEWTAPS \
-       PATCHES.txt \
        README.Win32 \
        Doxyfile.in \
        tools/logger.pl \
        README.Win32 \
        Doxyfile.in \
        tools/logger.pl \
diff --git a/PATCHES.txt b/PATCHES.txt
deleted file mode 100644 (file)
index 2757eac..0000000
+++ /dev/null
@@ -1,47 +0,0 @@
-// This file is part of the Doxygen Developer Manual
-/** @page patchguide Patch Guidelines
-
-Please mail patches to: @par
-       openocd-devel@lists.sourceforge.net
-
-Note that you can't send patches to that list unless
-you're a member, despite what the list info page says.
-
-@section Patch Guidelines in a Nutshell
-
-Your patches should be against git mainline.  Submit output
-of "git diff"; equivalently, quilt patches are OK.
-
-It should be a "good patch": focus it on a single
-issue, and make it be easily reviewable. Don't make
-it so large that it's hard to review; split large
-patches into smaller ones. (That can also help
-track down bugs later on.) All patches should
-be "clean", which includes preserving the existing
-coding style and updating documentation as needed.j
-
-Attach the patch to the email as a .txt file and
-also write a short change log entry that maintainers
-can copy and paste into the commit message
-
-Say if it's a bugfix (describe the bug) or a new
-feature. Don't expect patches to merge immediately
-for the next release. Be ready to rework patches
-in response to feedback.
-
-Add yourself to the GPL copyright for non-trivial changes.
-
-To create a patch from the command line:
-@code
-       git diff >mypatch.txt
-@endcode
-
-@section More Information on Patching
-
-The @ref primerpatches provides a more complete guide to creating,
-managing, and contributing patches to the OpenOCD project.
-
- */
-/** @file
-This file contains the @ref patchguide page.
-*/
diff --git a/doc/manual/primer/patches.txt b/doc/manual/primer/patches.txt
deleted file mode 100644 (file)
index cb3c07c..0000000
+++ /dev/null
@@ -1,172 +0,0 @@
-/** @page primerpatches Patch Primer
-
-This page provides an introduction to patching that may be useful
-for OpenOCD contributors who are unfamiliar with the process.
-
-@section primerpatchintro Introduction to Patching
-
-The standard method for creating patches requires developers to:
-- checkout the git repository (or bring a copy up-to-date),
-- make the necessary modifications to a working copy,
-- check with 'git status' to see which files will be modified/added, and
-- use 'git diff' to review the changes and produce a patch.
-
-It is important to minimize the changes to only those lines that contain
-important differences; do not allow stray whitespace changes into your
-patches, and keep the focus to a single logical change.
-
-@section primerpatchcreate Creating Patches
-
-You can create a patch (from the root of your working copy) with a
-command like the following example: @par
-@verbatim
-git diff > patch-name.patch
-@endverbatim
-
-where @a patch-name should be something that is descriptive and unique.
-
-The above command will create a patch containing all of the changes in
-the working copy; if you want to obtain a subset, simply provide the
-list of files to the command: @par
-@verbatim
-git diff doc > <patch-name>-doc.patch
-git diff src > <patch-name>-src.patch
-@endverbatim
-
-This will create two patches, each containing only those changes present
-in the subdirectory specified.
-
-@subsection primerpatchcreate Naming Patches
-
-One developer has evolved an informal standard for naming his patches: @par
-@verbatim
-<project>-<lod>-<action>-<task>.patch
-@endverbatim
-
-where @a project is @c openocd, @a lod (line-of-development) could be a
-subsystem (e.g. @c jtag, @c jlink, etc.) or other group identifier,
-@a action is @c add, @c change, @c fix, @c update, etc., and @a task is
-whatever the patch will accomplish (in 2-4 words).
-
-This scheme does not need to be followed, but it is helpful for
-maintainers that receive many patches.  You do not want your own
-@c openocd.patch file to be accidentally overwritten by another
-submission, sending your patch to the bit bucket on accident.
-
-@section primerpatchpreflight Developer Review
-
-Before sending in patches, please make sure you have updated to the
-latest version of the trunk (using <code>git pull</code>) before creating
-your patch.  This helps to increase the chances that it will apply
-cleanly to the trunk.  However, the content matters most.
-
-When creating a patch using "<code>git diff</code>", git will
-produce a patch that contains all of the changes in your working copy.
-To manage multiple changes at once, you either need one working copy per
-patch, or you can specified specific files and directories when using
-<code>git diff</code>.  Overlapping patches will be discussed in the
-next section.
-
-@todo Does git's treatment of line-endings behave sanely?
-Basically, the repository should use newlines internally,
-and convert to/from CRLF on Windows etc.
-
-@section primerpatchseries Patch Series
-
-As was mentioned above, each patch should contain one logical @c task,
-and multiple logical tasks should be split into a series of patches.
-There are no hard guidelines for how that is to be done; it's an art
-form.  Many simple changes should not have to worry about being split,
-as they will naturally represent a single task.
-
-When working on several different non-intersecting lines of development,
-a combination of multiple working copies and patch series management
-techniques can become critical to efficiently managing change.  This
-again is an area where developers have favorite methodologies that are
-simply a matter of taste or familiarity; your mileage may vary.
-
-Packages such as @c patchutils, @c diffutils, and @c quilt are among
-those that have proved themselves invaluable for these type of tasks.
-Others take their patch management a step further, using stkgit or
-some other framework on top of git.
-
-@subsection primerpatchseriesinterdiff Using @c interdiff
-
-The @c patchutils package includes the @c interdiff command, which
-produces a patch that contains the changes made between two other
-patches.  This command can be used to manage the creation of trivial
-patch series.  For example, the following sequence of commands will
-produce three patches: @par
-@verbatim
-$ cd openocd/
-$ git pull
-...
-$ <<<start changes for patch #1>>>
-...
-$ <<<finish changes for patch #1>>>
-$ git diff > series-1.patch                         # patch #1 is easy
-$ <<<start changes for patch #2>>>
-...
-$ <<<finish changes for patch #2>>>
-$ git diff > series-1+2.patch                       # create patch 1+2
-$ interdiff series-1{,+2}.patch > series-2.patch    #   1 ~  1+2  => #2
-$ <<<start changes for patch #3>>>
-...
-$ <<<finish changes for patch #3>>>
-$ git diff > series-1+2+3.patch                     # create patch 1+2+3
-$ interdiff series-1+2{,+3}.patch > series-3.patch  # 1+2 ~ 1+2+3 => 3
-@endverbatim
-
-This technique falls apart when the repository changes, but this may be
-suitable for small series of patches.
-
-@subsection primerpatchseriesquilt Using @c quilt
-
-The @c quilt package provides scripts to manage series of patches more
-efficiently than can be managed by hand.  For out-of-tree work projects
-that require such patch management, @c quilt provides an indispensable
-tool for solving the problem.
-
-@section primerpatchsubmit Submitting Patches
-
-Write access to the OpenOCD git repository is limited to
-contributors that have demonstrated the ability to produce clear,
-consistent, and frequent patches.  These individuals are responsible
-for maintaining the integrity of the repository for the community.
-
-Thus, commits to the git repository must be handled by one of
-these maintainers.
-
-Patches must be sent to the OpenOCD developer mailing list:
-@par
-       openocd-devel@lists.sourceforge.net
-
-They will be reviewed and committed if the changes are found to be
-acceptable.  If there are problems, you will receive feedback via the
-mailing list; in general, the maintainers prefer all communication to go
-through the list, as the entire community needs to judge contributions
-for possible merits and mistakes.
-
-Contributors may be asked to address certain issues and submit a new
-patch.  In the event that it gets overlooked, you may need to resubmit
-it or prompt for feedback.  Please have patience, as many maintainers
-work on the project voluntarily and without compensation for the time
-that they spend doing these tasks.
-
-@section primerpatchguide Guidelines for Submitting Patches
-
-- Each patch file should contain:
-  - A commit description that describes all of the changes.
-  - A separator line that contains three hyphens: <code>---</code>
-  - A summary of the changes produced by diffstat (optional)
-  - Another separator line (optional)
-  - The actual patch contents, containing a single change.
-
-- Each patch series should include:
-  - A summary of the patches in the series.
-  - Logically-related patches that contain incremental changes.
-
- */
-/** @file
-This file contains the @ref primerpatches page.
-*/
index 0fb24cb..824e744 100644 (file)
@@ -255,7 +255,7 @@ communication between developers:
 @uref{https://lists.sourceforge.net/mailman/listinfo/openocd-devel}
 
 Discuss and submit patches to this list.
 @uref{https://lists.sourceforge.net/mailman/listinfo/openocd-devel}
 
 Discuss and submit patches to this list.
-The @file{PATCHES.txt} file contains basic information about how
+The @file{HACKING} file contains basic information about how
 to prepare patches.
 
 @section OpenOCD Bug Database
 to prepare patches.
 
 @section OpenOCD Bug Database