Guide: Automagically package and publish addons
This guide has been deprecated in favour of GitHub Actions, as it's more integrated and (honestly) easier to set up.
A full guide is provided on the wiki for the packager itself. Direct link: https://github.com/BigWigsMods/packa...tions-workflow
Any seasoned developer will agree that automating repetitive tasks is a good idea,
and one of the most repetitive things we do as addon developers is publishing addon updates.
This guide will instruct you how you can automate packaging and publishing new releases,
so you can focus more on developing the addon itself.
With this tool, addons can be published at the two major addon sites; CurseForge/WoWAce (and thus Curse), and WoWInterface.
Addons can also be published (packaged) on GitHub in case you'd also want that.
To do this we're going to rely on a few tools.
You've probably already heard of Git, it's basically a tool to keep track of changes done to
your project's code, among other things.
If you've heard of (or used) Git, you've probably also heard of (and used) GitHub,
an online service that lets you host your Git repositories in the cloud.
But you've probably not heard of Travis CI, it's a tool exclusively made for GitHub that lets developers run
automated tests on their code. We'll be using this to package and release our addon(s).
Last but not least there is the BigWigs packager script which will do all of the actual work for us.
These tools combined will automatically do everything you would normally do when publishing
a new version for your addon(s), such as increasing the Version field in your TOC file,
fetching localization, embedding libraries and more, then finally zip everything and publish.
How it works
After the setup (see the next two posts), the following happens:
So, all you have to do (once set up) is to push to GitHub with a tag, like so:
git tag -am "Tag v2.0" v2.0 && git push origin master --tags
I'm not going into how to use Git and GitHub, there are plenty of guides that will explain that
better than I can do here, so I'm going to focus on the specifics for the actual packaging tools;
Travis CI and the packager script.
Sidenote: You don't have to use GitHub and Travis CI, you could just as well just run the script locally,
or use it with other CI tools for GitLab or Bitbucket, but this guide focuses on GitHub and Travis CI.
Travis CI Setup
Visit the Travis CI website and log in by authenticating it with GitHub.
Once authenticated you can visit your profile page where you'll find a list of all your repositories on GitHub.
To enable Travis CI for a project, find it in this list, then "Settings" button next to it.
In here you'll want to make sure only "Build pushed branches" is enabled, like so:
Further down on this page you'll find a section called "Environment Variables", here you'll
enter your credentials for each site you want your addons to be released at.
Here's a list of what to put in the "Name" and "Value" boxes:
Here's an example:
Once that's set up you'll need to create a ".travis.yml" file in the root of your repository,
right next to your TOC file. The naming of this file is crucial, as well as this content:
All this file does is letting Travis CI know what to do;
Install the required software, download the packager script and run it.
The only thing you need to keep in mind here is the "branches" part.
This will make sure that Travis CI only runs when there is a new tag.
It checks this by looking at the name of the branch (tags are techically branches),
then uses regular expressions to match it against your versioning schema.
You'll most likely need to tweak this to your own versioning schema, reply and I'll assist you.
And that's it for the Travis CI part!
Customizing the packaging
This part is specifically for instructing the packager on how to package your addon, and
where it should upload to.
You'll need to add additional fields to your addon's TOC file, this will let the packager know
where to upload your packaged addon to. You do this by finding the appropriate "IDs" for
the various supported sites and adding them to the TOC file.
The WoWInterface ID is easy to find, it's in the URL for your addon.
E.g. "22213" in wowinterface.com/downloads/info22213-BonusRollPreview.
For CurseForge you'll find it as "Project ID" under "About This Project" on the project page.
E.g. "54902" for wow.curseforge.com/projects/bonusrollpreview.
Add the ones you want to release on to the TOC file with their respective field names,
here's an example:
This file will deal with additional (all optional) things you'd like the packager to do to your
packaged addon, be it embedding external libraries, creating changelogs automatically, etc.
This is all done in a new file named ".pkgmeta" which needs to be located
at the root of your addon, next to the TOC file.
Here's a link to documentation on what you can include in this file:
An example where I specify some libraries it should include:
In addition to this file, additional substitutions can be done to your addon's files (not just the TOC file),
such as filling in the Version field in the TOC file to your latest tag, inserting
localizations from CurseForge, and much more.
More info: https://authors.curseforge.com/knowl...-substitutions
I personally always use the automatic versioning, so my TOC file looks something like this (note the version field):
And that's it! Now you can tag and push to GitHub and the packager will do everything else!
If you're having trouble making the .pkgmeta and .travis.yml files, do the following:
1. Open up a terminal (e.g. Git Bash on Windows) in the root directory for your addon.
2. Type/paste in the following:
touch .pkgmeta .travis.ymlWindows is kind of backwards when it comes to naming files, this solves that.
Nice, i was recently thinking about doing this, i just wasn't sure if this is even properly possible atm without hacks or not. Definitely gonna try it later.
I've a question regarding the Travis CI part:
I already have a simple travis.yml (based on https://github.com/WeakAuras/WeakAur...er/.travis.yml), all it does is run luacheck to catch any syntax errors if I forgot to run my offline build tools (which should be done automatically, but I haven't gotten around to that yet).
Can I just add the relevant parts to it without adding the "language: c" part, or must I add it for this script to work? Will it interfere with the execution if I do add it? Basically, I would want to combine the two to run the syntax check first and then deploy the file.
Also, for the regular expression:
My tags are usually named rXX-(alpha|beta)?(-YY), such as r21-beta-3 or r25-alpha or simply r27/r27-2/etc. (a release version). This was mostly so that Curse can detect the alpha/beta/release state properly, as I'm using their API via GitHub webhooks.
The packager script apparently would consider all of them beta, and worse still, package untagged commits as alpha versions when they aren't ready for deployment at all. Now, I think the branches option would filter out the untagged commits, but how do I have the script package as alpha/beta/release correctly without forking/modifying it or changing my versioning scheme? Maybe Travis could detect them and rename it before calling the script?
and the "default" language is (afaik) Ruby.
There is a "language: generic" that I'd prefer to use, but it's not documented so I'm staying away from using it.
You can add multiple scripts, but I'd recommend you use "after_script: " for the packager, to make sure that luacheck finishes first.
If the Git push was not a tag, it'll default to alpha.
If the Git push was a tag, it'll check if the version matches "1.2.3" or "v1.2.3" or has the word "release" in it, if not it'll be flagged as beta.
So, without modifying the script, your normal pushes will always be alpha, and your "releases" will be beta.
I'd recommend you fork the packager on GitHub, make the changes to match your versioning, then use that instead for the "after_script: ".
An alternative would be to apply a patch to the script before running it.
Something like this would do:
Thanks for your reply. That is the exact same portion I was looking at earlier, and I don't really want to fork it unless I have to as that means I need to pull changes in to keep it updated... and I'm lazy :P
I have literally no clue how to use Travis or just bash scripts in it, and even after trying various things and googling a lot I can't seem to get it to accept the "patch" you posted as a valid parameter in my after_script block.
This is the best that I've got, though no matter what, none of the block indicators I found seems to work: GitHub gist for the invalid .travis.yml file
Right now the error message is
Some issues with your yml file:
- You're ignoring the whitespace requirements of YAML (not really your fault, YAML is anal)
- You're running the "patch" before the release script is even downloaded
- You're attempting to start curl with "/curl", this is not WoW :P
- There's BBCode in the curl line (that's this forums fault for parsing links in code snippets)
- Incorrect syntax for the branch expression
I created a patch file:
And fixed your yml file, using that patch file:
The major difference here (apart from the syntax errors here and there) is this:
- It downloads the release script and saves it to disk, instead of piping it directly into bash (like in the guide)
- It downloads and applies the patch (linked above)
- Lastly, it runs the script
Wow, thank you so much! I really have no clue what I'm doing. I just tried to somehow make it work with the info this guide gives and my very limited knowledge.
I forked your gist to have a backup of it in case you want to delete it, but otherwise I can just have Travis download yours if you don't mind?
The build completed successfully now, but I don't think the release script is doing what it should... yet. All it did was create a GitHub release (for my alpha file, no less...), which isn't ideal. It also skipped the localization and there was no mention of uploading anything to WOWI at all. This is the build log: Travis-CI.org
I'm sure I am still missing something, but from what I see the whole point of using it over the CurseForge + GitHub webhooks solution is to have WOWI included. So far my addons have only been on Curse, but I've updated a smaller addon yesterday to see if I could get it to work. CurseForge has not received any update (do I still need the old webhook?) and I'm not sure how the process works here.
That's the only way (aside from arguments to the script directly, not very portable) the script will know which addon on their respective sites will be updated (aside from GitHub which already knows the repo).
Also notice the last part in the 3rd post, it will automagically update the version field in your TOC file also.
Everything seems to have worked now. Thank you! I should be able to use the same approach to upload my other addons here as well.
I am aware of the version substitution, but I had not added it to that specific addon yet.
I found an issue in the release.sh script.
From the old times of svn, we could directly refer to a subdirectory inside an external library. This survived ad is managed byt the curse packager but not from release.sh.
Here is the example
fatal: repository 'https://github.com/alarofrunetotem/LibInit.git/LibInit/' not found
Actually, the right behavious would be:
Uploading to WowAce
Thank you for this detailled guide, I managed to set it up smoothly!
The packager script, however, does not upload to WowAce (and thus CurseForge). When looking at the script, it specifically checks whether the project_page is curseforge. In my case, however, it is a WowAce project page.
Is it possible at all to upload to WowAce?
Thank you p3lim for this guide. I have implemented this for my add-ons and (after a few trials and errors) it's working great.
Do you know if there is a way to provide CurseForge with the supported version? Right now, every build uploaded to CurseForge is flagged for 8.0 and I have to go and manually replace the flag for 7.3.5. It would be really great if there was a way to read the .toc files and use the interface version number to flag the build on CurseForge correctly.
|All times are GMT -6. The time now is 05:44 PM.|
vBulletin © 2020, Jelsoft Enterprises Ltd
© 2004 - 2020 MMOUI