Difference between revisions of "NewRelease"

From RackTables Wiki
Jump to: navigation, search
m (rolling out)
m (part 1: simplify the git command)
 
(44 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
== pre-release checklist ==
 
== pre-release checklist ==
First make sure, that all necessary changes are already committed into the repository:
+
=== part 1 ===
* All release notes, if any, must appear both in upgrade script and in the README.
+
Make sure all necessary changes have been committed into the repository:
* Current date must be present on the version line of <tt>ChangeLog</tt>.
+
<ul>
* Make sure, that <tt>upgrade.php</tt> has new version listed in <tt>$versionhistory</tt> and <tt>executeUpgradeBatch()</tt>. It is normal to accumulate updates in <tt>executeUpgradeBatch()</tt> long before the release, this way on the release day you will have nothing to do in <tt>upgrade.php</tt>. But if you had no changes to DB since the last release, you are likely to see there changes missing. Just make sure the new version is in both places anyway.
 
* Bump up CODE_VERSION in <tt>inc/config.php</tt>. DON'T do this unless you really intend to make a release right now.
 
* svn stat; svn commit
 
  
Now export the codebase from the trunk (or maintenance branch, whichever you are releasing from) and test it.
+
<li>Make sure you have the right branch checked out and no pending changes are in the working copy:
 
<pre>
 
<pre>
# export --force in case the target directory already exists
+
git status
svn export https://racktables.svn.sourceforge.net/svnroot/racktables/branches/maintenance-0.19.x .
 
 
</pre>
 
</pre>
* The application must be able to install itself with own installer. Once this is found working, dump the database:
+
<li>If the new release should have any release notes, make sure these appear both in <tt>wwwroot/inc/upgrade.php</tt> and in <tt>README</tt>.</li>
 +
 
 +
<li>Update <tt>ChangeLog</tt> file to have the current date on the to-be version line.</li>
 +
 
 +
<li>Make sure <tt>upgrade.php</tt> has the to-be version listed in <tt>$versionhistory</tt> and <tt>getUpgradeBatch()</tt>. It is normal to accumulate updates in <tt>getUpgradeBatch()</tt> long before the release, this way on the release day you will have nothing to do in <tt>upgrade.php</tt>. But if you had no changes to DB since the last release, you are likely to see there changes missing. Just make sure the new version is in both places anyway.</li>
 +
 
 +
<li>Bump up <tt>CODE_VERSION</tt> in <tt>wwwroot/inc/config.php</tt>. DON'T do this unless you really intend to make a release right now.</li>
 +
 
 +
<li>Produce a commit with all changes pending thus far:
 +
<pre>
 +
git add ChangeLog wwwroot/inc/config.php
 +
git commit
 +
</pre>
 +
</li>
 +
 
 +
<li>Check the source code out from the same branch to a '''clean location''' to test it.
 +
<pre>
 +
git clone git@github.com:RackTables/racktables.git
 +
cd racktables
 +
git checkout master # or maintenance
 +
</pre></li>
 +
 
 +
<li>The application must be able to install itself using its own installer (only some of the involved code is in the Travis CI script). Once this is found working, dump the database:
 
<pre>
 
<pre>
 
mysqldump --extended-insert=FALSE --order-by-primary racktables_db > ~/tmp/dump-fresh.sql
 
mysqldump --extended-insert=FALSE --order-by-primary racktables_db > ~/tmp/dump-fresh.sql
</pre>
+
</pre></li>
* Demo data should also be loadable and functional:
+
 
 +
<li>Demo data must be loadable without any errors (this is likely to be OK since this check is now in the Travis CI script):
 
<pre>
 
<pre>
 
mysql racktables_db < scripts/init-sample-racks.sql
 
mysql racktables_db < scripts/init-sample-racks.sql
</pre>
+
</pre></li>
* The release being tested must detect and upgrade a database from the previous release(s) correctly. Load the database with one of the previous releases data, then upgrade it with the current upgrader, then dump the DB. Now compare to the previous dump, there must be no meaningful differences.
+
 
 +
<li>The release being tested must detect and upgrade a database from the previous release(s) correctly. Load the database with one of the previous releases data, then upgrade it with the current upgrader, then dump the DB. Now compare to the previous dump, there must be no meaningful differences.
 
<pre>
 
<pre>
racktables/contribs/demoreload.sh X.Y.z racktables_db
+
# reload using the previous release
# (upgrade.php)
+
/path/to/racktables-contribs/demo.racktables.org/demoreload.sh X.Y.z racktables_db no
 +
# (make through upgrade.php)
 
mysqldump --extended-insert=FALSE --order-by-primary racktables_db > ~/tmp/dump-upgraded.sql
 
mysqldump --extended-insert=FALSE --order-by-primary racktables_db > ~/tmp/dump-upgraded.sql
 
diff -u ~/tmp/dump-fresh.sql ~/tmp/dump-upgraded.sql
 
diff -u ~/tmp/dump-fresh.sql ~/tmp/dump-upgraded.sql
 +
</pre></li>
 +
 +
=== part 2 (unit testing) ===
 +
'''''The commands below need some proofreading because the test data files in the source code tree still use the <tt>racktables</tt> MySQL username, which I had for this reason used for the 0.20.12 release. Whatever is the agreed username, it probably should be consistent with what is in the SQL dumps. -- Denis'''''
 +
 +
<li>Setup a fresh database and grant access to the 'racktables_user' user.  This will be used to create a sample data file that unit tests can utilize.</li>
 +
<pre>
 +
DROP DATABASE IF EXISTS racktables_unittest;
 +
CREATE DATABASE racktables_unittest CHARACTER SET utf8 COLLATE utf8_general_ci;
 +
GRANT ALL PRIVILEGES ON racktables_unittest.* TO racktables_user@localhost IDENTIFIED BY 'MY_SECRET_PASSWORD';
 
</pre>
 
</pre>
* Test the source as much as you find possible.
+
 
* Look into the error log of the server you used for the tests. There shouldn't be any error/warning messages.
+
<li>Use the web interface to complete the installation. When prompted to set the admin password, enter 'admin'.</li>
The above rounds may happen repeated more, than once, until everything is fixed consistently.
+
 
 +
<li>Load the sample data.</li>
 +
<pre>mysql -u racktables_user -p racktables_unittest < scripts/init-sample-racks.sql</pre>
 +
 
 +
<li>Export the database to the tests/data dir.</li>
 +
<pre>mysqldump --skip-comments -u racktables_user -p racktables_unittest > tests/data/$CODE_VERSION.sql</pre>
 +
 
 +
<li>Run the unit tests. Fix any failures.</li>
 +
<pre>
 +
cd tests
 +
./express.sh
 +
phpunit --group large
 +
</pre>
 +
 
 +
<li>If all is OK, commit the new SQL dump in the <tt>tests/data</tt> directory.</li>
 +
 
 +
=== part 3 (finalization) ===
 +
<li>Test the source by hand as much as you find possible.</li>
 +
 
 +
<li>Look into the error log of the server you used for the tests. There shouldn't be any error/warning messages.</li>
 +
 
 +
<li>Do not proceed further until everything is fixed consistently.</li>
 +
</ul>
  
 
== the release itself ==
 
== the release itself ==
 
<pre>
 
<pre>
# from trunk (beta testing releases):
+
git tag RackTables-X.Y.z
svn cp \
+
git push origin RackTables-X.Y.z
https://racktables.svn.sourceforge.net/svnroot/racktables/trunk \
 
https://racktables.svn.sourceforge.net/svnroot/racktables/tags/RackTables-0.Y.z
 
 
 
# from maintenance (stable releases):
 
svn cp \
 
https://racktables.svn.sourceforge.net/svnroot/racktables/branches/maintenance-0.Y.x \
 
https://racktables.svn.sourceforge.net/svnroot/racktables/tags/RackTables-0.Y.z
 
 
</pre>
 
</pre>
  
 
== rolling out ==
 
== rolling out ==
* Make a tarball:
+
=== producing and publishing deliverables ===
 +
* Make two archives:
 
<pre>
 
<pre>
svn export https://racktables.svn.sourceforge.net/svnroot/racktables/tags/RackTables-X.Y.z
+
export TAG='RackTables-X.Y.z'
tar czf RackTables-X.Y.z.tar.gz RackTables-X.Y.z
+
git archive --prefix=$TAG/ -o $TAG.tar.gz $TAG
zip -r RackTables-X.Y.z.zip RackTables-X.Y.z
+
git archive --prefix=$TAG/ -o $TAG.zip $TAG
 
</pre>
 
</pre>
* Upload the tarball and zipfile to SF FRS ([https://sourceforge.net/projects/racktables/files/ from browser] or by [https://sourceforge.net/apps/trac/sourceforge/wiki/Release%20files%20for%20download other means]).
+
* Upload the tarball and zipfile to SF FRS ([https://sourceforge.net/projects/racktables/files/ from browser] or by [https://sourceforge.net/p/forge/documentation/Release%20Files%20for%20Download/ other means] if you prefer). Give the uploaded files a couple minutes to make it through the system to the user-visible download area.
* Open [https://sourceforge.net/projects/racktables/files files section] and set the newly uploaded tar.gz as "current".
+
* Open [https://sourceforge.net/projects/racktables/files files section] and set the newly uploaded release files as "current".
** Open properties form (round "i" sign) of the previous release tar.gz.
+
** Open properties form (round "(i)" sign) of the previous release tar.gz.
 
** Unset all "default download for" checkboxes.
 
** Unset all "default download for" checkboxes.
 
** Unset "download button" text.
 
** Unset "download button" text.
 
** Save.
 
** Save.
** Open properties form (round "i" sign) of the previous release zip.
+
** Open properties form (round "(i)" sign) of the previous release zip.
 
** Unset Windows "default download for" checkbox.
 
** Unset Windows "default download for" checkbox.
 
** Unset "download button" text.
 
** Unset "download button" text.
Line 65: Line 112:
 
** Save.
 
** Save.
 
** In the latest zipfile properties form, set Windows "default download for" checkbox.
 
** In the latest zipfile properties form, set Windows "default download for" checkbox.
 +
** Set "download button" text to "latest stable".
 
** Save.
 
** Save.
 
** Hover the big green "download" button and watch the mouse hint featuring the right version number (sometimes it takes several minutes to see the update).
 
** Hover the big green "download" button and watch the mouse hint featuring the right version number (sometimes it takes several minutes to see the update).
* In MantisBT mark version as released (Manage, Manage Projects, [http://bugs.racktables.org/manage_proj_edit_page.php?project_id=1 RackTables], Versions).
+
** '''Tip:''' to update the banner text below the file list of the SF's "Files" section open a terminal connection to SF shell and edit the file <tt>/home/frs/project/racktables/README.md</tt> (once done, let the SF 5-10 minutes to start using the updated revision).
* Log into SF shell service:
+
 
 +
=== updating Mantis ===
 +
* In MantisBT mark the released version as released (Manage, Manage Projects, [https://bugs.racktables.org/manage_proj_edit_page.php?project_id=1 RackTables], Versions). Add the next version with the release date several months into the future.
 +
 
 +
=== updating the main web-site ===
 +
* In racktables-htdocs repository modify and commit <tt>header.php</tt>.
 +
* On the web-server run <tt>git pull</tt>.
 +
* Open https://racktables.org and test the "download" link to work.
 +
 
 +
=== updating other news feeds ===
 +
* Send a letter to the racktables-users list (even more so after Freshmeat/Freecode is gone).
 +
* Update IRC channel topic
 +
 
 +
=== updating demo ===
 +
* Produce a helper SQL file for the current release in [https://github.com/RackTables/racktables-contribs racktables-contribs].
 +
** Copy the previous <tt>init-full-X.Y.z.sql</tt> to current <tt>init-full-X.Y.z.sql</tt> and <tt>git add</tt> the new file.
 +
** Take a clean RackTables instance of the current release (either use demoreload on the previous release or install manually).
 +
** Make an SQL dump of this new installation like this: <tt>mysqldump --extended-insert=FALSE --order-by-primary racktables_db > init-full-X.Y.z.sql</tt>
 +
** Edit permissions like [https://github.com/RackTables/racktables-contribs/commit/0354001ce16e937cfc5ae555fe73dc3c351a6556 this].
 +
** <tt>git add -i</tt> the new file again (note interactive add). Use patch mode to add relevant chunks. Quit.
 +
** <tt>git commit; git push</tt>
 +
* Update demo.racktables.org to the current release (<tt>$demorelease</tt> will need an update). Below is a sample CLI session of updating the demo to 0.20.3:
 
<pre>
 
<pre>
$ cat ~/.ssh/config
+
cd ~/racktables
Host shell.sourceforge.net
+
git fetch
User YOUR_SF_USERNAME,racktables
+
git checkout RackTables-0.20.3
$ ssh -t shell.sourceforge.net create
+
cd
</pre>
+
ln -s racktables RackTables-0.20.3
* Edit (vim) <tt>/home/project-web/racktables/htdocs/header.php</tt> to update <tt>$lastrelease</tt>. Test the "download" link to work after that.
+
# the symlink to ~/secret.php is already in wwwroot/inc/
* Post a Freecode (ex-Freshmeat) release announce
+
# the symlink to ~/google_analytics.php is already in plugins/
** open http://freecode.com/projects/racktables
+
cd ~/racktables-contribs/
** make sure you are logged in (check top bar)
 
** use "submit a release" button to the right
 
** fill in version number
 
** update version number in "tar.gz" and "zip" URL fields
 
** compose 1-2 paragraphs worth of text describing the focus of this release
 
** proofread and submit (usually it takes several hours to pass the moderation)
 
* Send a letter to the racktables-users list, if necessary.
 
* Update demo.racktables.org to the current release (<tt>$demorelease</tt> will need an update). Below is a sample CLI session of updating the demo to 0.19.13:
 
<pre>
 
svn export https://racktables.svn.sourceforge.net/svnroot/racktables/tags/RackTables-0.19.13
 
cd contribs/
 
 
git pull
 
git pull
 
cd
 
cd
 +
~/racktables-contribs/demo.racktables.org/demoreload.sh 0.20.3 rackdemo
 
crontab -e
 
crontab -e
cp local.php secret.php RackTables-0.19.13/wwwroot/inc/
+
# ../../racktables/wwwroot/index.php is already linked as www/demo/index.php
rm www/index.php
 
ln -s ../RackTables-0.19.13/wwwroot/index.php www/index.php
 
./contribs/demoreload.sh 0.19.13 rackdemo
 
 
</pre>
 
</pre>
* Update IRC channel topic
 

Latest revision as of 16:12, 12 June 2019

pre-release checklist

part 1

Make sure all necessary changes have been committed into the repository:

  • Make sure you have the right branch checked out and no pending changes are in the working copy:
    git status
    
  • If the new release should have any release notes, make sure these appear both in wwwroot/inc/upgrade.php and in README.
  • Update ChangeLog file to have the current date on the to-be version line.
  • Make sure upgrade.php has the to-be version listed in $versionhistory and getUpgradeBatch(). It is normal to accumulate updates in getUpgradeBatch() long before the release, this way on the release day you will have nothing to do in upgrade.php. But if you had no changes to DB since the last release, you are likely to see there changes missing. Just make sure the new version is in both places anyway.
  • Bump up CODE_VERSION in wwwroot/inc/config.php. DON'T do this unless you really intend to make a release right now.
  • Produce a commit with all changes pending thus far:
    git add ChangeLog wwwroot/inc/config.php
    git commit
    
  • Check the source code out from the same branch to a clean location to test it.
    git clone git@github.com:RackTables/racktables.git
    cd racktables
    git checkout master # or maintenance
    
  • The application must be able to install itself using its own installer (only some of the involved code is in the Travis CI script). Once this is found working, dump the database:
    mysqldump --extended-insert=FALSE --order-by-primary racktables_db > ~/tmp/dump-fresh.sql
    
  • Demo data must be loadable without any errors (this is likely to be OK since this check is now in the Travis CI script):
    mysql racktables_db < scripts/init-sample-racks.sql
    
  • The release being tested must detect and upgrade a database from the previous release(s) correctly. Load the database with one of the previous releases data, then upgrade it with the current upgrader, then dump the DB. Now compare to the previous dump, there must be no meaningful differences.
    # reload using the previous release
    /path/to/racktables-contribs/demo.racktables.org/demoreload.sh X.Y.z racktables_db no
    # (make through upgrade.php)
    mysqldump --extended-insert=FALSE --order-by-primary racktables_db > ~/tmp/dump-upgraded.sql
    diff -u ~/tmp/dump-fresh.sql ~/tmp/dump-upgraded.sql
    
  • part 2 (unit testing)

    The commands below need some proofreading because the test data files in the source code tree still use the racktables MySQL username, which I had for this reason used for the 0.20.12 release. Whatever is the agreed username, it probably should be consistent with what is in the SQL dumps. -- Denis

  • Setup a fresh database and grant access to the 'racktables_user' user. This will be used to create a sample data file that unit tests can utilize.
  • DROP DATABASE IF EXISTS racktables_unittest;
    CREATE DATABASE racktables_unittest CHARACTER SET utf8 COLLATE utf8_general_ci;
    GRANT ALL PRIVILEGES ON racktables_unittest.* TO racktables_user@localhost IDENTIFIED BY 'MY_SECRET_PASSWORD';
    
  • Use the web interface to complete the installation. When prompted to set the admin password, enter 'admin'.
  • Load the sample data.
  • mysql -u racktables_user -p racktables_unittest < scripts/init-sample-racks.sql
  • Export the database to the tests/data dir.
  • mysqldump --skip-comments -u racktables_user -p racktables_unittest > tests/data/$CODE_VERSION.sql
  • Run the unit tests. Fix any failures.
  • cd tests
    ./express.sh
    phpunit --group large
    
  • If all is OK, commit the new SQL dump in the tests/data directory.
  • part 3 (finalization)

  • Test the source by hand as much as you find possible.
  • Look into the error log of the server you used for the tests. There shouldn't be any error/warning messages.
  • Do not proceed further until everything is fixed consistently.

the release itself

git tag RackTables-X.Y.z
git push origin RackTables-X.Y.z

rolling out

producing and publishing deliverables

  • Make two archives:
export TAG='RackTables-X.Y.z'
git archive --prefix=$TAG/ -o $TAG.tar.gz $TAG
git archive --prefix=$TAG/ -o $TAG.zip $TAG
  • Upload the tarball and zipfile to SF FRS (from browser or by other means if you prefer). Give the uploaded files a couple minutes to make it through the system to the user-visible download area.
  • Open files section and set the newly uploaded release files as "current".
    • Open properties form (round "(i)" sign) of the previous release tar.gz.
    • Unset all "default download for" checkboxes.
    • Unset "download button" text.
    • Save.
    • Open properties form (round "(i)" sign) of the previous release zip.
    • Unset Windows "default download for" checkbox.
    • Unset "download button" text.
    • Save.
    • In the latest tarball properties form, set all "default download for" checkboxes except Windows.
    • Set "download button" text to "latest stable".
    • Save.
    • In the latest zipfile properties form, set Windows "default download for" checkbox.
    • Set "download button" text to "latest stable".
    • Save.
    • Hover the big green "download" button and watch the mouse hint featuring the right version number (sometimes it takes several minutes to see the update).
    • Tip: to update the banner text below the file list of the SF's "Files" section open a terminal connection to SF shell and edit the file /home/frs/project/racktables/README.md (once done, let the SF 5-10 minutes to start using the updated revision).

updating Mantis

  • In MantisBT mark the released version as released (Manage, Manage Projects, RackTables, Versions). Add the next version with the release date several months into the future.

updating the main web-site

  • In racktables-htdocs repository modify and commit header.php.
  • On the web-server run git pull.
  • Open https://racktables.org and test the "download" link to work.

updating other news feeds

  • Send a letter to the racktables-users list (even more so after Freshmeat/Freecode is gone).
  • Update IRC channel topic

updating demo

  • Produce a helper SQL file for the current release in racktables-contribs.
    • Copy the previous init-full-X.Y.z.sql to current init-full-X.Y.z.sql and git add the new file.
    • Take a clean RackTables instance of the current release (either use demoreload on the previous release or install manually).
    • Make an SQL dump of this new installation like this: mysqldump --extended-insert=FALSE --order-by-primary racktables_db > init-full-X.Y.z.sql
    • Edit permissions like this.
    • git add -i the new file again (note interactive add). Use patch mode to add relevant chunks. Quit.
    • git commit; git push
  • Update demo.racktables.org to the current release ($demorelease will need an update). Below is a sample CLI session of updating the demo to 0.20.3:
cd ~/racktables
git fetch
git checkout RackTables-0.20.3
cd
ln -s racktables RackTables-0.20.3
# the symlink to ~/secret.php is already in wwwroot/inc/
# the symlink to ~/google_analytics.php is already in plugins/
cd ~/racktables-contribs/
git pull
cd
~/racktables-contribs/demo.racktables.org/demoreload.sh 0.20.3 rackdemo
crontab -e
# ../../racktables/wwwroot/index.php is already linked as www/demo/index.php