Difference between revisions of "HOWTO-Release"

From ScummVM :: Wiki
Jump to navigation Jump to search
m (Add another step for new supported engines)
m (Text replacement - "</source>" to "</syntaxhighlight>")
(68 intermediate revisions by 14 users not shown)
Line 2: Line 2:


''This is work in progress and needs to be completed!''
''This is work in progress and needs to be completed!''
All examples are based on 1.7 and 1.7.0 version. Don't forget to adapt with the adequate version.




Line 7: Line 9:
* Making the release plan
* Making the release plan
* Telling people about it, making sure everybody knows what is going on
* Telling people about it, making sure everybody knows what is going on
* Update the lists of files below, adding new engine data files and such


=== Branching for major release ===
* Create a branch for the 1.7.x releases from master, named branch-1-7
** <code>git checkout -b branch-1-7 master</code>
* Increase version on branch-1-7 to 1.7.0pre (using <code>devtools/update-version.pl</code>; see below), and commit
** <code>devtools/update-version.pl 1 7 0 pre</code>
** <code>git commit -m "RELEASE: This is 1.7.0pre" -a</code>
* Create annotated tag desc/1.7.0pre on that commit and push
** <code>git tag -m "Mark 1.7.0pre" desc/1.7.0pre</code>
** <code>git push origin tag desc/1.7.0pre branch-1-7:branch-1-7</code>
* Increase version on master to 1.8.0git, and commit
** <code>git checkout master</code>
** <code>devtools/update-version.pl 1 8 0 git</code>
** <code>git commit -m "RELEASE: This is 1.8.0git" -a</code>
* Create annotated tag desc/1.8.0git on that commit and push
** <code>git tag -m "Mark 1.8.0git" desc/1.8.0git</code>
** <code>git push origin tag desc/1.8.0git master</code>


=== Testing & Branching ===
=== Testing ===
* Ensure ADGF_TESTING/ADGF_UNSTABLE flags are correct for the release.
* Identify release critical (show stopper) bugs and get people to fix them.
* Identify release critical (show stopper) bugs and get people to fix them.
* Identify other important bugs and get people to fix them.
* Identify other important bugs and get people to fix them.
Line 17: Line 37:


=== Preparing the source ===
=== Preparing the source ===
* You have to update the versions in all relevant files. There is a script, <code>tools/update-version.pl</code> meant to help you with this.  It will generate/update the following files:
* Browse 'git log' since the previous release and add all significant changes to the NEWS file
* Make sure the translations.dat file is up to date. This file is automatically generated once per week (on Monday morning) and may need to be updated manually if changes to the translations occurred since the last Monday. Use ''make translations-dat'' to update the file (and then commit it if it was changed).
* You have to update the versions in all relevant files. There is a script, <code>devtools/update-version.pl</code> meant to help you with this.  It will generate/update the following files:
** base/internal_version.h
** base/internal_version.h
** dists/macosx/Info.plist
** dists/macosx/Info.plist
Line 27: Line 49:
** COPYRIGHT
** COPYRIGHT
* Review the following port specific files for version updates:
* Review the following port specific files for version updates:
** backends/platform/gp2x/build/README-GP2X
** backends/platform/ps2/README.PS2
** backends/platform/gp2x/build/README-GP2X.html
** backends/platform/ps2/READ_PS2.TXT
** backends/platform/psp/README.PSP
** backends/platform/psp/README.PSP
** backends/platform/symbian/README
** backends/platform/symbian/README
** backends/platform/wince/README-WinCE.txt
** backends/platform/wince/README-WinCE.txt
** backends/platform/ds/arm9/dist/readme_ds.txt
** dists/win32/ScummVM.iss (AppVerName)
* Review the release dates in the following port specific files:
** dists/win32/scummvm.gdf.xml
* Make sure package descriptions are up-to-date:
* Make sure package descriptions are up-to-date:
** dists/redhat/scummvm.spec
** dists/redhat/scummvm.spec
* Make source tarballs, post them in the SF.net FRS.
* Create MSVC project files in the release branch (for example branch-1-7-0, where the tarballs are created from)
** There is a script <code>tools/dist-scummvm.sh</code>, which does this automatically.
** make ideprojects
** git commit -m "DISTS: Generated Code::Blocks and MSVC project files"
** And last but not least don't forget to push the results to our github repo via "git push"
* Make source tarballs, put them in the FRS directory.
** There is a script <code>devtools/dist-scummvm.sh</code>, which creates them automatically.
** Make sure that porters have write access to the release folder on FRS: <code>chmod 775 <folder></code>
* Add version to dists/macosx/scummvm_appcast.xml
 
