Shipping your first Windows application

Your program works on your computer.

Excellent.

Unfortunately, that is not quite the same thing as having something you can release.

A release needs to survive outside your development folder. It needs the files it depends on, a sensible version, some documentation, a licence, testing and, usually on Windows, an installer.

This guide joins those jobs together. It does not repeat every detail from the other Developer Central guides. Instead, it gives you an order to do things in and points you to the deeper guides when you need them.

1. Decide what you are actually releasing

Before packaging anything, identify the build you intend to give people.

Do not package whichever copy of the program happens to be sitting on your desktop. Make a deliberate release build and test that build.

If the application has a version number, settle it now. Your first public release does not have to be version 1.0. If the software is still experimental, 0.1 or another pre-1.0 version may describe it perfectly well.

Read Versioning your own software.

2. Get the application out of the development environment

If you already have a normal Windows executable and all of its required files, move on.

If you are starting with Python source code, you normally need to package it before somebody without Python installed can run it.

Accessible Python Executable Builder provides an accessible interface for PyInstaller and Nuitka. It can package the project, its data files, hidden imports and other dependencies into a Windows build.

Whatever tool you use, test the packaged application itself. Running the original Python script proves that your source works. It does not prove that the packaged EXE contains everything it needs.

Try it somewhere boring

A development computer is an unusually forgiving place to test software. It contains your source tree, development tools, environment variables and assorted libraries accumulated over time.

If possible, test the packaged build on another Windows installation or a clean virtual machine. At minimum, move the build away from the source directory and make sure it still starts.

3. Gather the release files

Put together exactly what the installed application needs.

That may include:

• The main EXE.
• DLLs or other runtime files.
• Data files.
• Sounds and images.
• Documentation.
• Licence notices required by software you use.

This is a useful moment to remove development leftovers. Your users probably do not need test data, old builds, temporary files, debug logs or final-final-really-final.txt.

4. Build the installer

For a Windows desktop application, an installer gives you a predictable way to put files in the right place, create shortcuts and remove the application again later.

Accessible Installer Wizard provides an accessible interface for Inno Setup.

A straightforward installer usually needs surprisingly little:

• The application name and version.
• The folder containing the release files.
• The main executable.
• An installation folder.
• A Start menu shortcut.
• Possibly an optional desktop shortcut.

Build that simple installer first. Tasks, components, registry entries, custom sounds and other features are useful when the application genuinely needs them; they are not entrance requirements for releasing software.

Test what gets installed, not what you meant to install

Run the finished Setup EXE. Install the application. Start it using the shortcut the installer created.

Check that the application can find its data files and that files have not accidentally been left pointing at locations on your development computer.

Then uninstall it.

Yes, actually uninstall it. An installer that installs beautifully and leaves half the application behind afterwards is only half finished.

5. Consider code signing

Windows code signing allows an executable to carry a digital signature identifying its publisher and helps show whether the file has changed since it was signed.

It requires a suitable code-signing certificate, so this may not be practical for every first release.

If you do have one, sign the files that need signing and the installer itself. Accessible Installer Wizard can configure signing for the generated installer, uninstaller and individual application files.

If you do not have a certificate, do not invent one, copy somebody else's signing setup or postpone the entire release because the checkbox looks important. Understand the trade-off and make an informed decision.

6. Choose a licence

If other people are going to receive your software, decide what permission you are giving them.

Copyright exists whether or not you remembered to add a licence file. A licence explains what other people may actually do with the work.

Start with Introduction to software licences, then use Choosing a software licence if you are unsure which direction fits the project.

Also check the licences of libraries, assets and other material included with your application. Your own licence does not magically replace theirs.

7. Write the README

The README answers the questions somebody has immediately after discovering your project.

What is it? What does it do? How do I install or run it? What does it require? Where do I report a problem?

Writing a useful README covers the principles, and the Software README template gives you a starting structure.

