Developer Guide

Contents

• Quick setup
• Development cycle
• Most Common Mistakes
• Releasing
  • How to release
• Auto-updates

Quick setup

We have nice video explaining GitHub Basics for datafiles's development (thanks to Jonskichov).

Here I assume you're a member (not a member?). First:

1. Turn off automatic updates.
   • Why? It's too automated. Might lead to chaos. More...
   • How? BattleScribe Editor (Catalogue or Roster) -> Manage Data -> uncheck "Check for new data files on startup?"
2. Open GitHub app.
3. Open BSData repo list.
   • You have a list on right. There is your profile and all organisations you are member of.
   • Choose BSData.
4. Clone repos.
   • For each repo you want to develop, right-click -> "Clone to..." -> choose "BattleScribe/data" folder.
   • You can find it in BattleScribe -> Manage Data on the bottom: ie. "Data location: C:/Users/Amadeus/BattleScribe/data"
5. Now we can actually start developing!

Development cycle

All these steps are part of our Video Tutorial too. :)

If you're part of our organisation (not a member?), you can directly commit changes. Here's how:

1. Open GitHub app.
2. Open local repo you'll work on.
   • on left side you have "Local" headline. Just under it click "repositories"
   • choose the repo you want to work on
3. Click the cog symbol, "View on GitHub".
   • this will open the webpage of the repository
4. Browse Issues.
   • check out Issue Guidelines
   • use label & milestone filters.
   • choose which one to work on.
   • if you want to do something not already listed, create new Issue
5. Sync
   • click "sync" in upper right corner
   • you really want to work on newest version of file. Believe me.
6. Work! :)
7. Commit you hard work for community (& yourself).
   • check for errors ;)
   • check most common mistakes (and how to avoid them!)
   • click "Uncommited changes" in GitHub app
   • enter summary - mention # of issue you were working on. (ie. Vespids stats updated, #12 or Goblin fix #1234 - that closes Issue right from commit!)
   • click "Commit to master"
8. If you've finished for today, sync. If not, go back to bullet-point 4.
   • only after you click "sync" will your changes be uploaded to GitHub servers

Read on! Then there's the release mechanism.

Most Common Mistakes

• Don't add compressed files (*.gstz, *.catz) - save them as *.gst and *.cat instead (Save as... in Files menu in Editors).
• Don't add index.xml and index.bsi files - so just don't run Data Indexer. This is done automatically by our webpage.
• Don't track (commit/add to repo) backups folder created by BattleScribe - versioning is what git (and GitHub by extension) is all about, so leave it to git to do that job better!
• Don't rename files after they've been released! This causes all sorts of unpleasant experiences for end users; they will take vengeance by drowning you in issues. Advanced: If you really want to, change also catalogue ID and internal name; if updating, they'll end up with two catalogues. They need to know which one is newer. You can also leave the original for few releases (with internal name changed to help users know it has been deprecated).

Actually, what to do: add/commit changes only for README.md, catalogues *.cat and one game system .gst.

Releasing

GitHub repository is one thing, but publishing is another. People with auto-update link download the so-called latest release. That is a tagged version, a moment in commit history. After release, all further changes are on top of that, and will be included in next release.

How to release

So you've decided the new version of repo is ready to be published. Now:

1. Go to home page of your repo. ie. in GitHub app open repo, click upper right cog, "View on GitHub".
2. In a single line you have numbers of "commits", "branches", "releases" and "contributors" Click releases
3. There you see last releases. Click "Draft a new release".
4. Tag your version. Our convention:
   • v3.5.12 will be for third general revision (big changes), after fifth update (ie. new Catalogue etc), and we (community) have made twelve little bug-fixes since then.
   • first number won't change often. It will change when new Rulebook comes out, or we add entirely new something for everyone
   • second number will change whenever you decide the release involves more than bug-fixes and little improvements.
   • third shall be changed most often. Don't be scared, release doesn't cost you anything besides a minute.
   • of course after changing first or second number, further numbers are zeroed. So if new file was added after v6.15.8, we call our's v6.16.0.
5. Enter title. Say what generally changed.
6. If you feel like detailing, why not.
7. Publish release.

More info on inner workings: bsdata/#7

Auto-updates

You can turn on updates for games you don't develop for, because each game has it's own folder. So just subsribe to them. But make sure these repos don't contains files for game system you develop for - that will, again, lead to chaos. Seriously.

Next up: Catalogue Naming Convention