Spec: Native Installers

Native Installer Proposal

This describes the plans for Bracket's initial pass at implementing native installers. See these users stories: Mac DMG and Win installer. This spec may evolve as we refine the Brackets install experience down the road.

General

• Separate downloads per platform
• Folder structure of the brackets repo part of the installed files is identical to the folder structure in Git.
• Future versions install alongside older versions (they do not update/overwrite the old version). All versions share the same preferences store, but users must manually copy over any extensions they had installed in the older version.
• Uninstalling deletes any extensions the user has installed. (Unless they used ln on Mac, which some extensions do recommend).
• New menu item that opens the extensions/user folder in Finder/Explorer.
• Unlike first launch today, brackets-shell doesn't prompt for the /src folder.
• On first launch, Brackets opens an HTML readme file (instead of opening its own source code, as today). The source code of the HTML file acts as a human-readable intro.
• All text in installer / EULA is localized for French, based on OS locale.

Mac

• Download is a DMG file (disk image) created with the DropDMG tool
• Opening the DMG displays a localized EULA
• All Brackets files are contained in the .app package (so the DMG contains only one item).
• User installs the standard way, dragging the .app onto /Applications. A shortcut and background image in the DMG make this easier.
• The .app package name includes the release number, to ensure it doesn’t overwrite older versions (and any extensions therein) -- see bullet above.
• Uninstalling works the usual Mac way: just drag the .app out of /Applications into the trash. The preferences store (which lies outside the .app) are not cleaned up, just like most other Mac apps.
• Visual assets required: DMG icon; DMG background image

Win

• Download is an MSI generated with Wix (open-source, XML-driven installer generation technology from Microsoft)
• Installer shows EULA; no other options required
• Adds a Start menu shortcut
• Uninstall via OS Add/Remove Programs dialog. Removes shortcut and entire install folder.
• Installed folder structure is similar to today's ZIP distros
• Users will get a UAC prompt when manually dragging files into the extensions folder, and extension source code will not be editable in situ (due to permissions).
• Visual assets required: ~493x312 px dialog background for first/last installer pagers (all but the leftmost ~150px must be solid white); and ~493x58 px banner background for intermediate installer pages

Out of scope / future

• Installer/app is not signed
  • On Mountain Lion, users will be unable to run Brackets without changing an OS setting or performing a one-time workaround (right-click, choose Open, confirm warning dialog).
  • On Windows, users will see a slightly more prominent warning dialog than usual at install time.
  • Both of these issues exist with our current plain-ZIP distros too -- not installer-specific.
• Extensions will be located in the install folder. In the future, we should use a user-specific folder.
• Installer built from raw source code (no additional build/merge steps)
• Brackets will not warn users if run directly out of the DMG (on Mac). Some apps do this, or even offer to automatically copy themselves to /Applications.
• No rigorous build/version numbering required -- custom name/location for each release is enough. (May be needed for the update notification feature, however).