=== Branching for minor releases ===
* Create a branch for 1.7.0 from branch-1-7, named branch-1-7-0
** <code>git checkout -b branch-1-7-0 branch-1-7</code>
* Increase version on branch-1-7-0 to 1.7.0 and commit, push
** <code>devtools/update-version.pl 1 7 0</code>
** Manually edit backends/platform/maemo/debian/changelog to reflect correct release date for 1.7.0 entry
** <code>git commit -m "RELEASE: This is 1.7.0" -a</code>
** <code>git push origin branch-1-7-0:branch-1-7-0</code>


=== Binaries ===
=== Binaries ===
* Get porters to make binaries.
* Get porters to make binaries.
** Porter must follow our filename convention, which goes like this: "scummvm-VERSION-PORT.EXTENSION". For example: "scummvm-1.0.0-macosx.dmg". Do '''not''' use special names like "EScummVM" or "ScummVMDS". The only exclusion from this requirement is Debian.
** Porter must follow our filename convention, which goes like this: "scummvm-VERSION-PORT.EXTENSION". For example: "scummvm-1.1.0-macosx.dmg". Do '''not''' use special names like "EScummVM" or "ScummVMDS". The only exclusion from this requirement is Debian.
** Porters should pass "--enable-release" to configure in case their port is using the configure/make based build system. If their port is not using the configure/make based build system they should make sure they properly define RELEASE_BUILD when compiling their release binary. It is also noteworthy that "--disable-debug" should be passed in order to remove debugging information from the binary.
** Here is a list of files porters should include in their release archives:
** Here is a list of files porters should include in their release archives:
*** AUTHORS
*** AUTHORS
*** COPYING
*** COPYING
*** COPYING.BSD
*** COPYING.FREEFONT
*** COPYING.LGPL
*** COPYRIGHT
*** COPYRIGHT
*** NEWS
*** NEWS
*** README (generic ScummVM one)
*** README (generic ScummVM one)
*** scummclassic.zip (if your port uses new GUI)
*** localized NEWS and README files (from doc/) (optional)
*** scummmodern.zip (if your port uses new GUI)
*** scummmodern.zip (from gui/themes directory) (if your port uses new GUI)
*** scummclassic.zip (from gui/themes directory) (if your port uses new GUI)
*** translations.dat (from gui/themes directory)
*** pred.dic (from dists directory)
*** pred.dic (from dists directory)
*** access.dat (from dists/engine-data)
*** drascula.dat (from dists/engine-data)
*** hugo.dat (from dists/engine-data)
*** kyra.dat (from dists/engine-data)
*** kyra.dat (from dists/engine-data)
*** lure.dat (from dists/engine-data)
*** mort.dat (from dists/engine-data)
*** neverhood.dat (from dists/engine-data)
*** queen.tbl (from dists/engine-data)
*** queen.tbl (from dists/engine-data)
*** sky.cpt (from dists/engine-data)
*** sky.cpt (from dists/engine-data)
*** lure.dat (from dists/engine-data)
*** teenagent.dat (from dists/engine-data)
*** drascula.dat (from dists/engine-data)
*** tony.dat (from dists/engine-data)
*** toon.dat (from dists/engine-data)
*** wintermute.zip (from dists/engine-data)
 
