Wiki Team Hub

From BTAWiki
Jump to navigation Jump to search

Introduction

Welcome to BTA Wiki Team. Here you'll find guides to how to edit various bits, as well as Feature Requests for wiki functionality. If you're new, don't worry about the latter and just familiarize yourself with the guides.

Terminology

  • bta-importer: bulk data importer that works with Cargo and the mysql db underlying MediaWiki. Currently does the majority of big data work.
  • Special pages: Unsearchable pages that only show up in the search bar with their exact title.
  • RawData: Special pages used by Cargo for queries. Do not edit.
  • Module: Special pages written in Lua that provide scripting functionality to MediaWiki. Hateful, like Lua. Do not edit.
  • Template: Special pages that provide re-usable blocks of text. Can call modules for extended scripting. Safe to edit, but write a test template first so you don't accidentally rewrite 10,000 pages at once with bad code.
  • LoM: List of Mechs. Bigass list page that's a nightmare to edit manually. Fulmir's problem now.
  • Cache purge: Button under "More" on most pages, refreshes all links, templates and module calls. Can also refer to an automated process via the bta-importer that does that against all mech pages.

Organization of Work

Currently all work is managed via pinned Google Sheets in #wiki-work. Called "Marathons" because they're not sprints and are sometimes enormous batches of work that you just plug away at until done. Don't burn yourself out! It is normally named for the month the update dropped.

Sheet Organization

Sheets Example

In order of Priority for tackling things:

  • 16.5: Current BTA version. This contains the meat of the work - Mech Updates. See the #Mech_Updates_Organization below for details.
    • We only concerns ourselves with BTA Classic, not light, because the Wiki only concerns itself with BTA Classic. All hotfixes are rolled up under the minor version.
  • Other Tabs: Here shown as Royal Fixes & Factory Updates, these are longer/time consuming projects to update non-automated work.
  • BD's Double Check List: Systemic issues we uncover that BD should answer/address. These are either issues that we can trace back to imported RawData like stat/description mismatches, things we surface from wiki updates like missing Affinities, or questions on how we should be presenting data.
    • This is frequently treated as a direct line to BD for non-critical issues (which, to be clear, is what most issues are) and so we don't ping him constantly. You're trusted to ask honest questions and not, say, provide balancing opinions.
    • Example: "Improved LRM 20 has the same slot size as regular LRM 20 (not sure if intended)" is a fair thing to raise. "Improved LRM 20 should have a smaller slot size than LRM 20" is not.
  • Other Updates: Updates to smaller non-automated entries. These may have a priority assigned to them within the section. Frequently come with links to code or Discord discussion
    • Example: Update Mech Quirks List
  • Info Tidbits to Add: Extra information that can be useful to players.
    • Please note that in order to avoid players arguing with BD over coding choices anything that surfaces under-the-hood mechanics should be written elsewhere (say, in a subsection of your user page) and run past him before being posted on a main page.
      • And also correctness! Sometimes the code doesn't work like you think it does. Don't want egg on your face 😃
    • Example: "How Cluster/multi-projectile ammo works with regular and AoE damage"

Mech Updates Organization

