Author: britter
Date: Tue Jan 6 20:29:00 2015
New Revision: 1649938
URL: http://svn.apache.org/r1649938
Log:
Commit log should be checked before release notes are generated
Modified:
commons/cms-site/trunk/content/xdoc/releases/prepare.xml
Modified: commons/cms-site/trunk/content/xdoc/releases/prepare.xml
URL:
http://svn.apache.org/viewvc/commons/cms-site/trunk/content/xdoc/releases/prepare.xml?rev=1649938&r1=1649937&r2=1649938&view=diff
==============================================================================
--- commons/cms-site/trunk/content/xdoc/releases/prepare.xml (original)
+++ commons/cms-site/trunk/content/xdoc/releases/prepare.xml Tue Jan 6
20:29:00 2015
@@ -241,7 +241,67 @@
</ul>
</p>
</subsection>
+ <subsection name='Check the commit log'>
+ <p>
+ Different components have their own ways of creating the change log.
+ The most common, and recommended, way, is to record all significant
+ changes in JIRA tickets and include entries in the Maven change-log
+ file, <code>changes.xml</code>. If your component has a change-log you
+ can skip this step.</p>
+ <p>Here's a way to get the information directly from svn if no change log
+ has been maintained for the component:
+ </p>
+ <p>
+ Get a list of all the commits since the last release by following
these steps.
+ <br/>
+ Assuming that, as part of the last release, a directory
{project-base}/tags/foo-1.1
+ had been created:
+ <pre>
+ cd {project-base}/tags
+ svn log --stop-on-copy foo-1.1
+ # The last revision NNNN reported in the log output is the revision
that was
+ # copied to create the tag. If this is a true tag directory, then of
course
+ # there will only be one revision listed by the log command..
+
+ cd ..
+ svn log -v -rNNNN:HEAD trunk > commits-since-last-release.txt
+ </pre>
+ </p>
+ <p>
+ This will result in a file that contains info on each commit that
affected at
+ least one file within the trunk directory since the last release. Note
that if
+ a commit affected a group of files of which some were outside the
trunk directory,
+ then they will be included with the associated commit message but can
be ignored.
+ </p>
+ <p>
+ Using "svn diff" instead of "svn log -v" will result instead in a file
that shows the
+ actual diffs for each file instead of the commit messages. This may be
more convenient
+ when the commit messages are not sufficiently detailed to be able to
build the release
+ notes directly from them.
+ </p>
+ <p>
+ Inspect the list of changes and enter relevant information into the
release notes;
+ this may require inspecting the actual changes using "svn diff".
+ Enhancements and new features need to be collated by topic.
+ Bugs fixed should be listed separately together with a short summary
of the bug.
+ </p>
+ <p>
+ Please remember to spell check the release notes. Please break lines
at 80 characters.
+ </p>
+ <p>
+ <b>IMPORTANT!</b> At the current time, selecting by date in subversion
within the
+ ASF repository isn't reliable. The reason is that when converting a
date to a revision
+ number, subversion assumes that revision N has an earlier date than
revision N+M, and
+ that it can therefore perform a binary search on revision numbers to
locate one with
+ the required date. However CVS imports of data that retain the
original date
+ information from CVS break this assumption. And unfortunately because
revisions
+ are repository-wide information, this affects date-based searches
+ even in directories unrelated to the ones that CVS stuff was imported
into.
+ So while dates are reported correctly in "svn log" output, only
revision numbers should
+ be used with the -r option. See issue #752 in the subversion issue
tracker at tigris.org.
+ </p>
+ </subsection>
<subsection name='Prepare Release Notes'>
<p>
Each component should have a file RELEASE-NOTES.txt in the base directory
of the component.
@@ -283,68 +343,6 @@
read easily without word wrap.
</p>
</subsection>
- <subsection name='Check the commit log'>
- <p>
- Different components have their own ways of creating the change log.
- The most common, and recommended, way, is to record all significant
- changes in JIRA tickets and include entries in the Maven change-log
- file, <code>changes.xml</code>. If your component has a change-log you
- can skip this step.</p>
- <p>Here's a way to get the information directly from svn if no change
log
- has been maintained for the component:
- </p>
- <p>
- Get a list of all the commits since the last release by following
these steps.
- <br/>
- Assuming that, as part of the last release, a directory
{project-base}/tags/foo-1.1
- had been created:
- <pre>
- cd {project-base}/tags
-
- svn log --stop-on-copy foo-1.1
- # The last revision NNNN reported in the log output is the revision that
was
- # copied to create the tag. If this is a true tag directory, then of
course
- # there will only be one revision listed by the log command..
-
- cd ..
- svn log -v -rNNNN:HEAD trunk > commits-since-last-release.txt
- </pre>
- </p>
- <p>
- This will result in a file that contains info on each commit that
affected at
- least one file within the trunk directory since the last release. Note
that if
- a commit affected a group of files of which some were outside the
trunk directory,
- then they will be included with the associated commit message but can
be ignored.
- </p>
- <p>
- Using "svn diff" instead of "svn log -v" will result instead in a file
that shows the
- actual diffs for each file instead of the commit messages. This may be
more convenient
- when the commit messages are not sufficiently detailed to be able to
build the release
- notes directly from them.
- </p>
- <p>
- Inspect the list of changes and enter relevant information into the
release notes;
- this may require inspecting the actual changes using "svn diff".
- Enhancements and new features need to be collated by topic.
- Bugs fixed should be listed separately together with a short summary
of the bug.
- </p>
- <p>
- Please remember to spell check the release notes. Please break lines
at 80 characters.
- </p>
- <p>
- <b>IMPORTANT!</b> At the current time, selecting by date in subversion
within the
- ASF repository isn't reliable. The reason is that when converting a
date to a revision
- number, subversion assumes that revision N has an earlier date than
revision N+M, and
- that it can therefore perform a binary search on revision numbers to
locate one with
- the required date. However CVS imports of data that retain the
original date
- information from CVS break this assumption. And unfortunately because
revisions
- are repository-wide information, this affects date-based searches
- even in directories unrelated to the ones that CVS stuff was imported
into.
- So while dates are reported correctly in "svn log" output, only
revision numbers should
- be used with the -r option. See issue #752 in the subversion issue
tracker at tigris.org.
- </p>
- </subsection>
-
<subsection name='Test Against Listed Dependencies'>
<p>
If you are using Maven to execute the unit tests associated with the
component then
