From: zwelch Date: Wed, 3 Jun 2009 02:12:44 +0000 (+0000) Subject: Add draft of Patching Primer in The Manual; update primer page. X-Git-Tag: v0.2.0~489 X-Git-Url: https://git.sur5r.net/?a=commitdiff_plain;h=003318b911af8efa7a664cb50a2327f1c44e56b2;p=openocd Add draft of Patching Primer in The Manual; update primer page. git-svn-id: svn://svn.berlios.de/openocd/trunk@2021 b42882b7-edfa-0310-969c-e2dbd0fdcd60 --- diff --git a/doc/manual/main.txt b/doc/manual/main.txt index e25cae67..4c7a9d9d 100644 --- a/doc/manual/main.txt +++ b/doc/manual/main.txt @@ -35,11 +35,23 @@ This pages lists Technical Primers available for OpenOCD Developers. They seek to provide information to pull novices up the learning curves associated with the fundamental technologies used by OpenOCD. +- @subpage primerpatches - @subpage primerdocs - @subpage primerautotools - @subpage primertcl - @subpage primerjtag +These documents should bridge any "ancillary" gaps in contributor +knowledge, without having to learn the complete languages or technology. +They should provide enough information for experienced developers to +learn how to make "correct" changes when creating patches. + +In all cases, these Primers should use idiomatic conventions that the +community has agreed are the "right way of doing things". In this +respect, these documents typically assume some familiarity with the +information contained in one or more @ref styleguide, or they will +directly refer to specific style guides as supplemental reading. + Contributions or suggestions for new Technical Primers are welcome. */ diff --git a/doc/manual/primer/patches.txt b/doc/manual/primer/patches.txt new file mode 100644 index 00000000..e104e4ff --- /dev/null +++ b/doc/manual/primer/patches.txt @@ -0,0 +1,210 @@ +/** @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 Subversion repository (or bring a copy up-to-date), +- make the necessary modifications to a working copy, +- check with 'svn status' to see which files will be modified/added, and +- use 'svn 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 +svn 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 +svn diff doc > -doc.patch +svn diff src > -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 +---.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 svn up) 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 "svn diff", Subversion 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 +svn diff. Overlapping patches will be discussed in the +next section. + +The remainder of this section provides + +@subsection primerpatchprops Subversion Properties + +The Subversion attributes of files can be examined with commands like the +following: @par +@verbatim +$ svn pl README +Properties on 'README': + svn:eol-style +$ svn pl tools/rlink_make_speed_table/rlink_make_speed_table.pl +Properties on 'tools/rlink_make_speed_table/rlink_make_speed_table.pl': + svn:executable + svn:eol-style +$ +@endverbatim + +@subsection primerpatchpropcrlf Native Line-endings + +Subversion checks out files marked with the attribute @c svn:eol-style +set to @c native such that these files contain the default line ending +style of the current host ('\\n' or '\\r\\n'). By using the proper line +endings for different platforms, two different byte streams for the same +file will be produced. + +@subsection primerpatchwincrlf Windows Patching Problems + +Because of the line-ending functionality, it may be correct when a fresh +patch does not apply cleanly on the Windows platform. This is because +patches are created by SVN with UNIX line endings, so the context and +changes will not appear to match the files with Windows line endings. + +In other words, the following command may @b not succeed because @c foo +has its @c svn:eol-style property set to @c native: @par +@code +svn diff foo | patch -R +@endcode + +The following series of commands will work: @par +@code +svn diff foo | unix2dos | patch -R +@endcode + +This is not a bug. + +@todo Does Subversion's treatment of line-endings for files marked with +svn:eol-style=native continue to pose the problems described here, or +has this been magically solved? + +@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, tracking the +Subversion repository with git-svn and employing GIT conventions and +methodologies for development. + +@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-head/ +$ svn up && svn st +At revision NNNN. +$ <<>> +... +$ <<>> +$ svn diff > series-1.patch # patch #1 is easy +$ <<>> +... +$ <<>> +$ svn diff > series-1+2.patch # create patch 1+2 +$ interdiff series-1{,+2}.patch > series-2.patch # 1 ~ 1+2 => #2 +$ <<>> +... +$ <<>> +$ svn 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. + +@subsection primerpatchseriesgit Using @c git + +The @c git revision control system provides a tool for tracking +Subversion repositories. + +@section primerpatchsubmit Submitting Patches + +Write access to the OpenOCD Subversion 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 Subversion repository must be handled by one of +these maintainers. + +Patches must be sent to the OpenOCD developer mailing list: +@par + openocd-development@lists.berlios.de + +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. + + */ +/** @file +This file contains the @ref patchprimer page. +*/