The sheet has automatic coloring that updates the colors based on the status of the work. The process is generally as follows:

  1. The wiki importer is run - this can be time consuming and someone will update in #wiki-work when its done.
  2. The list is generated based on #Getting_Changed_Files_From_BTA_Repo and all statuses returned to N/Not Done
  3. 1 person does all the Loadout pics (so we don't get collisions) - usually Amid
  4. When working on large batches, with multiple people, select a series of mechs you will handle and set them to Claimed (frequently you will want to do all of a certain chassistype)
  5. Within that batch, set your current mech to In-Progress and do the work of #Creating_Mech_Pages
  6. When done with that mech, set it to Tabbed (regardless of whether or not a new page was required - just call it Tabbed)
  7. When the List of Mechs is done (a now-automated progress) the list will be set to Done

Rough Guide to Editing the Wiki

Preface

We've taken a few steps to try and ease the task before you, but there's still some tricky bits to understand. For the most part, following this page will see you through.

Depending on the work in front of the team, you might have a spreadsheet to avoid people stepping on each others toes - 3+ people working on the same table can be a headache. Follow the process on that and we'll minimize collisions.

Now, lets get one thing straight - you almost NEVER want to be adding stuff via the editor. It's a relatively small box. Get a separate text editor, copy in the template you're using or otherwise do your work in there. Then paste it back in at the appropriate spot. Bonus points if your editor has tabs, so you can keep track of multiple files on the go. If you're stuck trying to do something, ask in #wiki-work or if you trust your technical skill and patience, go digging through the MediaWiki docs.

Creating Screenshots

BD provides icons, but we provide loadouts. I just use Steam's screenshot manager because it's the lowest impact on the game and you are going to be moving between skirmish mech bay entries a lot. Either way, rename them as per their variant (i.e. THM-4M.jpg) and upload them using the Upload Wizard. You may want to do it in batches, alongside the mechs you're editing, because there are several steps that require some repetitive work. (Note: Amid, at some point, will try to provide a CLI batch uploader to take the repeat effort out of using the Wizard). You'll need to swear its your work and provide a description.

At that point, they're submitted and available. The Wizard will spit out some helpful data about using them in the wiki that we're gonna ignore because 90% of the work is in templates. Now you can get to editing!

Actually Editing

Some generalities. Tabs and table entries are entered alphabetically, with gladiators appended at the end. For tables, Community Content get their own tables, but are appended in the tabs behind gladiators.

For tables, the length of an entry shouldn't matter, but if you find yourself making looooong columns, ask BD for how he wants it to look.

Creating Mech Pages

If you open an existing mech page, you'll find that it is actually incredibly short. That's because the vast majority of pages are created with templates. Below is really all you need.

<tabs>
<tab name="ABS-2L">
{{AutoInfoboxVariant|ABS-2L}}
===Description===
{{MechDetails|ABS-2L}}


===Bonuses===
{{QuirkEasyToMaintain}}


{{AffinityAgile}}


===Factions===
{{MechFactions|ABS-2L}}

{{LoadoutImage|image=ABS-2L.png}}
</tab>
</tabs>

[[Category:30 Ton Mechs]]
[[Category:Inner Sphere BattleMechs]]
[[Category:Inner Sphere Mechs]]


The "tabs" line initializes the tabbing system and is only needed once. Closing it is done at the bottom of a doc and closes out tabbed information.

Each tab is captured within a "tab" block.

Everything in a "{{ }}" block is a template and its in here that you'll do most of the work. For a new page, copy the above, change the mech name and variant id. For updating pages, copy a "tab" block and change the variant id.

For existing mechs, you will almost always be safe using the same Quirk and Affinity as the rest of the tabs, barring gotchas like Hero Mechs and Gladiators that get an extra quirk. For new mechs, you can find Quirks under a mech's chassisdef, under the FixedEquipment section. Affinity is more difficult to find. In order to do that, you must naviate to the MechAffinity folder and search for the unit's AssemblyVariant i.e. NightChanter via grep or findstr. The Affinity it is found under is the mech's affinity. Most of the time this does not return a result (for chassis matching /differentiation reasons) and you will then need to search for the Mech's PrefabIdentifier instead. This is because AssemblyVariant is used for units that share a PrefabIdentifier with a different mech but have a different Affinity. i.e. the Night Chanter shares a prefab with the crab, so it needs an AssemblyVariant but the Crab gets to use its prefab.

The gotchas here are the images - you may need to change the .png to a .jpg for the loadout. And the AutoInfoboxVariant template goes looking for a .png with the name of the title of the page, which can get hairy. You may need to specifically override it with a |image = FileName.png entry like so:

{{AutoInfoboxVariant|JM6-FB
|image = JagerMech.png
}}

If you need to do some digging to find file names, see the section below about #Finding Mech Images.

If you're uploading new images, say, for loadouts please keep the image size relatively sane. The vast majority of the world is still on 1080p. No 1440p, 4k or ultrawide images please.

Optional Automation for the Above

You can use my script if you've a Unix machine. Go ahead and make a .bat or .ps1 if you want.

Do note that this does not take into account any extra Quirks or extra text you may need for an entry.

Miscellaneous Gotchas

  1. Gladiators use a special faction line on their mech page, go find it and use that instead of the above. Actually, any mech that is ONLY found as a reward or through an event gets that treatment.
  2. On the List of Mechs page, the picture has a px (pixel) value. This is basically resizing it on the fly. 95% of the time, you won't need to touch this, but occasionally something just doesn't play well. The only real fix here is to play with the value until it looks more or less like the others.
  3. Community content mechs get their own table, but exist as tabs in the mech's main page.
  4. RAWDATA editing: here there be dragons, ask Amid or Wulf, if only so the latter can make a backup of the DB.

(DEPRECATED) Creating Faction Pages

18px Warning: This entire section has been deprecated by Fulmir's automated template. It's left up to help with any manual edits that may need to be done, particularly the module descriptions.
Deprecated Process

Faction pages are made from several categories:

  • Infobox
  • Sub-Commands (for major factions)
  • Description
  • Enemy Factions
  • Faction Store Inventory
  • Starting Mechs
  • Faction Mechs

Since all the factions are new, we make BD deal with the Infobox and Description because new factions are probably going to be homebrew. Enemy Factions currently have to be filled out by hand, consult the code at BT Advanced Factions\factions\faction_NAME.json.

The Faction Store Inventory section is the single most complicated bit: in order to get it to work, you need to update the Module Factions page, the Faction Store Table, and then you need to generate a formatted entry for that table.

Starting Mechs simply calls the appropriate Starter template.

Faction Mechs uses the Template and Module below.


Mech Factions Script Overview

Script page: Module:Factions

In short, this script does two things.

factionMechs: This takes in a factionId (ex: Davion, ClanNovaCat, EridaniLightHorse, etc) and outputs a list of mechs, by weight class, fielded by that faction. This is used for faction entries to show all mechs fielded by a faction.

Code Overview
This is fairly simple. It searches the wiki database for mechs that have the given faction in their tags list. Then it defines a function for making links, this function adjusts some specific mech variants slightly so they link to correct pages. Next we create mechList, which will be our final return, and four unordered lists for each weight class of mech. The list elements are then populated based on mech tonnage in a for loop, and finally added to the return div element, which is finally returned.

mechFactions: This takes a mech variant (ex: AS7-D, CP-10-HQ, MAD-5S, etc) and outputs a list of factions that use that mech. This is used on mech pages to list the factions where a given mech variant can be fought. The list is outputted as a collapsible div with a list containing the major factions that field that mech. Any faction with sub-commands will have a further expandable section listing the sub-commands fielding the mech.

Code Overview
This function gets the mech variant given, and then iterates through its tags, tags in factionIdsToNames are deemed to be faction tags and processed further. These faction tags are added to a dictionary of parent tags to child tags. If a tag isn't in spamFactionsToParents then it's added as its own parent. We then create the HTML framework using mediawiki with a parent list element. The dictionary of tags is then gone through in alphabetical order by parent tag. Single tags are just added to the list as individual items, tags with multiple children are added as their own sub-list. The idea here is that the list of parent tags is which parent faction to go fight to acquire a mech, while specific sub-factions are listed under that. Finally the tag is appended to the parent unordered list tag. When all parent factions have been iterated through the list is returned.

(DEPRECATED) Editing List of Mechs

18px Warning: This entire section has been deprecated by Fulmir's automated template. It's left up to help with any manual edits that may need to be done.
Deprecated Process

This... is a little bit more involved. And by a little, I mean a lot. You're going to want the Skirmish Bay open for some of this information, unless you're do maths gud in yer noggin.

Below is a complete entry within a table. Creating a whole new table is rare and beyond the scope of this quick intro.

|rowspan="4"|
[[File:Anubis.png|125px|border|center]]

'''[[Anubis|ANUBIS]]'''

'''Mech Quirk:''' Easy To Maintain

(Fast refits)

[[Pilot Affinities|'''Pilot Affinity:''']] Agile

(Gains 1 bonus evasion on movement)
|ABS-2L
|30t
|Fire Support
|0
|0
|2
|4
|0
|XL
|240
|DHS
|Endo
|Ferro
|None
|16.5t
|25.5t
|8
|12
|0
|-
|ABS-3D
|30t
|Fire Support
|0
|4
|0
|0
|0
|XL
|240
|DHS
|Endo
|Stealth
|None
|16.5t
|25.5t
|8
|12
|0
|-
|ABS-3L
|30t
|Fire Support
|0
|0
|4
|2
|0
|XL
|240
|DHS
|Endo
|Stealth
|None
|16.5t
|25.5t
|8
|12
|0
|-
|ABS-TZ
|30t
|Gladiator
|0
|4
|0
|4
|0
|XL
|240
|DHS
|Endo
|Stealth
|None
|16.5t
|25.5t
|8
|12
|0
|-

See that "rowspan="4"" bit? That is the single most important bit to get right, because it maps to the number of variants each mech will have per "Chassis" column and if its not exact, the table gets real wonky. Increment it by 1 for every variant you add or just make sure it matches the number of variants. Above, the Anubis has 4 variant entries, hence "rowspan="4"".

Where you see "Anubis|ANUBIS" the all caps is the displayed text and the "Anubis" is a dynamically created link

The remaining columns are fairly self-explanatory, but some bear some calling out:

Column Description
Role The big grey striped box in the top-right of loadout pics. Maintain its exact wording is key, particularly for anything comedic.
Hardpoints Do yourself a favour and memorize "BEMSO" and remember that "B" comes after the Role descriptor.
Core Gear With the exception of the engine, core, e-cooling and gyro (i.e. anything in the CT core gear), all non-fixed equipment and armor is stripped to give a free tonnage value. This is the default free tonnage measurement for OmniMechs with locked gear.
Bare All components and armor are stripped. This shows the weight taken up by structure and gives a broader idea of total free tonnage on BattleMechs
Speed Use the values in the mechbay UI, don't bother calculating supercharger/TSM/MASC

Now you just need to learn to map the columns as they appear on the List to how they appear in edit mode. Welcome to Wiki Hell! You're here forever. ☺

Note that the final line ends with "|-", which indicates a new section coming up. The very final section of a table ends in "|}", closing out a block waaayyy at the top that you ideally shouldn't need to worry about.

Finding Mech Images

For cases where an image is just not resolving, you're going to have to go digging. You can do this one of two ways, by going to the File list page or searching via the bar with the prefix "File:". 99% of the time, a file has been misnamed on accident while uploading, which is a quick fix in 99OKFINE 90% of cases - save the image, delete the file and re-upload with a correct name (ignoring the bit about the file already existing or having been uploaded before).

The search bar is helpful for finding, say, a file that has been slightly misnamed or finding the page of a questionable file. On that page you can find its details, and file history, which might point to why its busted.

The File List page is useful for finding a file that's wildly misnamed because you can go through looking for the right picture. You're probably working with newer uploads, so it should be pretty close to the first page. Otherwise, prepare to go back a while.

Updating Images

You can't update images from the bulk file uploader, you must update the image from its page.

It may be preferable to use a new, more descriptive file name and update it where it's needed.

If we get around to updating all the loadouts this might become more of a problem, but for one-offs just do it from the file's page.

Useful Formatting Prefabs

Chunks of markup or wiki code that can be copy-pasted for use elsewhere with little or no tweaking.

Collapsible Section with Title

Creates a collapsible section with a title that will remain visible and bolded. Also shades the background with "toccolours" class on the div. Note that including nowiki within this div seems to break it.

<div class="toccolours mw-collapsible mw-collapsed" style="max-width:1000px;">
<div style="font-weight:bold;line-height:1.6;">'''Found On These 'Mechs: (Click Expand For List)'''</div>
<div class="mw-collapsible-content">

</div></div>

Table of Contents floated right, out of the way of contents

<div id="" class="" style="clear: right; margin: -1em 0 0 10px; float: right; padding: 10px; background: transparent; width: 220px; ">__TOC__</div>

Mechs page template


<tabs>
<tab name="MECHID">
{{AutoInfoboxVariant|MECHID}}
===Description===
{{MechDetails|MECHID}}


===Bonuses===
{{Quirk________________}}


{{Affinity_______________}}


===Factions===
{{MechFactions|MECHID}}


{{LoadoutImage|image=MECHID.jpg}}
</tab>
</tabs>

[[Category:TONNAGE Ton Mechs]]
[[Category:Quad Mechs]]
[[Category:Superheavy Mechs]]
[[Category:Inner Sphere OmniMechs]]
[[Category:Inner Sphere BattleMechs]]
[[Category:Inner Sphere Mechs]]
[[Category:Clan Mechs]]
[[Category:Clan OmniMechs]]
[[Category:Clan BattleMechs]]
[[Category:Sanctuary Worlds BattleMechs]]
[[Category:Sanctuary Worlds Mechs]]

Coding Standards

Current Standards

The wiki currently uses Golang, Lua and C#. Lua we're stuck with because that's MediaWiki's scripting language. The bulk uploader is written in Golang to modularly upload information so that the Cargo extension can... somehow manage a bunch of things for us. And C# was introduced to get around the ugliness and right pain in the ass that is updating the List of Mechs. As it stands, Lua is horrendous to work with, the only full-time dev writes C# and only the devops monkey writes Go. Moving forward, our objective is to build expertise in Lua and Go because

  1. That's what the majority of tooling is currently written in.
  2. The output of that tooling is useful and flexible enough that non-coders can easily use it and play with it.
  3. Lua fucking sucks, but we're stuck with it. Time to ante up.

Further philosophy on why this stack was chosen is semi-confidential but can be found by searching "Jabberwocky" in #wiki-work.

Go Standards

  1. Use Effective Go
  2. Commands are handled by the Cobra library, which is a well-understood, flexible and well-documented library
  3. Logging is currently handled by logrus, but will probably change to a default logger as it doesn't provide anything we need at the moment.

Lua Standards

  1. Iunno, try to make them look like the other Modules?

Future Standards

We have roughly aligned on the goal of abandoning Mediawiki and pursuing a flat-file wiki instead. Coding language and standard discussions will be a part of it, but they will conform to these requirements:

  1. Easy to onboard onto
  2. Easy to run in Continuous Integration
  3. Good, well documented support for outputting Markdown, yaml or whatever the flat-file templating engine requires
  4. Dependency-light
  5. Self-documenting

Tooling Nonsense

Getting Changed Files From BTA Repo

The following commands get the changed files between the <START> commit and the <END> commit, run them through an appropriate regex to get relevant file names, and dump the changed file entries into a text file.

Windows:
git diff --name-only <START> <END> | findstr /i /r /c:"/chassisdef.*\.json" /c:"/mechdef.*\.json" > ChangedMechs.txt
git diff --name-only <START> <END> | findstr /i /r /c:"/vehicledef.*\.json" /c:"/vehiclechassisdef.*\.json" > ChangedVehicles.txt
git diff --name-only <START> <END> | findstr /i /r /c:"/Gear.*\.json" /c:"/emod.*\.json" > ChangedGear.txt
git diff --name-only <START> <END> | findstr /i /r /c:"/weapon_.*\.json" > ChangedWeapons.txt
git diff --name-only <START> <END> | findstr /i /r /c:"/amm.*\.json" > ChangedAmmo.txt
Unix-like:
git diff --name-only <START> <END> | grep -E "/chassisdef.*\.json|/mechdef.*\.json" > ChangedMechs.txt
git diff --name-only <START> <END> | grep -E "/vehicledef.*\.json|/vehiclechassisdef.*\.json" > ChangedVehicles.txt
git diff --name-only <START> <END> | grep -E "/Gear.*\.json|/emod.*\.json" > ChangedGear.txt
git diff --name-only <START> <END> | grep -E "/weapon_.*\.json" > ChangedWeapons.txt
git diff --name-only <START> <END> | grep -E "/amm.*\.json" > ChangedAmmo.txt

Feature Requests

None! See the latest wikisheet for outstanding long-term work.

Tips

  1. Save frequently. This allows for granular rollbacks, a wiki function found in the View history tab at the top right. This is especially useful if you accidentally broke something.
  2. Templates update on a successful save of the game page, so even if you've, say, changed an image name, a page with a link to that image won't necessarily show it until the page is edited and saved again. No changes need be made, just trigger the save button. You would not believe how many things can be solved by this. If a page or tab is giving an error, try that first. Cache purge it baybeeeeee.

Special Pages Not On the Special Pages Page

Category:Pages_with_broken_file_links

Category:Pages_with_script_errors