diff options
Diffstat (limited to 'doc/manual')
| -rw-r--r-- | doc/manual/primer/autotools.txt | 6 | ||||
| -rw-r--r-- | doc/manual/primer/patches.txt | 95 | ||||
| -rw-r--r-- | doc/manual/release.txt | 36 | ||||
| -rw-r--r-- | doc/manual/style.txt | 8 |
4 files changed, 46 insertions, 99 deletions
diff --git a/doc/manual/primer/autotools.txt b/doc/manual/primer/autotools.txt index fbf42196..28a4b5f6 100644 --- a/doc/manual/primer/autotools.txt +++ b/doc/manual/primer/autotools.txt @@ -22,14 +22,14 @@ cases, a fresh bootstrap may be still required. @subsection primerbootstrapcures Problems Solved By Bootstrap For example, the build system can fail in unexpected ways after running -<code>svn update</code>. Here, the <code>make maintainer-clean</code> +<code>git pull</code>. Here, the <code>make maintainer-clean</code> should be used to remove all of the files generated by the @c bootstrap script and subsequent build processes. In this particular case, one may also need to remove stray files by hand after running this command to ensure everything is rebuilt properly. This step should be necessary only if the @c maintainer-clean was run -@b after altering the build system files with Subversion. If it is run +@b after altering the build system files with git. If it is run @b before any updates, the build system should never leave artifacts in the tree. @@ -61,7 +61,7 @@ experience errors when running @c make that some files cannot be found the problems. The isssue is well-known and expected, if unfortunate. The OpenOCD project requires that all developers building from the -Subversion repository use the @c --enable-maintainer-mode option when +git repository use the @c --enable-maintainer-mode option when running the @c configure script. This option ensures that certain files are created during the build process that would normally be packaged in the distribution tarball. The @c bootstrap script will remind you of diff --git a/doc/manual/primer/patches.txt b/doc/manual/primer/patches.txt index b24e72fa..a894234c 100644 --- a/doc/manual/primer/patches.txt +++ b/doc/manual/primer/patches.txt @@ -6,10 +6,10 @@ 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), +- checkout the git 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. +- 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 @@ -20,7 +20,7 @@ patches, and keep the focus to a single logical change. 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 +git diff > patch-name.patch @endverbatim where @a patch-name should be something that is descriptive and unique. @@ -29,8 +29,8 @@ 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 > <patch-name>-doc.patch -svn diff src > <patch-name>-src.patch +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 @@ -56,65 +56,20 @@ 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>svn up</code>) before creating +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>svn diff</code>", Subversion will +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>svn diff</code>. Overlapping patches will be discussed in the +<code>git diff</code>. 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? +@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 @@ -132,9 +87,8 @@ 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. +Others take their patch management a step further, using stkgit or +some other framework on top of git. @subsection primerpatchseriesinterdiff Using @c interdiff @@ -144,22 +98,22 @@ 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. +$ cd openocd/ +$ git pull +... $ <<<start changes for patch #1>>> ... $ <<<finish changes for patch #1>>> -$ svn diff > series-1.patch # patch #1 is easy +$ git diff > series-1.patch # patch #1 is easy $ <<<start changes for patch #2>>> ... $ <<<finish changes for patch #2>>> -$ svn diff > series-1+2.patch # create patch 1+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>>> -$ svn diff > series-1+2+3.patch # create patch 1+2+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 @@ -173,19 +127,14 @@ 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 +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 Subversion repository must be handled by one of +Thus, commits to the git repository must be handled by one of these maintainers. Patches must be sent to the OpenOCD developer mailing list: diff --git a/doc/manual/release.txt b/doc/manual/release.txt index 2ba652de..64dcb811 100644 --- a/doc/manual/release.txt +++ b/doc/manual/release.txt @@ -26,13 +26,13 @@ formats: <code>openocd-\<version\>.{tar.gz,tar.bz2,zip}</code>. If produced properly, these files are suitable for release to the public. When released for users, these archives present several important -advantages when contrasted to using the Subversion repository trunk: +advantages when contrasted to using the git repository: -# They allow others to package and distribute the code. -# They build easier for developers, because they contain a working configure script that was produced by the Release Manager. --# They prevent users from trying a random HEAD revision of the trunk. --# They free developers from answering questions about trunk breakage. +-# They prevent users from trying a random work-in-process revision. +-# They free developers from answering questions about mainline breakage. Hopefully, this shows several good reasons to produce regular releases, but the release processes were developed with some additional design @@ -64,9 +64,9 @@ the minor version will @a also be zero (<code>y = 0, z = 0</code>). After these required numeric components, the version string may contain one or more <i>version tags</i>, such as '-rc1' or '-dev'. -The trunk and all branches should have the tag '-dev' in +Mainline and all branches should have the tag '-dev' in their version number. This tag helps developers identify reports -created from the Subversion repository, and it can be detected and +created from the git repository, and it can be detected and manipulated by the release script. Specifically, this tag will be removed and re-added during the release process; it should never be manipulated by developers in submitted patches. @@ -159,8 +159,8 @@ If T is the time of the next release, then the following schedule might describe some of the key milestones of the new release cycle: - T minus one month: start of new development cycle -- T minus two weeks: announce pending trunk closure to new work -- T minus one week: close trunk to new work, begin testing phase +- T minus two weeks: announce pending mainline closure to new work +- T minus one week: close mainline to new work, begin testing phase - T minus two days: call for final bug fixes - T minus one day: produce -rc packages and distribute to testers - T minus one hour: produce final packages and post on-line @@ -212,20 +212,20 @@ Even with the release script, some steps require clear user intervention The following steps should be followed to produce each release: --# Produce final patches to the trunk (or release branch): +-# Produce final patches to mainline (or release branch): -# Finalize @c NEWS file to describe the changes in the release - This file is Used to automatically post "blurbs" about the project. - This material should be produced during the development cycle. - Add a new item for each @c NEWS-worthy contribution, when committed. -# bump library version if our API changed (not yet required) -# Remove -dev tag from package version in configure.in: - - For major/minor releases, remove version tag from trunk, @a or + - For major/minor releases, remove version tag from mainline, @a or - For bug-fix releases, remove version tag from release branch. --# Branch or tag the required tree in the Subversion repository: +-# Branch or tag the required tree in the git repository: - Tags and branches for releases must be named consistently: @par "${PACKAGE_TARNAME}-${PACKAGE_VERSION}" - - For a major/minor release from the main trunk, the code should be - branched and tagged in the repository: + - For a major/minor release from the mainline, the code should be + tagged in the repository: @verbatim svn cp .../trunk .../branches/${RELEASE_BRANCH} svn cp .../branches/${RELEASE_BRANCH} .../tags/${RELEASE_TAG} @@ -238,9 +238,9 @@ svn cp .../branches/${RELEASE_BRANCH} .../tags/${RELEASE_TAG} -# Prepare to resume normal development activities: - Archive @c NEWS file as <code>doc/news/NEWS-${PACKAGE_VERSION}</code>. - Create a new @c NEWS file for the next release - - For major/minor release from the trunk: - -# Bump major or minor package version in trunk. - -# Restore version tag to trunk and release branch. + - For major/minor release from the mainline: + -# Bump major or minor package version in mainline. + -# Restore version tag to mainline. - For bug-fix releases from a release branch: -# Bump bug-fix version in release branch. -# Restore version tag to release branch. @@ -310,7 +310,7 @@ Packaging Commands: Repository Commands: commit Perform branch and tag, as appropriate for the version. - branch Create a release branch from the project trunk. + branch Create a release branch from project mainline. tag Create a tag for the current release branch. Other Commands: @@ -338,7 +338,7 @@ affect its behavior: and it produces archives that are unsuitable for public release. @note Only the Release Manager should use the @c --live option, as -it will make permanent changes to the Subversion repository that +it will make permanent changes to the git repository that cannot be undone. @subsection releasescriptenv Release Script Environment @@ -371,7 +371,7 @@ use to run the @c release.sh script to produce a minor release. If the proper environment has been set, the following steps will produce a new minor release: --# Check out (or update) the project trunk from the berliOS repository: +-# Check out (or update) mainline from the repository: @code svn checkout "${SVN_URL}/trunk" openocd-trunk @endcode diff --git a/doc/manual/style.txt b/doc/manual/style.txt index ef73aed6..b6d68b48 100644 --- a/doc/manual/style.txt +++ b/doc/manual/style.txt @@ -49,7 +49,7 @@ OpenOCD project. - limit adjacent empty lines to at most two (2). - remove any trailing empty lines at the end of source files - do not "comment out" code from the tree; instead, one should either: - -# remove it entirely (Subversion can retrieve the old version), or + -# remove it entirely (git can retrieve the old version), or -# use an @c \#if/\#endif block. Finally, try to avoid lines of code that are longer than than 72-80 columns: @@ -358,10 +358,8 @@ perl script.pl Maintainers must also be sure to follow additional guidelines: -# Ensure that Perl scripts are committed as executables: - - Use "<code>chmod +x script.pl</code>" - @a before using "<code>svn add script.pl</code>", or - - Use "<code>svn ps svn:executable '*' script.pl</code>" - @a after using "<code>svn add script.pl</code>". + Use "<code>chmod +x script.pl</code>" + @a before using "<code>git add script.pl</code>" */ /** @page styleautotools Autotools Style Guide |