Releasing WinMerge

## Creating a WinMerge release

Creating a release means building installer, executable- and source-packages that can be distributed for users. RELEASING IS A TASK WITH BIG RESPONSIBILITY! Making errors mean (lots of) users have non-working WinMerge installations. And users are not happy about that!

### Table of Contents

1. Environment
2. Steps to do a release (without scripts)
3. Using the scripts
4. Calculating checksums

### Environment

Before starting releasing, you must make sure you have all tools available:

1. Executable and libraries build tools are documented in Compiling.html
2. Installer building is explained in readme-InnoSetup.html
3. Manual building is explained in readme-manual.html

If you want to use the Python scripts for making creating release easier you'll need Python version 2.5 or later. The scripts also require Subversion command line binaries.

TortoiseSVN binaries don't work.

### Steps to do a release (without scripts)

There are many steps in creating full release. Doing a release without using the helper scripts may take hours! If you are doing a release for a first time, reserve few hours of time for this...

The list of steps is:

1. Verify that sources are ones you want to build as release.
   1. If you have a pristine copy (no modifications/build files etc) of sources make a copy of them before building etc. You can use this pristine copy as source distribution.
2. Set version numbers:
   1. `Src/Merge.rc` for executables
   2. `ShellExtension/ShellExtension.rc` for Shell Extension
   3. `Docs/Users/Manual/WinMerge_help.xml` for the manual
3. Build executables and libraries (see Compiling instructions)
4. Build manual (see readme-manual.html)
5. Build installer (see readme-InnoSetup.html)
6. Create binary distribution folder:
   1. Copy executables and libraries to distribution folder
   2. Copy manual to `Docs` -subfolder
   3. Copy filter files to `Filters` -subfolder
   4. Copy plugin files to `MergePlugins` -subfolder
7. Create source distribution folder from pristine sources (see 1.1 in the list)
   1. Remove plugin dlls from sources
8. Create packages from binary- and source-folders
9. Create checksums (MD5 or SHA1) from packages and installer
10. Run virus check for all files

### Using the scripts

Since creating the release is quite a tedious and error-prone task, there are couple of scripts helping this task:

- `Tools/Scripts/SetVersions.py` is a script for setting version numbers
- `Tools/Scripts/create_release.py` does many of the tasks of building the release.

When using the `create_release.py` -script the tasks for releasing are:

1. Verify you have sources you want to build
2. Build 64-bit shell extension (script doesn't build it and requires it)
3. Update version numbers into INI file
4. Run the `create_release.py` -script
5. Copy the installer file to release folder (its now created into `/Build` -folder
6. Create checksums (MD5 or SHA1) from packages and installer
7. Run virus check for all files

#### SetVersions.py

The `SetVersions.py` -script is documented in `SetVersions.txt` -file in the same folder. It reads version numbers and files to modify from INI file and sets the version numbers.

Running the script is easy, just give the INI file to use as a parameter.

#### create_release.py

The `create_release.py` -script does much of the releasing work. It does:

1. cleans previous build files from folders
2. sets version number for resources (using `SetVersions.py` -script)
3. updates POT and PO files
4. builds libraries (expat, scew, pcre)
5. builds WinMergeU.exe
6. builds 32-bit ShellExtension target
7. builds user manual
8. builds the InnoSetup installer
9. creates per-version distribution folder
10. exports SVN sources to distribution folder
11. creates binary distribution folder

##### Configuring the script

The `create_release.py` -script is meant to run from command line. Before running the script you may need to modify the configuration variables in the beginning of the script file. Variables to modify are:

- svn_binary: This must be a full path to the SVN command line binaries. TortoiseSVN or other GUI tool binaries DO NOT work.
- vs_path: Points to the root folder of Visual Studio installation.
- innosetup_path: Innosetup installation folder.
- dist_root_folder: Relative path to folder where WinMerge release will be created. The script creates version-specific release folder inside this folder.
- source_location: SVN repository URL from where to export the sources. Can be also 'workspace' if sources are exported from local workspace folder.

### Calculating checksums

Checksums must be calculated and published for all released files. Using checksums downloaders can verify the files are downloaded without erros and more importantly the files are the same files that were published. This very efficiently removes the possibility somebody has modified the files.

It is recommended that SHA-1 checksums are used.

There are several tools that can calculate SHA-1 checksums. One such tool is Checksum Tool.