Skip to content
GitLab
Commit 28b1fbd5 authored by Timo Ketola's avatar Timo Ketola Committed by Spencer Oliver
Browse files

doc: Update patch procedure 



Change-Id: I3e50357b4ddaf483712bbac68b6427b31529f666
Signed-off-by: default avatarTimo Ketola <timo@exertus.fi>
Reviewed-on: http://openocd.zylin.com/387


Tested-by: jenkins
Reviewed-by: default avatarØyvind Harboe <oyvindharboe@gmail.com>
Reviewed-by: default avatarSpencer Oliver <spen@spen-soft.co.uk>
parent 3528457b
Hide whitespace changes
Inline Side-by-side
BUGS
View file @ 28b1fbd5
......@@ -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
......
Doxyfile.in
View file @ 28b1fbd5
......@@ -567,7 +567,7 @@ WARN_LOGFILE =
INPUT = @srcdir@/doc/manual \
@srcdir@/TODO \
@srcdir@/BUGS \
@srcdir@/PATCHES.txt \
@srcdir@/HACKING \
@srcdir@/src \
@builddir@/config.h
......
HACKING
View file @ 28b1fbd5
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.
*/
Makefile.am
View file @ 28b1fbd5
......@@ -24,7 +24,6 @@ EXTRA_DIST = \
BUGS \
HACKING \
NEWTAPS \
PATCHES.txt \
README.Win32 \
Doxyfile.in \
tools/logger.pl \
......
PATCHES.txt deleted 100644 → 0
View file @ 3528457b
// 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.
*/
doc/manual/primer/patches.txt deleted 100644 → 0
View file @ 3528457b
/** @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.
*/
doc/openocd.texi
View file @ 28b1fbd5
......@@ -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
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment