Source Release for BES: Difference between revisions

From OPeNDAP Documentation
⧼opendap2-jumptonavigation⧽
(Created page with " Note that the old pages with the tables of version numbers are gone. Use the web pages themselves as documentation of what has or has not been built. For the current release, in...")
 
No edit summary
Line 6: Line 6:
#First, make sure that the source code you're using is on a branch, up-to-date (''svn up'') and that the software passes its tests and no outstanding tickets remain for the release milestone.
#First, make sure that the source code you're using is on a branch, up-to-date (''svn up'') and that the software passes its tests and no outstanding tickets remain for the release milestone.
#Update the text documentation files and version numbers in the configuration files:
#Update the text documentation files and version numbers in the configuration files:
##Update the '''ChangeLog''' file using the script ''update_cl.sh'' which can be found in the ''svn-tools'' project. (e.g., ~/svn-tools/update_cl.sh 2005-12-20 ChangeLog). If you're making the first ChangeLog entries, then you'll need to create the ChangeLog file first. Here's a key tip: When you're making the commit log entries, always include the file name(s) of the affected files in your entry. Then to write the NEWS file, just read over the new ChangeLog entries and summarize. In the old days of CVS, the logs automatically included the names of the changed files, but subversion doesn't do that. A little discipline with those log entries will go a long way toward streamlining the release process!
#*Update the '''ChangeLog''' file using the script ''update_cl.sh'' which can be found in the ''svn-tools'' project. (e.g., ~/svn-tools/update_cl.sh 2005-12-20 ChangeLog). If you're making the first ChangeLog entries, then you'll need to create the ChangeLog file first. Here's a key tip: When you're making the commit log entries, always include the file name(s) of the affected files in your entry. Then to write the NEWS file, just read over the new ChangeLog entries and summarize. In the old days of CVS, the logs automatically included the names of the changed files, but subversion doesn't do that. A little discipline with those log entries will go a long way toward streamlining the release process!
##Make sure that the version number is set in the '''configure.ac''' and '''*.spec''' files! When the version number changes, reset the RPM release number to '1'. For several releases of the same version, increment the release number (the number after the dash in the RPM file name; we don't have release numbers for the tar files). ''I generally update the ChangeLog before updating the version numbers or NEWS, et c., files because the ChangeLog gives me a bird's eye view of what happened since the last release.''
#*Make sure that the version number is set in the '''configure.ac''' and '''*.spec''' files! When the version number changes, reset the RPM release number to '1'. For several releases of the same version, increment the release number (the number after the dash in the RPM file name; we don't have release numbers for the tar files). ''I generally update the ChangeLog before updating the version numbers or NEWS, et c., files because the ChangeLog gives me a bird's eye view of what happened since the last release.''
##libtool versioning rules:
#*libtool versioning rules: What the ''CURRENT[:REVISION[:AGE]]'' string passed to ''libtool means:'' (Note these are set using variables in the configure.ac script.)
      What is meant by the ''CURRENT[:REVISION[:AGE]]'' string passed to ''libtool.'' Note these are set using variables in the configure.ac script.
#**No interfaces changed, only implementations (good): ==> Increment REVISION.
###No interfaces changed, only implementations (good): ==> Increment REVISION.
#**Interfaces added, none removed (good): ==> Increment CURRENT, increment AGE, set REVISION to 0.
###Interfaces added, none removed (good): ==> Increment CURRENT, increment AGE, set REVISION to 0.
#**Interfaces removed or changed (BAD, breaks upward compatibility): ==> Increment CURRENT, set AGE and REVISION to 0.
###Interfaces removed or changed (BAD, breaks upward compatibility): ==> Increment CURRENT, set AGE and REVISION to 0.
#**So how do you know? For C++, build a file of the methods and their arguments using ''nm .libs/libdap.a | c++filt | grep ' T .*::' | sed 's@.* T \(.*\)@\1@' > libdap_funcs'' and compare that using diff on the previous release's library.
###So how do you know? For C++, build a file of the methods and their arguments using ''nm .libs/libdap.a | c++filt | grep ' T .*::' | sed 's@.* T \(.*\)@\1@' > libdap_funcs'' and compare that using diff on the previous release's library.
#**Make sure that '''README''', '''INSTALL''' and '''NEWS''' are updated (setting ''check-news'' in ''Makefile.am'' ''AUTOMAKE_OPTIONS'' will enforce this).
  2. Make sure that '''README''', '''INSTALL''' and '''NEWS''' are updated (setting ''check-news'' in ''Makefile.am'' ''AUTOMAKE_OPTIONS'' will enforce this).
#Check in these changes.
#Check in these changes.
#Tag the release:
#Tag the release:
##I use svn="http://scm.opendap.org/svn" in the following and in my shell.
#*I use svn="http://scm.opendap.org/svn" in the following and in my shell.
##Use ''svn copy $svn/branch/<<package>> $svn/tags/<<package-name>>/<<release-number>>''
#*Use ''svn copy $svn/branch/<<package>> $svn/tags/<<package-name>>/<<release-number>>''
  2. If this is the first release of <<package-name>>, you have to create the directory under ''tags'' using ''svn mkdir''.
#*If this is the first release of <<package-name>>, you have to create the directory under ''tags'' using ''svn mkdir''.
#Use svn's ''export'' command to get a copy of the code that does not have the <tt>.svn</tt> directories.
#Use svn's ''export'' command to get a copy of the code that does not have the <tt>.svn</tt> directories.
#Use automake's ''distcheck'' target (''make distcheck'') to make a source code tar file.
#Use automake's ''distcheck'' target (''make distcheck'') to make a source code tar file.
Line 26: Line 25:
#Move the file to the web site for distribution.
#Move the file to the web site for distribution.
#Update the web pages:
#Update the web pages:
##Edit the package-specific page
#*Edit the package-specific page
  2. Edit the download ''index.html'' page
#*Edit the download ''index.html'' page
  2. Edit the ''whatsnew.html'' page
#*Edit the ''whatsnew.html'' page
  2. Add the edits from ''Whatsnew.html'' to the main ''index.html'' page under the News heading - the <tt><tr></tt> blocks can be copied verbatim and then the <tt><name></tt> element changed to a <tt><href></tt>. Follow the examples of the other entries.
#*Add the edits from ''Whatsnew.html'' to the main ''index.html'' page under the News heading - the <tt><tr></tt> blocks can be copied verbatim and then the <tt><name></tt> element changed to a <tt><href></tt>. Follow the examples of the other entries.
  2. edit the ''news.xml'' page to '''update the RSS news feed.''' One very useful tool is the RSS [http://feedvalidator.org/ Feed Validator].
#*edit the ''news.xml'' page to '''update the RSS news feed.''' One very useful tool is the RSS [http://feedvalidator.org/ Feed Validator].
  2. Edit the What's New section of the front page.
#*Edit the What's New section of the front page.
  2. Check in those changes and ask someone else in the group to look them over. ''The more people from our group that look over prospective changes, the better.'' Then find someone who has write access to the web site and have them update the served pages. People who have write access are Yuan, James and Dan (at least, maybe others).
#*Check in those changes and ask someone else in the group to look them over. ''The more people from our group that look over prospective changes, the better.'' Then find someone who has write access to the web site and have them update the served pages. People who have write access are Yuan, James and Dan (at least, maybe others).
#Build binaries and upload to the web site as time permits. See [[Distributions]].
#Build binaries and upload to the web site as time permits. See [[Distributions]].

Revision as of 21:04, 29 February 2012

Note that the old pages with the tables of version numbers are gone. Use the web pages themselves as documentation of what has or has not been built. For the current release, include grayed-out links to binaries we do plan to make but keep the grayed-out links in place for the current version only!

Here's how to make a source release:

  1. First, make sure that the source code you're using is on a branch, up-to-date (svn up) and that the software passes its tests and no outstanding tickets remain for the release milestone.
  2. Update the text documentation files and version numbers in the configuration files:
    • Update the ChangeLog file using the script update_cl.sh which can be found in the svn-tools project. (e.g., ~/svn-tools/update_cl.sh 2005-12-20 ChangeLog). If you're making the first ChangeLog entries, then you'll need to create the ChangeLog file first. Here's a key tip: When you're making the commit log entries, always include the file name(s) of the affected files in your entry. Then to write the NEWS file, just read over the new ChangeLog entries and summarize. In the old days of CVS, the logs automatically included the names of the changed files, but subversion doesn't do that. A little discipline with those log entries will go a long way toward streamlining the release process!
    • Make sure that the version number is set in the configure.ac and *.spec files! When the version number changes, reset the RPM release number to '1'. For several releases of the same version, increment the release number (the number after the dash in the RPM file name; we don't have release numbers for the tar files). I generally update the ChangeLog before updating the version numbers or NEWS, et c., files because the ChangeLog gives me a bird's eye view of what happened since the last release.
    • libtool versioning rules: What the CURRENT[:REVISION[:AGE]] string passed to libtool means: (Note these are set using variables in the configure.ac script.)
      • No interfaces changed, only implementations (good): ==> Increment REVISION.
      • Interfaces added, none removed (good): ==> Increment CURRENT, increment AGE, set REVISION to 0.
      • Interfaces removed or changed (BAD, breaks upward compatibility): ==> Increment CURRENT, set AGE and REVISION to 0.
      • So how do you know? For C++, build a file of the methods and their arguments using nm .libs/libdap.a | c++filt | grep ' T .*::' | sed 's@.* T \(.*\)@\1@' > libdap_funcs and compare that using diff on the previous release's library.
      • Make sure that README, INSTALL and NEWS are updated (setting check-news in Makefile.am AUTOMAKE_OPTIONS will enforce this).
  3. Check in these changes.
  4. Tag the release:
    • I use svn="http://scm.opendap.org/svn" in the following and in my shell.
    • Use svn copy $svn/branch/<<package>> $svn/tags/<<package-name>>/<<release-number>>
    • If this is the first release of <<package-name>>, you have to create the directory under tags using svn mkdir.
  5. Use svn's export command to get a copy of the code that does not have the .svn directories.
  6. Use automake's distcheck target (make distcheck) to make a source code tar file.
  7. Sign the tar file. See the help item on the main trac wiki page if you need instructions.
  8. Also check that the RPM and DMG targets are working. This is a lower priority item then the distcheck target because these targets seem pretty stable unless the packaging and distribution files are changed. If that is the case, these targets should be checked.
  9. Move the file to the web site for distribution.
  10. Update the web pages:
    • Edit the package-specific page
    • Edit the download index.html page
    • Edit the whatsnew.html page
    • Add the edits from Whatsnew.html to the main index.html page under the News heading - the blocks can be copied verbatim and then the <name> element changed to a <href>. Follow the examples of the other entries.
    • edit the news.xml page to update the RSS news feed. One very useful tool is the RSS Feed Validator.
    • Edit the What's New section of the front page.
    • Check in those changes and ask someone else in the group to look them over. The more people from our group that look over prospective changes, the better. Then find someone who has write access to the web site and have them update the served pages. People who have write access are Yuan, James and Dan (at least, maybe others).
  11. Build binaries and upload to the web site as time permits. See Distributions.