Changelog tutorial

[Optera]

Can you make it so that either the first tab/category is selected or better yet - have the All category tab first and selected and the rest follow alphabetically ?

And I'd like to +1 the Idea of showing the latest update first and the rest in descending order as is customary in most software change logs you find.

+1 on both
Now that you pointed it out I'll always be bothered by All tab not being the first tab.

[Pi-C]

@Pi-C - I love your post and use it every time I make a change to my mods (bc I don't do that often and always have a parsing problem somewhere with a new entry in the change log file... )

Thanks for the compliment -- and for keeping your changelogs working!

@Devs - I think there is a minor issue with ow the change log is presented in the game interface where the categories are ordered strangely (PSB my example picture):
[snip]

Can you make it so that either the first tab/category is selected or better yet - have the All category tab first and selected and the rest follow alphabetically ?

I'm not a developer, but there is a certain logic to the current layout: Everything before All is an "official" category used by the vanilla game, everything after it is a "custom" category (or a typo, e.g. "Bugfix" instead of "Bugfixes"), so "All" serves as a separator. The "All" tab is selected because you usually want to see everything at once, without having to click on every tab. Perhaps I've just gotten used to the current behavior, but if this would indeed be changed, I'd opt for the second suggestion (All tab first, official and custom categories mixed and following All in alphabetic order).

And I'd like to +1 the Idea of showing the latest update first and the rest in descending order as is customary in most software change logs you find.

Again, I've become used to the current order: When I install a new mod, I don't want to scroll to the bottom, start reading at the last entry and work my way upwards. It's different with updating mods, though: Having to scroll down to get to the latest changes can be a PITA if the changelog is as long as some of my own have become.

Instead of always sorting the entries one way only (be it first to last or last to first), I'd wish for a toggle button so you can sort the entries in whatever way is best for you at the moment. Something like that exists already in the "Install" section, where you can sort mods by name, version, last update etc.

[Schallfalke]

@Devs - I think there is a minor issue with ow the change log is presented in the game interface where the categories are ordered strangely (PSB my example picture):

Change log category order.JPG


Can you make it so that either the first tab/category is selected or better yet - have the All category tab first and selected and the rest follow alphabetically ?

I am not from dev team, but I can answer (partially) your questions.
There is a list of "supported" fields, as listed by Bilka's post on the first page of this thread.

There is some "hard-coded" order of the supported fields, where "All" field is the last one among them.
Any fields not in the list (such as your "Fix" and "To Do") will show after these supported fields.

EDIT: Did not see Pi-C's reply when posting this... But anyway...

[Honktown]

Heh, triggered a very minor "bug":

image

super_minor_bug.png (20.38 KiB) Viewed 4805 times

To stay on topic, any know of a changelog pretty printer, that works for both website and in-game? They have different widths which makes some things awkward, I usually just shorten my lines a bit and gently cascade indentation if I need to (or I'd be eating up a lot of space...). I've never used LaTeX, but I've seen a bit of it. Probably wouldn't mind using something which parsed that into a pretty-printed changelog. I can make a pretty-printer myself, just looking for a "standard" tool (markdown, LaTeX, etc). Don't mind if it's sh, bat, perl, what have you.

[Pi-C]

Heh, triggered a very minor "bug":

Interesting. I'll play around with that later.

To stay on topic, any know of a changelog pretty printer, that works for both website and in-game? They have different widths which makes some things awkward, I usually just shorten my lines a bit and gently cascade indentation if I need to (or I'd be eating up a lot of space...).

Impossible, I'd say! Websites are dynamic stuff, as author of web content, you don't have control about anything while you can control everything for print media. As author of web content, you don't know how big my monitor will be (e.g. huge monitor vs. small smartphone screen), you don't know whether I'll maximize my browser window, whether I'll use zooming or whether I'll overwrite the fonts you've so carefully chosen with a default style that I like. Heck, you can't even be sure I'll use a graphic browser -- perhaps I've just fired up elinks because it takes so long until Firefox has loaded all the tabs. Anyway, believing that you can control what the output in any browser but your own will look like is an illusion.

You have a bit more control with the in-game-viewer, I guess, because Factorio should at least provide the same fonts to everybody. Still, line lengths will vary with screen and window size.

In my opinion, the best thing you can do is conform with the game parser's rules and just forget about how it looks on the mod portal.

[BlueTemplar]

Yeah, one weakness of (Lua)(La)TeX is that (AFAIK) it only outputs to DVI / PostScript / PDF, which, (AFAIK) being locked to fixed page sizes, are (literally) a poor fit for digital-only documents !

Markdown's much smaller feature list is much more feasible of course... but is it worth it for the devs to spare their time for that ?

[Dae]

for beginner or lazy, you have this tool
https://mods.factorio.com/mod/da-changelog-tools

[Shenpen]

Something to add to your overview is that you can use spaces for indentation, but not tabs.
using tabs will cause the parsing to error with a generic error on the line.

Wow! Just wow!

[Vadatajs]

I really appreciate this tutorial...but...man...seems like there's always something else.

For example...found out that my changelogs weren't showing up in game because on the lines that use '-' you have to use a single space before text otherwise it's rejected.

IE
" - This is a change that is accepted"
" - This is a change this is not accepted, because there are two spaces after the '-'"

[brevven]

I believe there is now a new issue with spaces after category fields: For example:

Code: Select all

  Features:<space><newline>

will not parse in-game, the space must be removed.

I do not believe this used to be the case.

[Pi-C]

I believe there is now a new issue with spaces after category fields: For example:
…
I do not believe this used to be the case.

Thanks! Actually, that does seem to be an old issue. In the first post of this thread, section "In short: rules and example of a working changelog file", I've found this:

Add categories! Category lines must be indented with 2 spaces. They must end with a colon, no spaces are allowed after the colon! Category names may contain spaces. The required format of such a line is "**My category:".

But the format of a forum posting really isn't ideal, and it's easy to miss such details in a long wall of text.

[brevven]

Ah thank you, must have missed that I confused the guide with the format checker you've shared previously: https://mods.factorio.com/mod/da-changelog-tools/, but I've reported this issue on that as well, and that seems to be the appropriate venue.

[Bilka]

The changelog format is now documented on the wiki: https://wiki.factorio.com/Tutorial:Mod_changelog_format

[Pi-C]

The changelog format is now documented on the wiki: https://wiki.factorio.com/Tutorial:Mod_changelog_format

Thanks, that will be quite useful! A forum post just isn't as good a medium for a tutorial as a wiki page, and with all the additions and changes I've made over the time, my tutorial was, admittedly, a bit difficult to read. So, I'm glad there finally is an official documentation.