Write for somebody who was not present while you built the program. They do not know that the mysterious button is obvious once you have spent six months using it.

8. Keep a changelog

A changelog records what changed between releases.

For the first release, this may be wonderfully short. That is fine. The important thing is establishing the habit before version 2.7 arrives and you are reconstructing six months of work from commit messages and increasingly desperate memory.

Read Writing a changelog.

9. Write release notes for this release

A changelog is the ongoing history. Release notes are the message attached to this particular release.

Tell people what matters: what is new, what changed, whether anything breaks compatibility and what known problems remain.

Read Writing useful release notes.

10. Test accessibility as part of release testing

Do not treat accessibility testing as a ceremonial final checkbox after every other decision has been frozen.

At minimum, run through the real tasks with the keyboard. Make sure focus can reach the controls, labels make sense and dialogs put focus somewhere useful.

If the application is intended to work with screen readers, test it with one.

The accessibility path starts with Accessible development, then covers keyboard accessibility, accessible controls and screen-reader testing.

11. Test the release as a stranger would

By now you should have the actual files you intend to publish.

Forget the development project for a moment and test those.

• Download or copy the installer from the same package or location a user will receive it from.
• Run the installer.
• Read what the installer says.
• Launch the application from the installed shortcut.
• Try the main features.
• Check the version shown by the application if it displays one.
• Check the README and other documentation.
• Uninstall the application.

If possible, have somebody else try it. A fresh human being has a remarkable ability to click the one thing you unconsciously stopped seeing three months ago.

Things that bite first-time Windows releases

A clean build and a successful installer prove two things: it built, and the installer ran. Windows still has several opportunities to make you look silly on somebody else's computer.

SmartScreen and antivirus warnings

New or uncommon executables can attract warnings, particularly when they are unsigned or produced by packaging tools that generate executables dynamically. Do not tell users to disable their antivirus as a standard installation step. Investigate the warning, scan the release and understand what is being reported.

Your development machine has things the user's machine does not

A program may quietly depend on a runtime, DLL, environment variable, PATH entry or file that exists only because you develop software on that computer.

This is why testing on another machine or clean virtual machine is so valuable.

Program Files is not your data directory

Do not assume an installed application can casually write changing user data beside its EXE under Program Files. Decide where settings, caches, logs and user-created data belong. Windows provides locations such as AppData for a reason.

Paths contain spaces

Test from an installation path containing spaces. If a command works only when installed to C:\MyApp and falls over in C:\Program Files\My App, you have found a quoting bug before your users do.

Upgrades are different from clean installs

Once you have a previous version, install the new version over it. Check that settings and user data survive when they are supposed to, obsolete files are handled sensibly and shortcuts still point to the right place.

Uninstalling should not eat the user's work

An uninstaller should remove the application. Be extremely careful about deleting folders that may also contain documents, projects, recordings, downloaded material or other user-created data.

Administrator mode can hide mistakes

If you always test while running everything as administrator, permission problems may remain invisible until a normal user installs the application. Test the ordinary path too.

You do not need to solve every theoretical Windows deployment problem before version 1.0. You do need to test the assumptions your application actually makes.

12. Release it

At this point you should know what version you are releasing, what licence applies, what files are being distributed, how the software is installed, what changed and what limitations remain.

That is a release.

Not perfection. Not the end of development. A specific, identifiable version of the software that you have prepared for somebody else to use.

Preparing your first software release provides a shorter checklist you can return to for future releases.

The short version

1. Choose the release version.
2. Create and test the packaged application.
3. Gather only the files the release needs.
4. Build and test the installer.
5. Sign it if appropriate and available to you.
6. Choose and check the licence.
7. Write the README.
8. Update the changelog.
9. Write the release notes.
10. Test keyboard and screen-reader accessibility.
11. Test the actual release package.
12. Ship it.

The first time through, that list can look enormous. After a few releases, most of it becomes routine. That is precisely why it is worth building the routine properly.

Back to Developer Central.