p3lim/wow-packager repository overview

⁠release.sh

release.sh generates an addon zip file from a Git or SVN 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.

By default, 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 (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 that is a release version number and generate a changelog containing the commits since that previous release 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 CurseForge Knowledge Base 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
• license-output (creates an All Rights Reserved license)
• 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 CurseForge Knowledge Base 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.

Everything between @do-not-package@ and @end-do-not-package@, including the tags themselves, will be removed from the file. This may cause line numbers of subsequent lines to change. 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

<!--@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 TOC files

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

The line 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:

1. Create a .release subdirectory in your top-level checkout.
2. Copy release.sh into the .release directory.
3. Ignore the .release subdirectory in .gitignore.
4. 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: 80200
#@end-retail@
#@non-retail@
# ## Interface: 11302
#@end-non-retail@

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

⁠Usage

Usage: release.sh [-cdelLosuz] [-t topdir] [-r releasedir] [-p curse-id] [-w wowi-id] [-g game-version] [-m pkgmeta.yml]
  -c               Skip copying files into the package directory.
  -d               Skip uploading.
  -e               Skip checkout of external repositories.
  -l               Skip @localization@ keyword replacement.
  -L               Only do @localization@ keyword replacement (skip upload to CurseForge).
  -o               Keep existing package directory, overwriting its contents.
  -s               Create a stripped-down "nolib" package.
  -u               Use Unix line-endings.
  -z               Skip zip file creation.
  -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.
  -w wowi-id       Set the addon id used on WoWInterface for uploading.
  -g game-version  Set the game version to use for CurseForge uploading.
  -m pkgmeta.yaml  Set the pkgmeta file to use.

The following environment variables are necessary for uploading:

• CF_API_KEY - a CurseForge API token⁠, required for the CurseForge API to fetch localization and upload files.
• WOWI_API_TOKEN - a WoWInterface API token⁠, required for uploading to WoWInterface.
• GITHUB_OAUTH - a GitHub personal access token⁠, required for uploading to GitHub.

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. Note that if you use either of these methods of setting the environment variables, you will not be able to override them on the command line.