Skip to content

Data Author Guide

Jump to bottom
Amadeusz Sadowski edited this page Dec 4, 2018 · 11 revisions

Contents

Disclaimer: This tutorial was written long time ago, many versions of GitHub Desktop app ago. Instructions about handling this app may be (and probably are) out of date. Try to adapt! And if you have a second, contribute an update here. :)

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 Data/Roster Editor -> 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!

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 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! Hints for beginners :)
  7. Commit you hard work for community (& yourself).
  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). Explanation: repository is read by the webapp on AppSpot, and then indexed, compressed and served to the end users.
  • 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. 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.
  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 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.

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