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. Our problem again! Amid will try get a Visual Editor up
  • 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

Current Sheet

Sheets Example

In order of Priority for tackling things:

  • 16.5: Current (example) 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.

Also, don't worry if you break something: using View History you can revert your last edit. No (permanent) harm done!

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>           <!-- Creates the tab structure you see at the top of the page. -->
<tab name="ALC-T0">       <!-- A single tab. 'name' is the text that appears on the tab. -->

                          <!-- This creates the side panel info box for the mech.
                          The {{ }} indicates a template being called, in this case 'AutoInfoboxVariant'
                          The | indicates a break for a new input. The first input for this is the mech variant 'ALC-T0'
                          The following parameter is an override. In this case overriding the 'image' value.
                          The most common properties that need overriding are
                          image
                          speed (formatted as walk/sprint/jump)
                           -- Don't worry too much about these next categories. Just if you catch something that's off.
                          armor - Is as described. Wiki sometimes doesn't factor in stuff like the Royal quirk.
                          structure 
                          heatsinking 
                          alphaheat - the wiki can't do the math for exchangers
                          -->

{{AutoInfoboxVariant|ALC-T0
|image=ErinyesAM.png
}}
===Description===         <!-- Text surrounded by '=' is a header, number of '=' indicates size, fewer is larger heading. -->
{{MechDetails|ALC-T0}}    <!-- Same template structure as above, uses the Variant to get the data. -->


===Bonuses===
                          <!-- Quirks and Affinities just reference specific pages. 
                          Easiest way is to reference a mech with the same quirk or affinity to get the name,
                          or search in the search box with "Template:_____" to find the page. Each starts with Quirk or Affinity
                          so for example "Template:AffinityEv" will show "Template:AffinityEvasive" in the autocomplete. -->
{{QuirkEasyToPilot}}


{{AffinityEvasive}}


===Factions===
{{MechFactions|ALC-T0}}    <!-- Script that shows all factions using the variant. -->


{{LoadoutImage|image=ALC-T0.jpg}}     <!-- Loadout Images are *generally* named <variant>.jpg
                                       Sometimes the page naming rules get annoyed at us, 
                                       and we have to use slightly different names. -->
</tab>
</tabs>

                          <!-- Categories have to be done manually. Generally it's the tonnage category, 
                          then any faction categories. There's a separate category for each factions for
                          BattleMechs vs Omnimechs. If a mech has variants from multiple factions (Inner
                          Sphere and Sanctuary Alliance for example) then all of those are listed on the
                          page. Here are two different sets of Categories for two different mech pages.-->
[[Category:50 Ton Mechs]] 
[[Category:Sanctuary Worlds BattleMechs]]
[[Category:Sanctuary Worlds Mechs]]

[[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, but can generally be pulled from the List of Mechs. If that's not possible then 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.

Editing List of Mechs

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 used to use 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 (this code is now deprecated and replaced by easier to use [AutoTableLine](https://www.bta3062.com/index.php?title=Template:AutoTableLine). As it stands, Lua is horrendous to work with, and the only "developer" is a devops monkey who can kinda write Go and Python. Moving forward, our objective is to build expertise in Lua and Python because

  1. Python is the 3rd most popular language on the planet and so is easy to find contributors for
  2. Python allows us to write very clear, understandable code that eases onboarding for less skilled developers
  3. Lua fucking sucks, but it is the only mediawiki templating language that works in the backend. Time to ante up.
  4. Lua Modules power the templating work that accesses the information stored in the Cargo databases

We maintain the bta-importer in Go because

  1. The output of that tooling is useful and flexible enough that non-coders can easily use it and play with it (via already-written Lua modules)
  2. There's no capacity to re-write it in Python.

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?

Python Standards

  1. Under development, suggestions welcome
  2. Use black to format
  3. Point to standard python peps(?) https://peps.python.org/pep-0008/ and https://peps.python.org/pep-0020/
  4. write tests eventually

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

Coding Resources

This section basically exists as a sets of bookmarks for Amid and/or anyone interested in contributing on the scripting side. Don't hurt your eyes if you're not committed.

https://www.mediawiki.org/wiki/Extension:Scribunto/Lua_reference_manual https://workingwithmediawiki.com/book/chapter12.html https://www.mediawiki.org/wiki/Help:Extension:ParserFunctions https://en.wikipedia.org/wiki/Module:Example

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

wiki scripts repo

Note: needs a Github account and for you to be added to the BTA Org

https://github.com/BattleTech-Advanced-3062/wiki-scripts/tree/main

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.
  1. 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.
  1. Finding Broken Links on a large page: If you're editing a big page and want to find broken links, open up the browser debug (F12 in Chrome) and search in the page source for "page does not exist" and it'll find all the links to pages that don't exist! This will include things like the Discussion Page link at the top, just click past those. If you can't get the "Find" box to appear click in the source code and then hit "Ctrl+F" and a search box should appear within the debug window.

Special Pages Not On the Special Pages Page

Category:Pages_with_broken_file_links

Category:Pages_with_script_errors

Retrieved from "https://www.bta3062.com/index.php?title=Wiki_Team_Hub&oldid=61036"