release.sh

release.sh generates an addon zip file from a Git, SVN, or Mercurial checkout.

release.sh works by creating a new project directory, checking out external repositories within the project directory, then copying files from the checkout into the project directory. The project directory is then zipped to create a distributable addon zip file.

release.sh creates the new project directory in the .release subdirectory of the top-level directory of the checkout.

release.sh can also upload your zip file to CurseForge, WoWInterface, and GitHub/GitLab (as a release), but requires jq. See Usage for more info.

release.sh assumes that tags (Git annotated tags and SVN tags) are named for the version numbers for the project. It will identify if the HEAD is tagged and use that as the current version number. It will search back through parent commits for the previous tag and generate a changelog containing the commits since that tag.

release.sh uses the TOC file to determine the package name for the project. You can also set the CurseForge project id (-p) and the WoWInterface addon id (-w) by adding the following to the TOC file:

## X-Curse-Project-ID: 1234
## X-WoWI-ID: 5678

Your CurseForge project id can be found on the addon page in the "About Project" side box. Your WoWInterface addon id is in the url for the addon, eg, the "5678" in https://wowinterface.com/downloads/info5678-MyAddon.

release.sh reads .pkgmeta and supports the following directives. See the wiki page for more info.

externals (Git, SVN, and Mercurial) Caveats: An external's .pkgmeta is only parsed for ignore and externals will not have localization keywords replaced.
ignore
manual-changelog
move-folders
package-as
enable-nolib-creation (defaults to no) Unlike using the Curse packager, manually uploading nolib packages has no affect for client users that choose to download libraries separately.
tools-used
required-dependencies
optional-dependencies
embedded-libraries Note: All externals will be marked as embedded, overriding any manually set relations in the pkgmeta.

You can also use a few directives for WoWInterface uploading.

wowi-archive-previous : yes|no (defaults to yes) Archive the previous release.
wowi-create-changelog : yes|no (defaults to yes) Generate a Git changelog using BBCode that will be set when uploading. A manual changelog will always be used if set in the .pkgmeta. If you have pandoc installed, manual changelogs in Markdown format will be converted to BBCode; otherwise, the manual changelog will be used as-is.

release.sh supports the following repository substitution keywords when copying the files from the checkout into the project directory. See the wiki page for more info.

@localization(locale="locale", format="format", ...)@
- escape-non-ascii
- handle-unlocalized
- handle-subnamespaces="concat"
- key
- namespace
- same-key-is-true
- table-name
@alpha@...@end-alpha@ / @non-alpha@...@end-non-alpha@
@debug@...@end-debug@ / @non-debug@...@end-non-debug@
@do-not-package@...@end-do-not-package@
@no-lib-strip@...@end-no-lib-strip@
@retail@...@end-retail@ / @non-retail@...@end-non-retail@
@file-revision@
@project-revision@
@file-hash@
@project-hash@
@file-abbreviated-hash@
@project-abbreviated-hash@
@file-author@
@project-author@
@file-date-iso@
@project-date-iso@
@file-date-integer@
@project-date-integer@
@file-timestamp@
@project-timestamp@
@project-version@

Build type keywords

alpha, debug, do-not-package, no-lib-strip, and retail are build type keywords and are used to conditionally run a block of code based on the build type with the use of comments.

@do-not-package@ and @end-do-not-package@ are a bit special. Everything between the tags, including the tags themselves, will be removed from the file. This will cause the line numbers of subsequent lines to change, which can result in bug report line numbers not matching the source code. The typical usage is at the end of Lua files surrounding debugging functions and other code that end users should never see or execute.

In Lua files

--@keyword@ and --@end-keyword@
turn into --[===[@keyword and --@end-keyword]===].

--[===[@non-keyword@ and --@end-non-keyword@]===]
turn into --@non-keyword@ and --@end-non-keyword@.

In XML files

 and 
turn into .


turn into  and .

In TOC files

The lines with #@keyword@ and #@end-keyword@ get removed, as well as every line in-between.

The lines with #@non-keyword@ and #@end-non-keyword@ get removed, as well as removing a '# ' at the beginning of each line in-between.

Using release.sh

The recommended way to include release.sh in a project is to:

Create a .release subdirectory in your top-level checkout.
Copy release.sh into the .release directory.
Ignore the .release subdirectory in .gitignore.
Run release.sh.

Using release.sh to build a Classic release

To make use of the @retail@ and @non-retail@ keywords, release.sh needs to know what version of World of Warcraft the package is targeting. This is automatically detected using the ## Interface: line of the addon's TOC file.

If your addon supports both retail and classic in the same branch, you can use keywords in your TOC file to include the appropriate ## Interface: line in the package.

#@retail@
## Interface: 80300
#@end-retail@
#@non-retail@
# ## Interface: 11305
#@end-non-retail@

release.sh will target retail by default. You can change this by passing a different game version as an argument. To target classic this would be release.sh -g 1.13.5.

Usage

Usage: release.sh [-celzdLWHGosui] [-t topdir] [-r releasedir] [-p curse-id] [-w wowi-id] [-j github-slug] [-k gitlab-slug] [-g game-version]
  -c               Skip copying files into the package directory.
  -e               Skip checkout of external repositories.
  -l               Skip @localization@ keyword replacement.
  -z               Skip zip file creation.
  -d               Skip uploading.
  -L               Skip upload to CurseForge.
  -W               Skip upload to WoWInterface.
  -H               Skip upload to GitHub.
  -G               Skip upload to GitLab.
  -o               Keep existing package directory, overwriting its contents.
  -s               Create a stripped-down "nolib" package.
  -u               Use Unix line-endings.
  -i               Don't try to infer GitHub/GitLab URLs from the Git remote URL or each other.
  -t topdir        Set top-level directory of checkout.
  -r releasedir    Set directory containing the package directory. Defaults to "$topdir/.release".
  -p curse-id      Set the project id used on CurseForge for localization and uploading. (Use 0 to unset the TOC value)
  -w wowi-id       Set the addon id used on WoWInterface for uploading. (Use 0 to unset the TOC value)
  -j github-slug   Set the project slug used on GitHub, if different from Git remote URL.
  -k gitlab-slug   Set the project slug used on GitLab, if different from Git remote URL.
  -g game-version  Set the game version to use for CurseForge uploading.
  -m pkgmeta.yaml  Set the pkgmeta file to use.

In addition, the following environmental variables are accepted:

CF_ID - a CurseForge project ID.
CF_API_KEY - a CurseForge API token, required for the CurseForge API to fetch localization and upload files.
WOWI_ID - a WoWInterface addon ID.
WOWI_API_TOKEN - a WoWInterface API token, required for uploading to WoWInterface.
GITHUB_SLUG - a GitHub project slug, if different from Git remote URL.
GITHUB_OAUTH - a GitHub personal access token, required for uploading to GitHub.
GITLAB_SLUG - a GitLab project slug, if different from Git remote URL.
GITLAB_OAUTH - a GitLab personal access token, required for uploading to GitLab.
TRAVIS, TRAVIS_PULL_REQUEST, TRAVIS_BRANCH, TRAVIS_TAG - for usage in Travis CI

release.sh will attempt to load environment variables from a .env file in the topdir or current working directory. You can also edit release.sh and enter the tokens near the top of the file.

shrugal/wow-packager