doc: Update patch procedure
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>
This commit is contained in:
Timo Ketola
Spencer Oliver
parent
3528457ba8
commit
28b1fbd5ee
2
BUGS
2
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
|
||||
|
|
|
|||
|
|
@ -567,7 +567,7 @@ WARN_LOGFILE =
|
|||
INPUT = @srcdir@/doc/manual \
|
||||
@srcdir@/TODO \
|
||||
@srcdir@/BUGS \
|
||||
@srcdir@/PATCHES.txt \
|
||||
@srcdir@/HACKING \
|
||||
@srcdir@/src \
|
||||
@builddir@/config.h
|
||||
|
||||
|
|
|
|||
174
HACKING
174
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
|
||||
|
||||
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.
|
||||
|
||||
0. Create a Gerrit account at:
|
||||
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.
|
||||
|
||||
http://openocd.zylin.com
|
||||
Add yourself to the GPL copyright for non-trivial changes.
|
||||
|
||||
- On subsequent sign ins, use the full URL prefaced with 'http://'
|
||||
For example:
|
||||
@section stepbystep Step by step procedure
|
||||
|
||||
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
|
||||
-# 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:
|
||||
Further reading: http://www.coreboot.org/Git
|
||||
|
||||
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.
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -24,7 +24,6 @@ EXTRA_DIST = \
|
|||
BUGS \
|
||||
HACKING \
|
||||
NEWTAPS \
|
||||
PATCHES.txt \
|
||||
README.Win32 \
|
||||
Doxyfile.in \
|
||||
tools/logger.pl \
|
||||
|
|
|
|||
47
PATCHES.txt
47
PATCHES.txt
|
|
@ -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.
|
||||
*/
|
||||
|
|
@ -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.
|
||||
*/
|
||||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in New Issue