# App/Setup/Upgrading

From XOWA: the free, open-source, offline wiki application

This article describes the process in upgrading your XOWA program from one release to another.

## Background

XOWA has a rapid release cycle, with a new version coming out every week. For more details, see Help/Release_schedule.

XOWA releases frequently for a few reasons:

- MediaWiki updates frequently: English Wikipedia and all the other Wikimedia wikis use a continuous integration model. These releases tend to come out very quickly with releases as often as every week. See https://www.mediawiki.org/wiki/News for an example of the release schedule
- XOWA is still young: XOWA was only released in 2012-12-31. Although a lot of features have been added since then, there are still a lot of features to be added.
- Frequent release philosophy: I personally prefer having frequent releases as opposed to larger infrequent releases. The former is more manageable, and keeps overall development nimble.

## Upgrade by an xowa_upgrade package

`xowa_upgrade` packages are produced with every release.

### Upgrade process

To upgrade, do the following:

Windows

- Download the "xowa_upgrade" exe for your operating system. For example, if you're on Windows with a 64-bit JVM and upgrading to v2.8.2, you would download xowa_upgrade_windows_64_v2.8.2.1.exe
- Place the .exe in your xowa root directory. For example, if you're running XOWA by using `C:\xowa\xowa_64.exe`, then place xowa_upgrade_windows_64_v2.8.2.1.exe in `C:\xowa` so that the file name is `C:\xowa\xowa_upgrade_windows_64_v2.8.2.1.exe`
- Double-click the "xowa_upgrade.exe". The upgrade is a self-extracting 7-zip exe and will unzip all files and place them in the correct locations. Among other things, you'll have a new xowa.jar file. For example, `C:\xowa\xowa_windows_64.jar` should show a recent date.

Linux / Mac OS X

- Download the "xowa_upgrade" zip for your operating system
- Place the .zip in your xowa root directory. For example, if you're running Mac OS X by using `/Users/your_user_name/xowa/xowa_macosx_64.sh`, then place xowa_upgrade_macosx_64_v2.8.2.1.zip in `/Users/your_user_name/xowa/` so that the file name is `/Users/your_user_name/xowa/xowa_upgrade_macosx_64_v2.8.2.1.zip`
- Extract the files. Note that depending on your unzip program, the file may be placed in a new sub-directory. For example, on Mac OS X, the files will be unzipped to a new folder called `/Users/your_user_name/xowa/xowa_upgrade_macosx_64_v2.8.2.1/`
- Move the files from the extracted folder to the XOWA root folder. Overwrite any files in the process. For example, on Mac OS X, there will be a new file called `/Users/your_user_name/xowa/xowa_upgrade_macosx_64_v2.8.2.1/xowa_macosx_64.jar`. This should be moved to `/Users/your_user_name/xowa/xowa_macosx_64.jar` and overwrite the existing version.

### Upgrade shelf-life of 4 weeks

A given upgrade will only work if your release is within the past 4 weeks. For example:

- You start off with the v2.1.3 application.
- v2.1.4 is released. You can use the v2.1.4 upgrade since your v2.1.3 release is 1 week old
- v2.2.1 is released and you haven't upgraded anything. You can use the v2.2.1 upgrade since your v2.1.3 release is 2 weeks old.
- v2.2.2 is released and you haven't upgraded anything. You can use the v2.2.2 upgrade since your v2.1.3 release is 3 weeks old.
- v2.2.3 is released and you haven't upgraded anything. You can use the v2.2.3 upgrade since your v2.1.3 release is 4 weeks old.
- v2.2.4 is released and you haven't upgraded anything. You can not use the v2.2.4 upgrade since your v2.1.3 release is 5 weeks old. You must get a new application package

Once you upgrade, the 4-week window resets. You can perpetually upgrade XOWA in this fashion. For example:

- You start off with the v2.1.3 application.
- You upgrade when v2.2.3 is released. Your release will now be v2.2.3
- You upgrade again when v2.3.3 is released. Your release will now be v2.3.3
- You upgrade again when v2.4.1 is released. Your release will now be v2.4.1
- And so on...

### Upgrade issues should fallback to xowa_app packages

If you have problems after using an xowa_upgrade package, try upgrading using an xowa_app package. I personally test xowa_app packages on both Windows and Linux for every release and these will always work. In addition, due to the nature of the build script, the application package is always guaranteed to have the latest changes.

## Upgrade by an xowa_app package

You can also upgrade by downloading an xowa_app package and unzipping everything in the xowa root directory. For example:

- Download the "xowa_app" zip for your operating system
- Place the .zip in your xowa root directory. For example, if you're running on Windows 64-bit by using `C:\xowa\windows_64.exe`, then place xowa_app_windows_64_v2.8.2.1.zip in `C:\xowa\windows_64\` so that the file name is `C:\xowa\windows_64\xowa_app_windows_64_v2.8.2.1.zip`
- Extract the files. Note that depending on your unzip program, the file may be placed in a new sub-directory. For example, on Windows 64-bit, the files will be unzipped to a new folder called `C:\xowa\windows_64\xowa_app_windows_64_v2.8.2.1\`
- Move the files from the extracted folder to the XOWA root folder. Overwrite any files in the process. For example, on Windows 64-bit, there will be a new file called `C:\xowa\windows_64\xowa_app_windows_64_v2.8.2.1\xowa_windows_64.jar`. This should be moved to `C:\xowa\windows_64\xowa_windows_64.jar` and overwrite the existing version.

Note that you can always just upgrade using the `xowa_app` package. The `xowa_upgrade` packages are provided because they are generally 5 to 10 times smaller than the application packages.

## Upgrade by an xowa_app package and regenerating the XOWA root directory

You can also do an upgrade by renaming your existing XOWA root directory and unzipping a new app package in the same directory. For example, assuming a Windows system with XOWA in `C:\xowa`

- Rename the `C:\xowa` folder to `C:\xowa-old`
- Download an app package and unzip it to `C:\xowa`
- Move the following directories from `C:\xowa-old` to `C:\xowa`
  - `C:\xowa-old\wiki` to `C:\xowa\wiki`
  - `C:\xowa-old\file` to `C:\xowa\file`
  - `C:\xowa-old\user` to `C:\xowa\user`

This approach is more manual, but is meant as an alternate approach. It's also useful for moving XOWA from one drive to another.

### XOWA

- Main page
- Screenshots
- Video
- Download XOWA
- Download wikis

### Getting started

- Requirements
- Installation
- Simple Wikipedia
- English Wikipedia
- Other Wikipedias

### Android

- Setup
- Video

### Help

- About
- Contents
- Media
- Feedback

### Blog

- Current

### Links

- Wikimedia dumps
- XOWA @ archive.org
- English Wikipedia

### Donate

- archive.org
- Wikipedia