*** your build binary
*** your build binary
*** your build-specific README (optional)
*** your build-specific README (optional)
*** ...
*** ...
* Porters need to upload binaries at some service and then send the link to the team member managing the release (this should be detailed in the email sent to porters with the links to the tarballs).
* Update the website internally (i.e. update the version in the repository), but do not yet put these changes online.
* Update the website internally (i.e. update the version in the repository), but do not yet put these changes online.
** Edit <code>include/config.inc.php</code> to update the global version.
** Create a new XML file for the new version in <code>data/compatibility/</code>.
** Update <code>data/downloads.xml</code>.
** Add a news item.
** Sparkle automatic updates
*** Create a ReleaseNotes file on FRS with the changes from this release (from NEWS file).
*** Sign the macOS and Win32 binaries with our private key for Sparkle
*** Update the scummvm_appcast.xml file in scummvm/dist/macosx/.
*** Copy the app cast file on the website as appcasts/macosx/release.xml
** Copy over the release files to FRS
*** Set the OS for the newly uploaded binaries (click on the (i) next to each binary).
**** -win32.exe as Windows binary
**** -macosx.dmg as Mac binary
**** .tar.bz2 as Linux, FreeBSD and Other binary
**** -solaris-x86.tar.gz as Solaris binary
=== Tagging a version ===
* When 1.7.0 is ready to be announced, make a permanent v1.7.0 tag in git to mark the release
** <code>git checkout branch-1-7-0</code>
** <code>git tag -m "Tag v1.7.0" v1.7.0</code>
** <code>git push origin tag v1.7.0</code>
* Also increase the version number on the 1.7.x branch to 1.7.1pre
** <code>git checkout branch-1-7</code>
** <code>devtools/update-version.pl 1 7 1 pre</code>
** <code>git commit -m "RELEASE: This is 1.7.1pre" -a</code>
* Create annotated tag desc/1.7.1pre on that commit and push
** <code>git tag -m "Mark 1.7.1pre" desc/1.7.1pre</code>
** <code>git push origin tag desc/1.7.1pre branch-1-7:branch-1-7</code>
=== Creating source tarballs ===
Then you need to create and upload the tarballs.
<syntaxhighlight lang="bash">
devtools/dist-scummvm.sh scummvm 1.9.0
devtools/dist-scummvm.sh scummvm-tools 1.9.0
</syntaxhighlight>
Then upload the resulting scummvm-1.9.0.tar.gz, scummvm-1.9.0.tar.bz2, scummvm-1.9.0.tar.xz and scummvm-1.9.0.tar.zip to the FRS.


=== News & Notification ===
=== News & Notification ===
Write a news blurb (or rather multiple to be used in the following). Usually, you want a bit longer one for the website, a list for Versiontracker, something with proper english sentences for Freshmeat, etc....
Write a news blurb (or rather multiple to be used in the following). Usually, you want a bit longer one for the website, a list for Versiontracker, something with proper english sentences for Freshmeat, etc....


