doc: Update patch procedure
authorTimo Ketola <>
Tue, 17 Jan 2012 14:10:10 +0000 (16:10 +0200)
committerSpencer Oliver <>
Wed, 18 Jan 2012 21:46:15 +0000 (21:46 +0000)
Change-Id: I3e50357b4ddaf483712bbac68b6427b31529f666
Signed-off-by: Timo Ketola <>
Tested-by: jenkins
Reviewed-by: √ėyvind Harboe <>
Reviewed-by: Spencer Oliver <>
PATCHES.txt [deleted file]
doc/manual/primer/patches.txt [deleted file]

diff --git a/BUGS b/BUGS
index 2ed8bf627062f4151b1a46ed2f07e3f039cf01e1..4381c87b5d093071bc030f369ce6c99afa877034 100644 (file)
--- a/BUGS
+++ b/BUGS
@@ -32,7 +32,7 @@ that may be important.
 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 658f66710cc7c1b56f45322a392ffc6458f85002..34a37063406f89dfe44ee88b9f5b74c29dc67d9b 100644 (file)
@@ -567,7 +567,7 @@ WARN_LOGFILE           =
 INPUT                  = @srcdir@/doc/manual \
                          @srcdir@/TODO \
                          @srcdir@/BUGS \
-                         @srcdir@/PATCHES.txt \
+                         @srcdir@/HACKING \
                          @srcdir@/src \
diff --git a/HACKING b/HACKING
index ed971715406b79db363d395920915294ed7dfcc8..d6a6b5b835033fb42d94940a492462f735846664 100644 (file)
@@ -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
+@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:
-- On subsequent sign ins, use the full URL prefaced with 'http://'
-  For example:
-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:
-       for OSX:
-       for Linux:
-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://
-or if you have problems with the "git:" protocol, use
-the slower http protocol:
-git clone
-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:
+  - On subsequent sign ins, use the full URL prefaced with 'http://'
+    For example:
+  -# 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:
+     - for OSX:
+     - for Linux:<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://
+ @endcode
+   or if you have problems with the "git:" protocol, use
+   the slower http protocol:
+ @code
+ git clone
+ @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:
 git remote add review ssh://
 git config HEAD:refs/for/master
-Or with http only:
+  Or with http only:
 git remote add review
 git config HEAD:refs/for/master
-You will need to install this hook, we will look into a better
+  -# You will need to install this hook, we will look into a better solution:
 scp -p -P 29418 .git/hooks/
-Or with http only:
+  Or with http only:
 mv commit-msg .git/hooks
 chmod +x .git/hooks/commit-msg
-3. Set up git with your name and email:
+-# Set up git with your name and email:
 git config --global "John Smith"
 git config --global ""
-4. Work on your patches. Split the work into
-multiple small patches that can be reviewed and
-applied seperately and safely to the OpenOCD
+-# Work on your patches. Split the work into
+   multiple small patches that can be reviewed and
+   applied seperately and safely to the OpenOCD
+   repository.
 while(!done) {
   work - edit files using your favorite editor.
   run "git commit -s -a" to commit all changes.
   run tools/ to verify your patch style is ok.
-TIP! use "git add ." before commit to add new files.
+   @b TIP! use "git add ." before commit to add new files.
 --- example comment, notice the short first line w/topic ---
 topic: short comment
 <blank line>
 longer comments over several
+<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.
+-# 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:
 git pull --rebase origin/master
-6. Send the patches to the Gerrit server for review.
+-# Send the patches to the Gerrit server for review:
 git push review
-7. Forgot something, want to add more? Just make the changes and do:
+-# Forgot something, want to add more? Just make the changes and do:
 git commit --amend
 git push review
-Further reading:
+Further reading:
-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 0d20233b4054f9a464b5aba18ca29f7ea5cc6416..8de1dbdb8de5d3718b1c748352d876c23b926ff7 100644 (file)
@@ -24,7 +24,6 @@ EXTRA_DIST = \
        BUGS \
        HACKING \
        NEWTAPS \
-       PATCHES.txt \
        README.Win32 \ \
        tools/ \
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
-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:
-       git diff >mypatch.txt
-@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
-git diff > patch-name.patch
-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
-git diff doc > <patch-name>-doc.patch
-git diff src > <patch-name>-src.patch
-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
-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
-$ 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
-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:
-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 0fb24cb42c68c9f288d49497d6b1b7a44d7bceaa..824e744cda550fcc135ec8008e55b185e51a3ad8 100644 (file)
@@ -255,7 +255,7 @@ communication between developers:
 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

Linking to existing account procedure

If you already have an account and want to add another login method you MUST first sign in with your existing account and then change URL to read to get to this page again but this time it'll work for linking. Thank you.

SSH host keys fingerprints

1024 SHA256:YKx8b7u5ZWdcbp7/4AeXNaqElP49m6QrwfXaqQGJAOk (DSA)
384 SHA256:jHIbSQa4REvwCFG4cq5LBlBLxmxSqelQPem/EXIrxjk (ECDSA)
521 SHA256:UAOPYkU9Fjtcao0Ul/Rrlnj/OsQvt+pgdYSZ4jOYdgs (ECDSA)
256 SHA256:A13M5QlnozFOvTllybRZH6vm7iSt0XLxbA48yfc2yfY (ECDSA)
256 SHA256:spYMBqEYoAOtK7yZBrcwE8ZpYt6b68Cfh9yEVetvbXg (ED25519)
+--[ED25519 256]--+
|=..              |
|+o..   .         |
|*.o   . .        |
|+B . . .         |
|Bo. = o S        |
|Oo.+ + =         |
|oB=.* = . o      |
| =+=.+   + E     |
|. .=o   . o      |
2048 SHA256:0Onrb7/PHjpo6iVZ7xQX2riKN83FJ3KGU0TvI0TaFG4 (RSA)