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
-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
index 658f667..34a3706 100644 (file)
@@ -567,7 +567,7 @@ WARN_LOGFILE           =
 INPUT                  = @srcdir@/doc/manual \
                          @srcdir@/TODO \
                          @srcdir@/BUGS \
-                         @srcdir@/PATCHES.txt \
+                         @srcdir@/HACKING \
                          @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!
 
-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
@@ -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
 
-
-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.
-
-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
-
-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
-
-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/
-
-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
-
-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"
-
-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.
 }
-
-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...
+<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
-
-6. Send the patches to the Gerrit server for review.
-
+@endcode
+-# Send the patches to the Gerrit server for review:
+@code
 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
+@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
@@ -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.
+*/
+/** @file
+This file contains the @ref patchguide page.
+*/
index 0d20233..8de1dbd 100644 (file)
@@ -24,7 +24,6 @@ EXTRA_DIST = \
        BUGS \
        HACKING \
        NEWTAPS \
-       PATCHES.txt \
        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.
-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