HOWTO/release.txt

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