HOWTO/release.txt

   1 This document covers how to prepare major releases of SCons--that is,
   2 releases numbered with X.Y format, such as 0.93, 1.0, etc.
   3
   4 If you need to prepare a specific subrelease (X.Y.Z, such as 0.94.1),
   5 then see the document HOWTO/subrelease.txt.
   6
   7 Things to do to release a new X.Y version of SCons:
   8
   9         Prepare the describe-the-release section for the announcements
  10
  11                 summarize changes from src/CHANGES.txt
  12
  13                 template is below, search for "describe-the-release"
  14
  15                 send this out for review while you get the rest of the
  16                 release ready!
  17
  18         Build and test candidate packages
  19
  20                 test on Linux
  21
  22                 test on Windows NT
  23
  24                         1) tar zxf scons-src-{version}.tar.gz
  25                            cd scons-src-{version}
  26                            python runtest.py -a
  27
  28                         2) tar zxf scons-{version}.tar.gz
  29                            cd scons-{version}
  30                            python setup.py install
  31                            cd scons-src-{version}
  32                            python runtest.py -a -X -x C:\Python20\scons.bat
  33
  34                         3) scons-{verson}.win32.exe
  35                            cd scons-src-{version}
  36                            python runtest.py -a -X -x C:\Python20\scons.bat
  37
  38                         4) mkdir temporary_directory
  39                            cd temporary_directory
  40                            tar zxf scons-local-{version}.tar.gz
  41                            cd scons-src-{version}
  42                            python runtest.py -a -x C:\temporary_directory\scons.py
  43
  44                 Checkin any changes necessary to make everything work
  45
  46         END THE CURRENT DEVELOPMENT BRANCH
  47
  48                 ae_p scons.0
  49
  50                 aede {95}
  51
  52                 aerpass {95}
  53
  54                 aeib {95}
  55
  56                 aeb
  57
  58                 aet
  59
  60                 aet -reg
  61
  62                 aed
  63
  64                 aeipass
  65
  66         START THE NEW BRANCH FOR RELEASE
  67
  68                 aenbr -p scons.0 {96}
  69
  70                 aenc -p scons.0.{96}
  71
  72                         Call it something like,
  73                         "Initialize the new branch for release."
  74                         Cause = internal_enhancement.
  75                         Exempt it from all tests (*_exempt = true).
  76
  77                 ae_p scons.0.{96}
  78
  79                 aedb 100
  80
  81                 aecd
  82
  83                 # Change the hard-coded package version numbers
  84                 # in the following files.
  85                 aecp README
  86                 vi README
  87
  88                 aecp SConstruct
  89                 vi SConstruct
  90
  91                 aecp rpm/scons.spec.in
  92                 vi rpm/scons.spec.in
  93
  94                 aecp src/setupTests.py
  95                 vi src/setupTests.py
  96
  97                 # Read through and update the README files if necessary
  98                 [optional] aecp README
  99                 [optional] vi README
 100
 101                 [optional] aecp src/README.txt
 102                 [optional] vi src/README.txt
 103
 104                 # Prepare src/CHANGES.txt
 105                 aecp src/CHANGES.txt
 106                 vi src/CHANGES.txt
 107
 108                         date -R the latest release
 109
 110                         should be current if this has been updated
 111                         as each change went in.
 112
 113                 # Prepare src/RELEASE.txt
 114                 aecp src/RELEASE.txt
 115                 vi src/RELEASE.txt
 116
 117                         date -R the latest release
 118
 119                         Read through and edit appropriately.
 120
 121                         Can probably keep most of the existing text
 122
 123                         Add any new known problems
 124
 125                 # Prepare debian/changelog
 126                 aecp debian/changelog
 127                 vi debian/changelog
 128
 129                         date -R the latest release
 130
 131                 # Now build and prepare the release itself.
 132                 aeb
 133
 134                 aet -reg
 135
 136                 aed
 137
 138                 aede
 139
 140                 etc.
 141
 142
 143
 144         Read through the FAQ for any updates
 145
 146
 147
 148         Upload the packages to the SourceForge incoming FTP:
 149
 150                 ftp upload.sourceforge.net
 151                 anonymous
 152                 <your email>
 153                 cd incoming
 154                 bin
 155                 put scons-0.{96}-1.noarch.rpm
 156                 put scons-0.{96}-1.src.rpm
 157                 put scons-0.{96}.tar.gz
 158                 put scons-0.{96}.win32.exe
 159                 put scons-0.{96}.zip
 160                 put scons-local-0.{96}.tar.gz
 161                 put scons-local-0.{96}.zip
 162                 put scons-src-0.{96}.tar.gz
 163                 put scons-src-0.{96}.zip
 164                 put scons_0.{96}-1_all.deb
 165
 166         Create the new release at the SourceForge project page:
 167
 168                 Go to the Admin page
 169
 170                 => Edit/Add File Releases
 171
 172                 Package Name:  scons
 173
 174                 => Add Release
 175
 176                 New release name:  0.{96}
 177
 178                 Cut-and-paste or upload the RELEASE.txt file.
 179
 180                 Cut-and-paste or upload the CHANGES.txt file.
 181
 182                 (If you cut-and-paste, check the "Preserve my
 183                 pre-formatted text." box!)
 184
 185                 Click "Submit/Refresh"  (IMPORTANT!)
 186
 187                 Check the SCons files you uploaded
 188
 189                 Click "Add Files and/or Refresh View"
 190
 191                 Edit the file info:
 192
 193                         scons-0.{96}-1.noarch.rpm       Any     .rpm
 194                         scons-0.{96}-1.src.rpm          Any     Source .rpm
 195                         scons-0.{96}.tar.gz             Any     .gz
 196                         scons-0.{96}.win32.exe          i386    .exe (32-bit Windows)
 197                         scons-0.{96}.zip                Any     .zip
 198                         scons_0.{96}-1_all.deb          Any     .deb
 199
 200                 Click "Update/Refresh" for each file; this must be done
 201                 one at a time.
 202
 203                 Check "I'm sure." and click "Send Notice" in the Email
 204                 Release Notice section.
 205
 206
 207                 Go to the Admin page
 208
 209                 => Edit/Add File Releases
 210
 211                 Package Name:  scons-local
 212
 213                 => Add Release
 214
 215                 New release name:  0.{96}
 216
 217                 Cut-and-paste or upload the RELEASE.txt file.
 218
 219                 Cut-and-paste or upload the CHANGES.txt file.
 220
 221                 (If you cut-and-paste, check the "Preserve my
 222                 pre-formatted text." box!)
 223
 224                 Click "Submit/Refresh"  (IMPORTANT!)
 225
 226                 Check the SCons files you uploaded
 227
 228                 Click "Add Files and/or Refresh View"
 229
 230                 Edit the file info:
 231
 232                         scons-local-0.{96}.tar.gz       Any     .gz
 233                         scons-local-0.{96}.zip          Any     .zip
 234
 235                 Click "Update/Refresh" for each file; this must be done
 236                 one at a time.
 237
 238                 Check "I'm sure." and click "Send Notice" in the Email
 239                 Release Notice section.
 240
 241
 242                 Go to the Admin page
 243
 244                 => Edit/Add File Releases
 245
 246                 Package Name:  scons-src
 247
 248                 => Add Release
 249
 250                 New release name:  0.{96}
 251
 252                 Cut-and-paste or upload the RELEASE.txt file.
 253
 254                 Cut-and-paste or upload the CHANGES.txt file.
 255
 256                 (If you cut-and-paste, check the "Preserve my
 257                 pre-formatted text." box!)
 258
 259                 Click "Submit/Refresh"  (IMPORTANT!)
 260
 261                 Check the SCons files you uploaded
 262
 263                 Click "Add Files and/or Refresh View"
 264
 265                 Edit the file info:
 266
 267                         scons-src-0.{96}.tar.gz         Any     .gz
 268                         scons-src-0.{96}.zip            Any     .zip
 269
 270                 Click "Update/Refresh" for each file; this must be done
 271                 one at a time.
 272
 273                 Check "I'm sure." and click "Send Notice" in the Email
 274                 Release Notice section.
 275
 276
 277         Hide release 0.{94} at the SourceForge download page:
 278
 279                 Go to the Admin page
 280
 281                 => Edit/Add File Releases
 282
 283                 Package Name:  scons
 284
 285                 => Edit Releases
 286
 287                 Release Name: 0.{94}
 288
 289                 => Edit This Release
 290
 291                 Status: => Hidden
 292
 293                 Click Submit/Refresh
 294
 295
 296                 Go to the Admin page
 297
 298                 => Edit/Add File Releases
 299
 300                 Package Name:  scons-local
 301
 302                 => Edit Releases
 303
 304                 Release Name: 0.{94}
 305
 306                 => Edit This Release
 307
 308                 Status: => Hidden
 309
 310                 Click Submit/Refresh
 311
 312
 313                 Go to the Admin page
 314
 315                 => Edit/Add File Releases
 316
 317                 Package Name:  scons-src
 318
 319                 => Edit Releases
 320
 321                 Release Name: 0.{94}
 322
 323                 => Edit This Release
 324
 325                 Status: => Hidden
 326
 327                 Click Submit/Refresh
 328
 329
 330
 331         In the Bugs Tracker, add a Group for the new release 0.{94}
 332
 333
 334
 335         Test downloading from the SourceForge project page
 336
 337                 You may need to wait a good bit; they seem to update
 338                 this on half-hour cycles.
 339
 340
 341
 342         Update the web site:
 343
 344                 template:  new version number
 345
 346                 src/index.in:  announcement on the home page
 347
 348                 src/scons-doc.tar.gz:  update
 349
 350                 src/CHANGES.txt:  update
 351
 352         Test downloading from the web site download page
 353
 354
 355
 356         Add news item to the SourceForge project page
 357
 358
 359
 360         Announce to the following mailing lists (template below):
 361
 362                 scons-announce@lists.sourceforge.net
 363                 scons-users@lists.sourceforge.net
 364                 scons-devel@lists.sourceforge.net
 365
 366                         [right away]
 367
 368                 python-announce@python.org
 369
 370                         [right away, it's moderated and will take
 371                         some time to get through]
 372
 373                 linux-announce@news.ornl.gov
 374
 375                         [right away, it's moderated and will take
 376                         some time to get through]
 377
 378                 [optional] cons-discuss@gnu.org
 379
 380                         [only if it's a really big announcement,
 381                         I said we wouldn't bug this list]
 382
 383                 python-list@python.org
 384
 385                         [wait until business hours so the announcement
 386                         hits mailboxes while U.S. workers are active]
 387
 388         Notify Gentoo Linux of the update
 389
 390                 For now, we will do this by entering a bug report, and
 391                 attaching the files in build/gentoo to the report.  Go
 392                 to:
 393
 394                         http://bugs.gentoo.org/
 395
 396                 This requires an account (based on your email address)
 397                 and a certain amount of Bugzilla-based navigation,
 398                 but nothing that's too difficult.
 399
 400                 This is just my best stab at a process that will work
 401                 for Gentoo.  This process may change if the Gentoo
 402                 developers come back and want something submitted in
 403                 some other form.
 404
 405         Notify www.cmtoday.com/contribute.html
 406
 407                 [This guy wants an announcement no more frequently than
 408                 once a month, so save it for a future release if it's
 409                 been too soon since the previous one.]
 410
 411         Notify freshmeat.net
 412
 413                 [Wait until the morning so the announcement hits the
 414                 main freshmeat.net page while people in the U.S. are
 415                 awake and working]
 416
 417
 418
 419         Checkin another change to prepare for development on this branch.
 420
 421                 # Prep the following files to track the changes
 422                 # made during the next development cycle
 423                 aecp src/CHANGES.txt src/RELEASE.txt
 424                 vi src/CHANGES.txt src/RELEASE.txt
 425
 426                 # Optionally, update release numbers in the following:
 427                 [optional] aecp HOWTO/change.txt
 428                 [optional] vi HOWTO/change.txt
 429
 430                 [optional] aecp HOWTO/release.txt
 431                 [optional] vi HOWTO/release.txt
 432
 433
 434
 435
 436 =======================
 437 Template describe-the-release section:
 438
 439 IMPORTANT:  Release 0.95 contains the following interface changes:
 440   - XXX
 441
 442   See the release notes for more information about these changes.
 443
 444 This release adds the following features:
 445   - XXX
 446
 447 The following fixes have been added:
 448   - XXX
 449
 450 Performance has been improved as follows:
 451   - XXX
 452
 453 The following changes have been made to the SCons packaging:
 454   - XXX
 455
 456 The documentation has been improved:
 457   - XXX
 458 =======================
 459 Template scons-devel announcement:
 460
 461 SConspirators--
 462
 463 SCons beta release 0.95 is now available for download.
 464
 465 XXX Template describe-the-release section goes here XXX
 466
 467 Special thanks to XXX, XXX, and XXX for their contributions to this
 468 release.
 469
 470         --SK
 471 =======================
 472 Template scons-users + scons-announce announcement:
 473
 474 Version 0.95 of SCons has been released and is available for download
 475 from the SCons web site:
 476
 477         http://www.scons.org/
 478
 479 Or through the download link at the SCons project page at SourceForge:
 480
 481         http://sourceforge.net/projects/scons/
 482
 483 RPM and Debian packages and a Win32 installer are all available, in
 484 addition to the traditional .tar.gz and .zip files.
 485
 486
 487 WHAT'S NEW IN THIS RELEASE?
 488
 489 XXX Template describe-the-release section goes here XXX
 490
 491
 492 ACKNOWLEDGEMENTS
 493
 494 Special thanks to XXX, XXX, and XXX for their contributions to this
 495 release.
 496
 497 On behalf of the SCons team,
 498
 499         --SK
 500 =======================
 501 Template python-announce, linux-announce and python-list announcement:
 502
 503 SCons is a software construction tool (build tool, or make tool) written
 504 in Python.  It is based on the design which won the Software Carpentry
 505 build tool competition in August 2000.
 506
 507 Version 0.95 of SCons has been released and is available for download
 508 from the SCons web site:
 509
 510         http://www.scons.org/
 511
 512 Or through the download link at the SCons project page at SourceForge:
 513
 514         http://sourceforge.net/projects/scons/
 515
 516 RPM and Debian packages and a Win32 installer are all available, in
 517 addition to the traditional .tar.gz and .zip files.
 518
 519
 520 WHAT'S NEW IN THIS RELEASE?
 521
 522 XXX Template describe-the-release section goes here XXX
 523
 524
 525 ABOUT SCONS
 526
 527 Distinctive features of SCons include:
 528
 529   - a global view of all dependencies; no multiple passes to get
 530     everything built properly
 531   - configuration files are Python scripts, allowing the full use of a
 532     real scripting language to solve difficult build problems
 533   - a modular architecture allows the SCons Build Engine to be
 534     embedded in other Python software
 535   - the ability to scan files for implicit dependencies (#include files);
 536   - improved parallel build (-j) support that provides consistent
 537     build speedup regardless of source tree layout
 538   - use of MD5 signatures to decide if a file has really changed; no
 539     need to "touch" files to fool make that something is up-to-date
 540   - easily extensible through user-defined Builder and Scanner objects
 541   - build actions can be Python code, as well as external commands
 542
 543 An scons-users mailing list is available for those interested in getting
 544 started using SCons.  You can subscribe at:
 545
 546         http://lists.sourceforge.net/lists/listinfo/scons-users
 547
 548 Alternatively, we invite you to subscribe to the low-volume
 549 scons-announce mailing list to receive notification when new versions of
 550 SCons become available:
 551
 552         http://lists.sourceforge.net/lists/listinfo/scons-announce
 553
 554
 555 ACKNOWLEDGEMENTS
 556
 557 Special thanks to XXX, XXX, and XXX for their contributions to this
 558 release.
 559
 560 On behalf of the SCons team,
 561
 562         --SK