-
Notifications
You must be signed in to change notification settings - Fork 305
How to Into Changelog
You may have stumbled upon this page after being directed by someone to look at what things merit changelogs, or perhaps you're being proactive about learning to code. Most likely, you clickied the wiki and this was the least intimidating page to start reading (Yes, git is scary, and even hardened devs have to remember to sacrifice their geese under the new moon). Regardless, you're here to figure out what goes into the changelog.
Requested by basically everyone who knows that this is a thing elsewhere, merry christmas I guess.
🆑
experimental - Adds new github action to automatically update the changelog from merged PR descriptions
/🆑
The parsing might be a little janky because I rarely write python code, but if you include a name on the cl-tag line, it should take that as the author instead of the PR author (the default). Generally speaking, the first word of each line is taken as the changelog tag (If there's just one word on the line, it'll skip the line because that's not a changelog). Full list of valid tags are at the top of the script, and adding more should be fairly straightforward because it's just a dict. The added entries for stuff like Adds will be weird to write with because it'll currently consume the Adds as the changelog tag and make everything else the entry, keep that in mind when writing your logs. Format is as follows
:cl: [Author name (optional)]
[tag] [some combination of [ ,-:]] [Changelog entry]
/:cl:
(Clarification: the some combination of [ ,-:] bit means any string of those separates the tag from the changelog entry)
The tag is consumed by the parser and does not appear in the final entry, so if you make a line containing Adds cats, then the entry would just be cats. The valid tags (And icons they convert to) are as follows:
``
validPrefixes = {
- "fix": 'bugfix',
- "fixes": 'bugfix',
- "bugfix": 'bugfix',
- "wip": 'wip',
- "tweak": 'tweak',
- "tweaks": 'tweak',
- "rsctweak": 'tweak',
- "soundadd": 'soundadd',
- "sounddel": 'sounddel',
- "add": 'rscadd',
- "adds": 'rscadd',
- "rscadd": 'rscadd',
- "del": 'rscdel',
- "dels": 'rscdel',
- "delete": 'rscdel',
- "deletes": 'rscdel',
- "rscdel": 'rscdel',
- "imageadd": 'imageadd',
- "imagedel": 'imagedel',
- "maptweak": 'maptweak',
- "remap": 'maptweak',
- "remaps": 'maptweak',
- "typo": 'spellcheck',
- "spellcheck": 'spellcheck',
- "experimental": 'experiment',
- "experiments": 'experiment',
- "experiment": 'experiment' }
I think that format should also let you write changelogs for multiple authors in a single PR (Which I suppose might be useful for downstreams that don't have a pullbot). Since this runs on PR-closed (And skips unmerged closed PRs) mirrorbots that copy PR descs will also update downstreams with the changelogs without needing to make a separate PR to update the changelog. It will also autoprocess manually-generated .yml files, so if people want to stay old-fashioned they're more than welcome to.
Oh, and I tested this about 50 times trying to get it to work (And since I couldn't get the new script to parse the PR body correctly from CMD, that's 50 pull requests I made). A working run can be seen here: https://github.com/Atermonera/Polaris/actions/runs/438966873 And a skipped run (closed without merge) can be found here: https://github.com/Atermonera/Polaris/actions/runs/438971145
I haven't tested this with incorrectly formatted files, because those are mostly either missing :'s or unescaped ""s inside of an entry. The latter is actually concerning but seeing as its fairly trivial for maintainers to edit PRs (Or not merge a PR until the author fixes such) I think that should be fairly straightforward to deal with.
Now, it's occasionally said (usually by people that don't want to go through the hassle of writing changelogs) that people that really want to be kept up to date on the new changes of the code should just watch the github, since you're able to actually see how the code is changing, and participate more permanently in discussions over balance, sprite changes, mapping stuff, etc.. Now, the latter statement is certainly true when compared to discussions in round or on such platforms as Discord, where people tend to forget conversations within days of having them, and searching for stuff from "I dunno, I think somewhere in December? It's somewhere in there," is generally a waste of everyone's time. But the former isn't necessarily reasonable for Urist McSecurity that's just here to eat donuts, drink coffee, and shoot the occasional space carp. They aren't interested in whatever new toys engineering is getting, or how people are tweaking the tech levels for science to grind. And that's totally ok! But they do need to be informed when their spacesuits are suddenly significantly less fireproof. So if someone doesn't make it painfully obvious to them, they're like to complain about how opaque the development process is, because they never got a say in the matter. Thus, it falls to the developers to try and maintain some sort of changelog that's accessible while playing, and presents the most important changes to the players. And this may be less of an issue with the rise of Discord, since near every server will have their own Discord server, and people that play on a particular server tend to find their way onto that server's Discord, where active coding projects are often discussed, but it's still good etiquette to try and be transparent on this stuff, where possible.
There's a few different methods for generating the changelogs (at least, ones that I can think of):
- A dedicated developer could go through all merged pull requests, and compile a log by hand that summarizes the stuff they feel should be summarized (boring and tedious, even to just compile links to all the merged PRs since a particular date).
- Everyone could edit the single changelog file independently in each and every pull request (Oh gods the conflicts, conflicts everywhere)
- People submit files of a uniform format containing the changelogs with each PR, and then someone, usually dedicated to the task, periodically compiles those files into a proper update (The current system, which uses a python script to parse the .yml files)
- Someone smart makes a bot that can read PR descriptions and then automagically update the changelog file when it has been merged (This has been done, but nobody that complains about how we don't use it has directed us to how to set it up)
Enough blathering, though, odds are you've come here to figure out what you're expected to do with those changelog files! They're fairly straightforward.
The changelog that players see in game is in ~/html/changelog.html, such that ~ is the root directory for the codebase (Note that ~ often represents an actual directory that in most cases should not be where all the code files live).
There's some styling stuff for the changelog in ~/html/changelog.css, but nobody ever touches that file.
There's probably some sort of scripting done in ~/html/changelog.js, but to be honest I've never looked at it so whatever it does, it may be more or less fickle than the mapmerger.
The submitted changelog files live in ~/html/changelogs/, and are usually named something on the order of Urist McCoder - remove_cats.yml.
To make a new changelog, it's generally easiest to copy example.yml, and then rename it with your username and the topic of the changelog, in a very broad (1-3 words) sense.
If you don't name it properly, it's not really a big deal, someone might just squint at it when they're updating the changelog.
If you open up your new changelog file, you'll be greeted by a veritable wall of text.
This wall mostly serves to inform you on what to actually put into the changelog, to comply with the formatting that the python script that parses it.
All lines that start with a # are comments, which the script ignores.
If you screw up the formatting, whoever updates the changelog will have to fix it, and it will usually be a hassle.
So please adhere to the format.
The format, in the most barebones format, which is generally preferred because it's easiest to proofread, is as follows:
author: [Your username, as you wish it to appear in game]
delete-after: True
changes:
- [prefix]: "[Summary]"
There are, notably, two spaces before the hyphen for every change. These two spaces are required, and they cannot be tabs.
The delete-after line isn't strictly required, it just makes the script delete the file once it's been parsed.
In most cases, it skips a bit of bookkeeping.
But when there's errors in the script, it makes fixing those errors just a little bit more of a hassle.
For a list of valid prefixes, see the comments at the top of ~/html/changelogs/example.yml.
The list of valid prefixes, as of 26-Jan-2020, is as follows:
bugfixwipsoundaddsounddelrscaddrscdelimageaddimagedelmaptweakspellcheckexperiment
However, most people only ever really use bugfix, rscadd, and occasionally rscdel in usually changes.
Code that can be described with the wip tag probably shouldn't be merged until it's in a more complete state, subject to the ruling of the current development team.
spellcheck describes changes that don't actually warrant changelogs.
The first thing to add is your username. It's generally best that this be a current username that you actually use in the context of ss13 or coding, because it looks a little strange if people who are known to go by certain usernames use completely different pseudonyms in their changelog entries that are matched with known github usernames by the pull request.
The second thing to add is the summary of your changes.
The summary should be clear on the general nature of the changes. If you increase the power of radioactive emissions, the changelog entry should not indicate that radiation is weaker.
The summary should be itemized in broad strokes, especially according to the prefixes. If you add 15 different chemicals for medical to use, those should be grouped into a single entry. If you change how limb-replacement surgery works, and also change the map layout of the roboticist's surgery table, those should have separate entries.
There are major differences between things that warrant changelogs, and things that do not. Most commonly, changelogs should be made for major front-end changes that the players are likely to encounter. This includes:
- New features (Adding a new food item, adding new guns that the players can access, reworking food flavors to be more flavorful, etc.,)
- Feature tweaks (Changing the engine's atmospherics settings, buffing or nerfing medical gear, bugfixes that modify the function of something, etc.,)
- Mapping changes to the main maps that affect the general layout of an area.
Things that do NOT warrant changelogs:
- Back-end refactors that don't change the functionality of anything, this includes most code optimizations
- POI changes and additions. Players can find those out on their own, the POI system is built around exploration.
- Minor bugfixes, particularly pertaining to runtimes and typos.
- New features that are admin-spawn only
There are, of course, exceptions to the rule. If the person running the script is responsible, they will proofread entries before trying to run the script, to ensure that the script runs successfully on the first try. This also happens to be a natural point at which to correct spelling and grammar, and prune out entries that aren't warranted. Unwarranted entries that the proofreader finds amusing or silly are far less likely to be removed, but they should still accurately describe some sort of change that was made.
Far less likely are you to actually need this information, but it is nonetheless important to the current function of the changelog system.
The script that actually updates the ~/html/changelog.html file from the .yml files lives in ~/tools/GenerateChangelog.
It is written in python, version 2.7.
If you try to use a version of python other than 2.7, the results are undefined, and you may very well set the world on fire.
The tool is simplest to use from a command prompt (cmd on windows).
On Windows:
- With python 2.7 installed and in the current user's PATH environment variable (Which python knows how to do on its own if you used a proper installer), navigate in a cmd window to
~, as it has been used previously in this document. - Run
py .\tools\GenerateChangelog\ss13_genchangelog.py .\html\changelog.html .\html\changelogs - The script will run. If it finds any errors, odds are your work has been ruined. The simplest solution I've found to this situation is to revert the code changes to before you tried to run the script through git, and then correct any errors and try again.
- Commit and push the updated changelog files (basically everything in
~/html)