Skip to content

Data Author Guide

Jump to bottom
Amadeusz Sadowski edited this page Jan 19, 2022 · 11 revisions

Prerequisites

Workspace setup

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

To prepare your desktop for editing datafiles:

  1. Turn off automatic updates in BattleScribe Roster Editor.

    • Why? It's too automated. Might lead to chaos. More about auto update...
    • How? BattleScribe Data/Roster Editor ➡ Manage Data ➡ uncheck "Check for new data files on startup?"

  2. Find out where on your computer are the datafiles located. In the Roster Editor, on the bottom of Manage Data screen you can find your data location (a folder path typically ending in /BattleScribe/data), e.g. "Data location: C:/Users/Amadeusz/BattleScribe/data".

  3. Open GitHub Desktop app.

  4. Clone a repository you'll be contributing to (if you don't have write permissions, read about forking and clone your fork instead):

    • Click Ctrl+Shift+O or File ➡ Clone repository.
    • Filter the list by writing the (first few characters of the) name of the repo.
    • Select the repository you wish to clone.
    • Choose local path where the files will be cloned to. Local path should be %USER%/BattleScribe/data/repo-name.
    • Click Clone.

    image

Issues

Issues is GitHub's great&simple bugtracker. Open Issue list from right panel on main repo page.

It's simple, yet can be great tool.

Mentions

Always mention issue in commit. ie. You've worked on some Guardsmen stats, according to Issue #102 you saw on Issue list.

To simply mention the issue, enter Guardsmen profile update - #102 and it's linked!

If you feel like the issue is fixed/closed, you can close it on Issue's page. There's a button on the bottom.

However if after edit you think it's all to be done for that issue, you can close it directly by mentioning it after fix/fixes/close/closes/see more keywords, ie. Ork profile update, closes #93. Cool, right?

Labels & Milestones

You should use labels to tag issues as bugs or enhancements, or if Issue is a topic for discussion, tag it "question". If you see something that was solved, but a new issue was created, tag it as duplicate, and after commenting with a link to proper issue, close it.

Milestones on the other hand group Issues together. We still discuss how to use them. One way we see it is to create Milestones for each Rulebook generation, for each file created. So Milestones would be titled like Skaven 8th Ed and closed after edition change. But that will depend on actual repo. Check that repo's wiki for actual guidelines.

Development cycle

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

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

  1. Open GitHub app, select the data repository you'll be working on as Current repository.
  2. Go to home page of your repo. (click Ctrl+Shift+G or Repository ➡ View on GitHub).
  3. Browse Issues.
    • use label & milestone filters
    • choose which one to work on
    • if you want to do something not already listed, create a new Issue
  4. Sync
    • click "sync" in upper right corner
    • you really want to work on newest version of file. Believe me.
  5. Work! Hints for beginners :)
  6. Commit your hard work for community (& yourself):
    • check for errors ;)
    • check most common mistakes (and how to avoid them!)
    • check that changed files have their internal revision attribute incremented - otherwise the change won't propagate to the users!
    • 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"
  7. 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][releasing] 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). Explanation: repository is read by the webapp on AppSpot, and then indexed, compressed and served to the end users.

    image

  • 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

For starters, read GitHub Help: Creating Releases.

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

  1. Go to home page of your repo. (From GitHub Desktop, if you have the repo selected, click Ctrl+Shift+G or Repository ➡ View on GitHub).
  2. Click Releases in the right panel.
  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 v6.16.0.
  5. Enter title. Say what generally changed.
  6. If you feel like detailing, why not.
  7. Publish the release.
  8. Wait. ⚠ The AppSpot refreshes its data cache every 12hrs. It means you could wait up to half a day for your release to propagate and be available for BattleScribe's update task. :) 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 subscribe to them. But make sure these repos don't contains files for game system you develop for - that will, again, lead to chaos. Seriously.

Hints for beginners

  • Our (data authors') tool of trade is BattleScribe Data Editor, installed together with BattleScribe Roster Editor on desktops (Windows/mac/Linux)
  • Data Editor loads datafiles into graphical user interface and allows editing them without necessity to edit the actual XML file in some text editor (these files have tens or even hundreds of lines!)
  • You might want to play around with already existing files and look at methods of implementation for various conditions, modifiers etc. Most popular repos are most often a good canditate to look at - pick the one you're at least a little familiar with, so you can reverse-engineer what and why was implemented.
Clone this wiki locally