Changelog tutorial

Place to get help with not working mods / modding interface.
User avatar
Optera
Smart Inserter
Smart Inserter
Posts: 2915
Joined: Sat Jun 11, 2016 6:41 am
Contact:

Re: Changelog tutorial

Post by Optera »

jockeril wrote:
Wed Jan 15, 2020 3:29 pm

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
Smart Inserter
Smart Inserter
Posts: 1639
Joined: Sun Oct 14, 2018 8:13 am
Contact:

Re: Changelog tutorial

Post by Pi-C »

jockeril wrote:
Wed Jan 15, 2020 3:29 pm
@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... :evil: )
Thanks for the compliment -- and for keeping your changelogs working! :-D
@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.
A good mod deserves a good changelog. Here's a tutorial (WIP) about Factorio's way too strict changelog syntax!

Schallfalke
Fast Inserter
Fast Inserter
Posts: 162
Joined: Sun Oct 28, 2018 7:57 am
Contact:

Re: Changelog tutorial

Post by Schallfalke »

jockeril wrote:
Wed Jan 15, 2020 3:29 pm
@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
Smart Inserter
Smart Inserter
Posts: 1025
Joined: Thu Oct 03, 2019 7:10 am
Contact:

Re: Changelog tutorial

Post by Honktown »

Heh, triggered a very minor "bug":
image
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.
I have mods! I guess!
Link

Pi-C
Smart Inserter
Smart Inserter
Posts: 1639
Joined: Sun Oct 14, 2018 8:13 am
Contact:

Re: Changelog tutorial

Post by Pi-C »

Honktown wrote:
Thu Jan 16, 2020 8:18 pm
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.
A good mod deserves a good changelog. Here's a tutorial (WIP) about Factorio's way too strict changelog syntax!

User avatar
BlueTemplar
Smart Inserter
Smart Inserter
Posts: 2420
Joined: Fri Jun 08, 2018 2:16 pm
Contact:

Re: Changelog tutorial

Post by 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 ?
BobDiggity (mod-scenario-pack)

User avatar
Dae
Inserter
Inserter
Posts: 28
Joined: Sat Feb 11, 2017 2:52 am
Contact:

Re: Changelog tutorial

Post by Dae »

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

User avatar
Shenpen
Fast Inserter
Fast Inserter
Posts: 227
Joined: Sat Aug 27, 2016 2:46 pm
Contact:

Re: Changelog tutorial

Post by Shenpen »

Muppet9010 wrote:
Tue Mar 12, 2019 12:01 am
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
Manual Inserter
Manual Inserter
Posts: 1
Joined: Wed Jul 31, 2019 2:21 pm
Contact:

Re: Changelog tutorial

Post by 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 '-'"

User avatar
brevven
Long Handed Inserter
Long Handed Inserter
Posts: 61
Joined: Mon May 01, 2017 1:02 am
Contact:

Re: Changelog tutorial

Post by 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
Smart Inserter
Smart Inserter
Posts: 1639
Joined: Sun Oct 14, 2018 8:13 am
Contact:

Re: Changelog tutorial

Post by Pi-C »

brevven wrote:
Tue Feb 22, 2022 5:20 am
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.
A good mod deserves a good changelog. Here's a tutorial (WIP) about Factorio's way too strict changelog syntax!

User avatar
brevven
Long Handed Inserter
Long Handed Inserter
Posts: 61
Joined: Mon May 01, 2017 1:02 am
Contact:

Re: Changelog tutorial

Post by 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
Factorio Staff
Factorio Staff
Posts: 3123
Joined: Sat Aug 13, 2016 9:20 am
Contact:

Re: Changelog tutorial

Post by Bilka »

The changelog format is now documented on the wiki: https://wiki.factorio.com/Tutorial:Mod_changelog_format
I'm an admin over at https://wiki.factorio.com. Feel free to contact me if there's anything wrong (or right) with it.

Pi-C
Smart Inserter
Smart Inserter
Posts: 1639
Joined: Sun Oct 14, 2018 8:13 am
Contact:

Re: Changelog tutorial

Post by Pi-C »

Bilka wrote:
Mon Jan 09, 2023 12:26 pm
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. :-)
A good mod deserves a good changelog. Here's a tutorial (WIP) about Factorio's way too strict changelog syntax!

Post Reply

Return to “Modding help”