* Write a news item for our website (and as template for news items on other sites).
* Write a news item for our website (also to be used as template for news items on other sites).
* Update documentation page to link to the new README.
* Update link to release notes (on downloads.php) to point to the correct new release notes in the SF.net FRS.
* Update / notify various sites:
* Update / notify various sites:
** Create a SF.net news item (Ender, Fingolfin, Sev, ...)
** Create a SF.net news item
** [http://freshmeat.net/ Freshmeat] (Ender, Fingolfin, ...)
** [http://freecode.com/ Freecode]  
** [http://www.versiontracker.com Versiontracker.com] (Fingolfin)
** Post about the release on our forums
** Update [http://www.heise.de/software/ heise software directory] (Fingolfin)
** ... more ?
** ... more ?
* Put the updated web site online
* Put the updated web site online
* In the File Release System, use the "Notify" feature to make sure everybody who's interested in new releases gets a mail
* Update IRC channel topic


=== Updating the wiki ===
=== Updating the wiki ===
Line 80: Line 170:
* Add the first release field on the info box of the newly supported engines.
* Add the first release field on the info box of the newly supported engines.
* Update [[Platforms]] page if status changed for some of the platforms (e.g. no release for the latest stable version). For these platforms the latest stable version info will also need to be changed if it was using the StableVersion template.
* Update [[Platforms]] page if status changed for some of the platforms (e.g. no release for the latest stable version). For these platforms the latest stable version info will also need to be changed if it was using the StableVersion template.
* Update the support field on the info box of the newly supported games. Also remove these games from ''Unsupported Games'' category.
* Set the ''First Official Version'' field for new platforms.
* Update the support field on the info box of the newly supported games. Also change these games from ''Unsupported Games'' category to ''Supported Games'' category.

Revision as of 15:08, 25 October 2018

How to make a ScummVM release.

This is work in progress and needs to be completed!

All examples are based on 1.7 and 1.7.0 version. Don't forget to adapt with the adequate version.


Preparations

  • Making the release plan
  • Telling people about it, making sure everybody knows what is going on
  • Update the lists of files below, adding new engine data files and such

Branching for major release

  • Create a branch for the 1.7.x releases from master, named branch-1-7
    • git checkout -b branch-1-7 master
  • Increase version on branch-1-7 to 1.7.0pre (using devtools/update-version.pl; see below), and commit
    • devtools/update-version.pl 1 7 0 pre
    • git commit -m "RELEASE: This is 1.7.0pre" -a
  • Create annotated tag desc/1.7.0pre on that commit and push
    • git tag -m "Mark 1.7.0pre" desc/1.7.0pre
    • git push origin tag desc/1.7.0pre branch-1-7:branch-1-7
  • Increase version on master to 1.8.0git, and commit
    • git checkout master
    • devtools/update-version.pl 1 8 0 git
    • git commit -m "RELEASE: This is 1.8.0git" -a
  • Create annotated tag desc/1.8.0git on that commit and push
    • git tag -m "Mark 1.8.0git" desc/1.8.0git
    • git push origin tag desc/1.8.0git master

Testing

  • Ensure ADGF_TESTING/ADGF_UNSTABLE flags are correct for the release.
  • Identify release critical (show stopper) bugs and get people to fix them.
  • Identify other important bugs and get people to fix them.
  • Get even more people to fix all the other bugs, if possible :-).
  • Get people to do lots of testing, possibly by asking for help via a news item.
  • Collect all that information (e.g. in the Wiki). See Release Testing

Preparing the source

  • Browse 'git log' since the previous release and add all significant changes to the NEWS file
  • Make sure the translations.dat file is up to date. This file is automatically generated once per week (on Monday morning) and may need to be updated manually if changes to the translations occurred since the last Monday. Use make translations-dat to update the file (and then commit it if it was changed).
  • You have to update the versions in all relevant files. There is a script, devtools/update-version.pl meant to help you with this. It will generate/update the following files:
    • base/internal_version.h
    • dists/macosx/Info.plist
    • dists/redhat/scummvm.spec
    • dists/scummvm.rc
  • Review the following documentation files for version and copyright year updates:
    • README
    • NEWS
    • COPYRIGHT
  • Review the following port specific files for version updates:
    • backends/platform/ps2/README.PS2
    • backends/platform/psp/README.PSP
    • backends/platform/symbian/README
    • backends/platform/wince/README-WinCE.txt
    • backends/platform/ds/arm9/dist/readme_ds.txt
    • dists/win32/ScummVM.iss (AppVerName)
  • Review the release dates in the following port specific files:
    • dists/win32/scummvm.gdf.xml
  • Make sure package descriptions are up-to-date:
    • dists/redhat/scummvm.spec
  • Create MSVC project files in the release branch (for example branch-1-7-0, where the tarballs are created from)
    • make ideprojects
    • git commit -m "DISTS: Generated Code::Blocks and MSVC project files"
    • And last but not least don't forget to push the results to our github repo via "git push"
  • Make source tarballs, put them in the FRS directory.
    • There is a script devtools/dist-scummvm.sh, which creates them automatically.
    • Make sure that porters have write access to the release folder on FRS: chmod 775 <folder>
  • Add version to dists/macosx/scummvm_appcast.xml

Branching for minor releases

  • Create a branch for 1.7.0 from branch-1-7, named branch-1-7-0
    • git checkout -b branch-1-7-0 branch-1-7
  • Increase version on branch-1-7-0 to 1.7.0 and commit, push
    • devtools/update-version.pl 1 7 0
    • Manually edit backends/platform/maemo/debian/changelog to reflect correct release date for 1.7.0 entry
    • git commit -m "RELEASE: This is 1.7.0" -a
    • git push origin branch-1-7-0:branch-1-7-0

Binaries

  • Get porters to make binaries.
    • Porter must follow our filename convention, which goes like this: "scummvm-VERSION-PORT.EXTENSION". For example: "scummvm-1.1.0-macosx.dmg". Do not use special names like "EScummVM" or "ScummVMDS". The only exclusion from this requirement is Debian.
    • Porters should pass "--enable-release" to configure in case their port is using the configure/make based build system. If their port is not using the configure/make based build system they should make sure they properly define RELEASE_BUILD when compiling their release binary. It is also noteworthy that "--disable-debug" should be passed in order to remove debugging information from the binary.
    • Here is a list of files porters should include in their release archives:
      • AUTHORS
      • COPYING
      • COPYING.BSD
      • COPYING.FREEFONT
      • COPYING.LGPL
      • COPYRIGHT
      • NEWS
      • README (generic ScummVM one)
      • localized NEWS and README files (from doc/) (optional)
      • scummmodern.zip (from gui/themes directory) (if your port uses new GUI)
      • scummclassic.zip (from gui/themes directory) (if your port uses new GUI)
      • translations.dat (from gui/themes directory)
      • pred.dic (from dists directory)
      • access.dat (from dists/engine-data)
      • drascula.dat (from dists/engine-data)
      • hugo.dat (from dists/engine-data)
      • kyra.dat (from dists/engine-data)
      • lure.dat (from dists/engine-data)
      • mort.dat (from dists/engine-data)
      • neverhood.dat (from dists/engine-data)
      • queen.tbl (from dists/engine-data)
      • sky.cpt (from dists/engine-data)
      • teenagent.dat (from dists/engine-data)
      • tony.dat (from dists/engine-data)
      • toon.dat (from dists/engine-data)
      • wintermute.zip (from dists/engine-data)
      • your build binary
      • your build-specific README (optional)
      • ...
  • Porters need to upload binaries at some service and then send the link to the team member managing the release (this should be detailed in the email sent to porters with the links to the tarballs).
  • Update the website internally (i.e. update the version in the repository), but do not yet put these changes online.
    • Edit include/config.inc.php to update the global version.
    • Create a new XML file for the new version in data/compatibility/.
    • Update data/downloads.xml.
    • Add a news item.
    • Sparkle automatic updates
      • Create a ReleaseNotes file on FRS with the changes from this release (from NEWS file).
      • Sign the macOS and Win32 binaries with our private key for Sparkle
      • Update the scummvm_appcast.xml file in scummvm/dist/macosx/.
      • Copy the app cast file on the website as appcasts/macosx/release.xml
    • Copy over the release files to FRS
      • Set the OS for the newly uploaded binaries (click on the (i) next to each binary).
        • -win32.exe as Windows binary
        • -macosx.dmg as Mac binary
        • .tar.bz2 as Linux, FreeBSD and Other binary
        • -solaris-x86.tar.gz as Solaris binary

Tagging a version

  • When 1.7.0 is ready to be announced, make a permanent v1.7.0 tag in git to mark the release
    • git checkout branch-1-7-0
    • git tag -m "Tag v1.7.0" v1.7.0
    • git push origin tag v1.7.0
  • Also increase the version number on the 1.7.x branch to 1.7.1pre
    • git checkout branch-1-7
    • devtools/update-version.pl 1 7 1 pre
    • git commit -m "RELEASE: This is 1.7.1pre" -a
  • Create annotated tag desc/1.7.1pre on that commit and push
    • git tag -m "Mark 1.7.1pre" desc/1.7.1pre
    • git push origin tag desc/1.7.1pre branch-1-7:branch-1-7

Creating source tarballs

Then you need to create and upload the tarballs.

devtools/dist-scummvm.sh scummvm 1.9.0
devtools/dist-scummvm.sh scummvm-tools 1.9.0

Then upload the resulting scummvm-1.9.0.tar.gz, scummvm-1.9.0.tar.bz2, scummvm-1.9.0.tar.xz and scummvm-1.9.0.tar.zip to the FRS.

News & Notification

Write a news blurb (or rather multiple to be used in the following). Usually, you want a bit longer one for the website, a list for Versiontracker, something with proper english sentences for Freshmeat, etc....

  • Write a news item for our website (also to be used as template for news items on other sites).
  • Update / notify various sites:
    • Create a SF.net news item
    • Freecode
    • Post about the release on our forums
    • ... more ?
  • Put the updated web site online
  • Update IRC channel topic

Updating the wiki

  • Update Template:StableVersion. This is used for links to the Compatibility page for the stable version and for the latest stable version info field for each platform.
  • Move newly supported engines in the Complete engines in the latest stable version section on the Engines page.
  • Add the first release field on the info box of the newly supported engines.
  • Update Platforms page if status changed for some of the platforms (e.g. no release for the latest stable version). For these platforms the latest stable version info will also need to be changed if it was using the StableVersion template.
  • Set the First Official Version field for new platforms.
  • Update the support field on the info box of the newly supported games. Also change these games from Unsupported Games category to Supported Games category.