lothar.buchholz/Grichelde
0
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

- restored release script and made adjustments to release process

Browse Source
This commit is contained in:
Lothar Buchholz
2026-11-01 16:34:02 +01:00
parent 8feea49c36
commit 56378f630c
5 changed files with 3639 additions and 49 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.release/README.md
+174 -48
View File
@@ -3,7 +3,7 @@
__release.sh__ generates an addon zip file from a Git, SVN, or Mercurial
checkout.
__release.sh__ works by creating a new project directory (*.release* by
__release.sh__ works by creating a new project directory (`.release` by
default), copying files from the checkout into the project directory, checking
out external repositories then copying their files into the project directory,
then moves subdirectories into the project root. The project directory is then
@@ -20,12 +20,12 @@ since that tag.
For a full example workflow, please check out the [wiki page](https://github.com/BigWigsMods/packager/wiki/GitHub-Actions-workflow).
### Example using [options](#Usage)
### Example using [options](#usage)
```yaml
- uses: BigWigsMods/packager@v1
- uses: BigWigsMods/packager@v2
with:
args: -g classic -m .pkgmeta-classic
args: -p 1234 -w 5678 -a he54k6bL
```
## Customizing the build
@@ -54,9 +54,13 @@ __release.sh__ can read a __.pkgmeta__ file and supports the following
directives. See the [wiki page](https://github.com/BigWigsMods/packager/wiki/Preparing-the-PackageMeta-File)
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.
- *externals* (Git, SVN, Mercurial, and zip archives) Caveats: An external's
.pkgmeta is only parsed for ignore and externals will not have localization
keywords replaced. If zip and the archive holds a single top-level folder, the
contents of that folder are used.
- *ignore*
- *plain-copy*
- *license-output*
- *changelog-title*
- *manual-changelog*
- *move-folders*
@@ -65,6 +69,8 @@ for more info.
uploaded to GitHub and attached to a release. Unlike with the CurseForge
packager, manually uploaded nolib packages will not be used by the client when
users have enabled downloading libraries separately.
- *enable-toc-creation* (defaults to no) Create game type specific TOC files
from your TOC file if you have multiple `## Interface-[Type]:` lines.
- *tools-used*
- *required-dependencies*
- *optional-dependencies*
@@ -82,7 +88,7 @@ You can also use a few directives for WoWInterface uploading.
changelog in Markdown format to BBCode if you have [pandoc](http://pandoc.org/)
installed; otherwise, the manual changelog will be used as-is. If set to `no`
when using a generated changelog, Markdown will be used instead of BBCode.
**Note**: Markdown support is experimental and needs to be requested on a
__Note:__: Markdown support is experimental and needs to be requested on a
per-project basis.
### String replacements
@@ -115,6 +121,10 @@ for more info.
- *@file-timestamp@*
- *@project-timestamp@*
- *@project-version@*
- *@build-date@*
- *@build-date-iso@*
- *@build-date-integer@*
- *@build-timestamp@*
### Build type keywords
@@ -129,10 +139,10 @@ Supported keywords and when the code block will run:
- `debug`: never. Code will only run when using an unpackaged source.
- `do-not-package`: never. Same as `debug` except removed from the packaged
file.
- `no-lib-strip`: _(not supported in Lua files)_ in any build other than a
- `no-lib-strip`: *(not supported in Lua files)* in any build other than a
*nolib* build.
- `retail`,`version-retail`,`version-classic`,`version-bcc`: based on game
version.
- `retail`,`version-retail`,`version-classic`,`version-bcc`,`version-wrath`,
`version-cata`, `version-mists`: based on game version.
`do-not-package` is a bit special. Everything between the tags, including the
tags themselves, will always be removed from the packaged file. This will cause
@@ -142,7 +152,7 @@ Lua files surrounding debugging functions and other code that end users should
never see or execute.
All keywords except `do-not-package` can be prefixed with `non-` to inverse the
logic. When doing this, the keywords should start and end a **block comment**
logic. When doing this, the keywords should start and end a __block comment__
as shown below.
More examples are available on the [wiki page](https://github.com/BigWigsMods/packager/wiki/Repository-Keyword-Substitutions#debug-replacements).
@@ -157,7 +167,7 @@ turn into `--@non-keyword@` and `--@end-non-keyword@`.
#### In XML files
**Note:** XML doesn't allow nested comments so make sure not to nest keywords.
__Note:__ XML doesn't allow nested comments so make sure not to nest keywords.
If you need to nest keywords, you can do so in the TOC instead.
`<!--@keyword@-->` and `<!--@end-keyword@-->`
@@ -172,7 +182,7 @@ 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.
removing a '# ' (note the space) at the beginning of each line in-between.
### Changing the file name
@@ -204,54 +214,145 @@ on the build type:
`{classic}` has some additional magic:
1. It will show as the non-retail build type, so either `-classic` or `-bcc`.
2. It will not be shown if "-classic" or "-bcc" is in the project version.
1. It will show as the non-retail build type, so `-classic`, `-bcc`, `-wrath`,
`-cata`, or `-mists`.
2. It will not be shown if `-classic`, `-bcc`, `-wrath`, `-cata`, or `-mists`
is in the project version (tag).
3. If it is included in the file name (it is by default) and #2 does not apply,
it will also be appended to the file label (i.e., the name shown on
CurseForge).
it will also be appended to the file label (i.e., the name shown in the file
list on CurseForge).
## Building for multiple game versions
__release.sh__ needs to know what version of World of Warcraft the package is
targeting. This is normally automatically detected using the `## Interface:`
line of the addon's TOC file.
__release.sh__ automatically detects what game version(s) the addon supports.
You only need to run a build once and the file will be tagged with the
appropriate versions when uploaded.
If your addon supports both retail and classic in the same branch, you can use
multiple `## Interface-Type:` lines in your TOC file. Only one `## Interface:`
line will be included in the packaged TOC file based on the targeted game
version.
For builds with multiple game types, you won't be able to use [build version keywords](#build-type-keywords)
(e.g., `@version-retail@` ... `@end-version-retail@`) in Lua files for
controlling what code blocks execute based on the build version, you need to
switch to plain old Lua control statements. Fortunately, there are some
[constants](https://warcraft.wiki.gg/wiki/WOW_PROJECT_ID) set by Blizzard you
can use for this. If you use these keywords in XML files, you will have to
reorganize your includes in the appropriate TOC files.
### Multiple Interface values
You can specify multiple interface versions delimited by commas. If you don't
set an interface version that matches the game client, then the addon is flagged
out-of-date.
```toc
## Interface: 90005
## Interface-Retail: 90005
## Interface-Classic: 11306
## Interface-BCC: 20501
## Interface: 11509, 20506, 30405, 38002, 40402, 50504, 120100, 16001
```
You specify what version of the game you're targeting with the `-g` switch. You
can use a specific version (`release.sh -g 1.13.6`) or you can use the game type
(`release.sh -g classic`). Using a game type will set the game version based on
the appropriate TOC `## Interface` value.
The above example would mark an addon compatible with the latest version of all
client flavors and Forever Beta.
You can also set multiple specific versions as a comma delimited list using the
`-g` switch (`release.sh -g 1.13.6,2.5.1,9.0.5`). This will still only build
one package, with the the last version listed used as the target version for
the build.
That said, just because you *can* include a bunch of interface versions doesn't
mean you *should* start adding upcoming versions you haven't tested your addon
against.
**Setting multiple versions is not recommended!** The addon will always be
marked "Out of date" in-game for versions that do not match the TOC interface
value for the last version set. So even if you don't need any special file
processing, it will always be best to run the packager multiple times so the TOC
interface value is correct for each game version.
### Multiple TOC files
You can create [multiple TOC files](https://warcraft.wiki.gg/wiki/TOC_format#Naming),
one for each supported game type, and __release.sh__ will use them to set the
build's game version.
### Single TOC file
Most clients support a variety of directives to allow conditional loading of the
TOC file using [Loading conditions](https://warcraft.wiki.gg/wiki/TOC_format#Loading_conditions)
or each individual listed file with [Inline directives](https://warcraft.wiki.gg/wiki/TOC_format#Inline_directives).
Example from the [wiki](https://warcraft.wiki.gg/wiki/TOC_format) (mash up of
variables, loading conditions, inline directives, and multiple values):
```toc
## Interface: 11509, 20506, 30405, 38002, 40402, 50504, 120100, 16001
## Title: My Cool AddOn
## Title: My Cool AddOn in Classic [AllowLoadGameType classic]
## Notes: My addon is working in [Game].
## AllowLoadGameType: standard, classic
## ExcludeLoadGameType: titan, wrath
# This will load "Mainline\File.lua" or "Classic\File.lua"
# as appropriate for the client.
[Family]\File.lua
# This will load "Standard\File.lua", "Mists\File.lua", "Cata\File.lua", ...
# as appropriate for the client.
[Game]\File.lua
# This will load "Localization\enUS.lua", "Localization\frFR.lua", ...
# as appropriate for the client text locale.
Localization\[TextLocale].lua
# This will only be loaded on Standard (retail).
StandardOnly.lua [AllowLoadGameType standard]
# This will only be loaded on Camelot (forever).
ForeverOnly.lua [AllowLoadGameType camelot][ExcludeLoadGameType standard, classic]
# This will only be loaded in Vanilla or TBC.
VanillaOrTBC.lua [AllowLoadGameType vanilla, tbc]
# This will only be loaded under English or French client locales.
EnglishOrFrenchOnly.lua [AllowLoadTextLocale enUS, frFR]
```
__release.sh__ has provided quality of life features to make packaging an addon
for multiple versions easier, but with the TOC features Blizzard has added, most
of the versioning "magic" (build keywords, splitting, multiple packages) is no
longer necessary!
#### Using TOC file creation (splitting)
__release.sh__ can support multiple game versions with the use of additional
`## Interface-[Type]` lines in your TOC file.
```toc
## Interface: 120100
## Interface-Classic: 11509
## Interface-Mists: 50504
```
When using multiple `## Interface-[Type]` lines in a single TOC file, you
can use the `-S` command line option or add `enable-toc-creation: yes` to your
`.pkgmeta` file to automatically generate game type specific TOC files using
your existing preprocessing logic. The fallback TOC file will use the base
interface value as it's version.
For each `## Interface-[Type]` line, a new TOC file is created. In the above
example, __release.sh__ would create `MyAddon_Vanilla.toc` and
`MyAddon_Mists.toc`, based on `MyAddon.toc` applying each game type's processing
logic and rewriting the interface version and also copy `MyAddon.toc` processed
as retail. You can also not include a fallback TOC file to prevent the addon
from displaying for unsupported versions by not including a base interface
value.
### Single game version
You can specify what version of the game you're targeting with the `-g` switch.
As the game officially supports multiple game versions, manually setting the
version should only be used if you have a specific reason for creating and
uploading multiple packages.
If you specify a single game type (`release.sh -g classic`), the game version
will be set based on the appropriate TOC `## Interface-[Type]` value. You can
also completely override version detection by passing a version number
(`release.sh -g 1.15.9`) or a list of versions (`release.sh -g "5.5.4,1.15.9"`).
## Building locally
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__.
1. Create a `.release` subdirectory in the root of your checkout.
2. Ignore the `.release` subdirectory in your `.gitignore`.
3. Copy __release.sh__ into the `.release` directory.
4. (Optionally) Create a `.env` file in the `.release` directory filled with
your upload secrets. (KEY=value pairs each on a new line)
5. Run __release.sh__.
## Usage
@@ -264,6 +365,7 @@ Usage: release.sh [options]
-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.
-S Create a package supporting multiple game types from a single TOC file.
-u Use Unix line-endings.
-z Skip zip file creation.
-t topdir Set top-level directory of checkout.
@@ -273,20 +375,43 @@ Usage: release.sh [options]
-a wago-id Set the project id used on Wago Addons for uploading. (Use 0 to unset the TOC value)
-g game-version Set the game version to use for uploading.
-m pkgmeta.yaml Set the pkgmeta file to use.
-n package-name Set the package zip file name. Use "-n help" for more info.
-n "{template}" Set the package zip file name and upload label. Use "-n help" for more info.
```
```text
Usage: release.sh -n "{template}"
Set the package zip file name and upload file label. There are several string
substitutions you can use to include version control and build type information in
the file name and upload label.
The default file name is "{package-name}-{project-version}{nolib}{classic}".
The default upload label is "{project-version}{classic}{nolib}".
To set both, separate with a ":", i.e, "{file template}:{label template}".
If either side of the ":" is blank, the default will be used. Not including a ":"
will set the file name template, leaving upload label as default.
Tokens: {package-name}{project-revision}{project-hash}{project-abbreviated-hash}
{project-author}{project-date-iso}{project-date-integer}{project-timestamp}
{project-version}{game-type}{release-type}
Flags: {alpha}{beta}{nolib}{classic}
Tokens are always replaced with their value. Flags are shown prefixed with a dash
depending on the build type.
```
### Uploading
__release.sh__ uses following environment variables for uploading:
- `CF_API_KEY` - a [CurseForge API token](https://wow.curseforge.com/account/api-tokens),
- `CF_API_TOKEN` - a [CurseForge API token](https://authors.curseforge.com/#/settings/api-tokens),
required for the CurseForge API to fetch localization and upload files.
- `WOWI_API_TOKEN` - a [WoWInterface API token](https://www.wowinterface.com/downloads/filecpl.php?action=apitokens),
required for uploading to WoWInterface.
- `WAGO_API_TOKEN` - a [Wago Addons API token](https://addons.wago.io/account/apikeys),
required for uploading to Wago Addons.
- `GITHUB_OAUTH` - a [GitHub personal access token](https://github.com/settings/tokens),
- `GH_API_TOKEN` - a [GitHub personal access token](https://github.com/settings/personal-access-tokens),
required for uploading to GitHub.
__release.sh__ will attempt to load environment variables from a `.env` file in
@@ -300,6 +425,7 @@ environment provided the following are available:
- bash >= 4.3
- awk
- grep
- sed
- curl
- zip