Changelog tutorial

[<NO_NAME>]

This syntax is reaching a whole new, unknown before levels of being too strict.
Why can't the parser just use some simple regexes to make things easier for modders if not actual game programmers of the game.

I've written 6 simple regexes which would be fully compatible with the current syntax but eliminate a whole lot of unnecessary restrictions.

• Header line (any printable character which is not letter on digit, repeated at least 3 times):

  Code: Select all

  ^\s*[^\sA-Za-z0-9]{3,}\s*$

• Version:

  Code: Select all

  ^\s*[Vv]ersion[:\s]\s*([0-9.]+)\s*$

• Date:

  Code: Select all

  ^\s*[Dd]ate[:\s]\s*([0-9]{4}\.[0-9]{2}\.[0-9]{2})\s*$

• Category:

  Code: Select all

  ^\s*(\w+):\s*$

• Entry:

  Code: Select all

  ^\s*(?!-{3,})-\s*(\S|\S.*\S)\s*$

• Ignored line (empty or containing only non-printable characters):

  Code: Select all

  ^\s*$

[Optera]

Not a bad idea in general however strictly enforcing yyyy-mm-dd is not the best idea.

1) It doesn't account for multiple releases on one day. The yyyy-mm-dd hh:mm:ss should be just as valid.
2) Outside IT circles no one sadly uses this format and prefers the nonsensical format their country uses, like the US format mm/dd/yyyy.

[Pi-C]

This syntax is reaching a whole new, unknown before levels of being too strict.

I know. That's why I've opened another thread some months ago.

Why can't the parser just use some simple regexes to make things easier for modders if not actual game programmers of the game.

Because, to quote Rseding91, "if the thing is wrong... then it's wrong."

I've written 6 simple regexes which would be fully compatible with the current syntax but eliminate a whole lot of unnecessary restrictions.

Been there, done that. Also, I just noticed that Trebor has put up a working sed-script in that other thread …

Anyway, the gist of the other thread is this: It's OK to apply very strict rules if you tell people what the rules are. In the beginning, the rules were too strict and undocumented. The developers won't ease the rules, but we have been promised that documentation will be improved.

I'd like to emphasize Bilka's contribution: he has been very helpful! It may have slipped by unnoticed because this isn't explicitly mentioned in any release notes of Factorio, but he has made writing/debugging changelogs much easier by

• reworking the error messages so that they actually make sense and point out correctly (most of the time -- an error on line 1 is always about a missing or broken header line, no matter what the error message tells you) what is wrong,
• and by changing the mod portal in such a way that if you upload a mod, you will be pointed to this thread (extremely helpful because many modders aren't even aware that changelogs require a special syntax).

He will also document changelog syntax in the wiki when he is done with updating the rest of the wiki for 0.17.

[Bilka]

• reworking the error messages so that they actually make sense and point out correctly (most of the time -- an error on line 1 is always about a missing or broken header line, no matter what the error message tells you) what is wrong,
• and by changing the mod portal in such a way that if you upload a mod, you will be pointed to this thread (extremely helpful because many modders aren't even aware that changelogs require a special syntax).

Thanks for pointing out the line 1 thing, I have made the error for it clearer (now points out that you need a header line for any error on line 1). The BOM no longer errors, thanks to posila. The mod portal change was something Sanqui did because he saw the pinned thread, none of my doing :p

[Pi-C]

Thanks for pointing out the line 1 thing, I have made the error for it clearer (now points out that you need a header line for any error on line 1).

Great news!

In this context, could you provide me with a list of all existing error messages, please? I think it would be a good idea to include them in the tutorial. (I could try to collect them on my own, but there's always a chance of missing one or a couple …)

The BOM no longer errors, thanks to posila.

I'll update that …

The mod portal change was something Sanqui did because he saw the pinned thread, none of my doing :p

In the post where this change was announced, there was no mention of who implemented it, so I assumed it must have been you. I herewith formally extend my thanks to posila and Sanqui!

Oh, by the way: Why are you (this means all of the developers who have delved into the matter) so modest about your work regarding the changelog parser? Sure, fixing some error messages etc. may not seem as important as, say, reworking the complete behavior of fluid boxes or the rail network. But mod manager and changelog parser are part of the game, so it seems appropriate to mention changes to these in the release notes as well.

[<NO_NAME>]

Anyway, the gist of the other thread is this: It's OK to apply very strict rules if you tell people what the rules are. In the beginning, the rules were too strict and undocumented. The developers won't ease the rules, but we have been promised that documentation will be improved.

It's only OK to apply very strict rules if you are also OK with the fact that a lot of changelogs will be broken because someone has put one additional space somewhere, by accident.

Anyway, I appreciate this tutorial. I had a bad time when I was trying to fix my changelogs. Good work!

[Pi-C]

Anyway, the gist of the other thread is this: It's OK to apply very strict rules if you tell people what the rules are. In the beginning, the rules were too strict and undocumented. The developers won't ease the rules, but we have been promised that documentation will be improved.

It's only OK to apply very strict rules if you are also OK with the fact that a lot of changelogs will be broken because someone has put one additional space somewhere, by accident.

While I agree with you, that's something the developers have to decide. It's OK in the sense that people have at least a chance to comply with the rules (however strict these rules may be) iff the rules are documented somewhere. The way it used to be -- very strict rules that nobody knew about -- was like in The Hitchhikers Guide to the Galaxy:

“But the plans were on display…”
“On display? I eventually had to go down to the cellar to find them.”
“That’s the display department.”
“With a flashlight.”
“Ah, well, the lights had probably gone.”
“So had the stairs.”
“But look, you found the notice, didn’t you?”
“Yes,” said Arthur, “yes I did. It was on display in the bottom of a locked filing cabinet stuck in a disused lavatory with a sign on the door saying ‘Beware of the Leopard.”

Anyway, I appreciate this tutorial. I had a bad time when I was trying to fix my changelogs. Good work!

Thanks for the compliment!

[slippycheeze]

FWIW, I have used https://github.com/git-chglog/git-chglog to turn git commit messages into a specific changelog format in the past. It was flexible enough that I'm pretty sure you could write a compatible output for Factorio changelogs, if you wanted, and used git. I'm sure something similar for other VCS choices exists, and so do a million more Git variations.

Someone helpful might do that, then post the template to the wiki or something. Unfortunately, right now, that someone isn't me. Sorry.

[Pi-C]

Update:

Some weeks ago, I've wanted to add that changelogs may now be files encoded as UTF8 with BOM. Forgot that somehow, it's done now. Also, Bilka has told me how to make "Date: " lines without a date error-proof. Just add at least one question mark at the end of the line:

Code: Select all

---------------------------------------------------------------------------------------------------
Version: 0.17.4
Date: ?

[adamius]

Just made Changelog tools to automate this. Far from finished and I'm sure there's plenty to do.

[Pi-C]

@Bilka:
I think I found a GUI bug:

More categories than fit on the screen

all_categories.png (56.92 KiB) Viewed 7227 times

I wanted to test the ordering of the tabs, so I made a changelog file where all vanilla categories + one custom category have been used. Turns out the list was too wide for my screen (1920x1080, full screen), so the custom category isn't displayed. However, there is no way to scroll the category list.

This is what it looks like in windowed mode:

Non-fullscreen mode

windowed.png (22.14 KiB) Viewed 7227 times

Please note the last tab (highlighted because the cursor is hovering over it).

This is what I get in windowed mode by clicking on the last tab:

Non-fullscreen mode (after click)

windowed_click.png (20.82 KiB) Viewed 7227 times

As you can see, the last tab has vanished, and there's no way to get at it again.

Granted, using so many categories is hardly practical, and I guess nobody in their right mind would do this! But especially for non-fullscreen mode, it would make sense if the tabs were scrollable. Is that something that could be implemented?

[Pi-C]

I've thought for a long time that multiple entries with the same version line would always result in an error. However, there seem to be cases (see versions 0.0.3 and 0.0.4 in the attached file) where the parser accepts them -- merging these entries! Has that always been that way (may be nobody discovered that before), has there been a change lately, or is that a bug?

[Honktown]

I had posted this topic somewhere else with no replies - is there a way to flip the order of how the changelog is presented in-game? The order is always first to last (I get that, ascending order of number), but changes are you know... descending in order of version history, and since that's the only sorting field, I always have to scroll down to the bottom to see what's been changed. I'm a regex/Perl monster and just that litttttttttle thing gets to me.

Edit: I did actually change the order of my changelog history in the file (if I recall correctly), but the parser thwarted me and sorted it anyway or gave an error, not sure which.

[Pi-C]

I had posted this topic somewhere else with no replies - is there a way to flip the order of how the changelog is presented in-game? The order is always first to last (I get that, ascending order of number), but changes are you know... descending in order of version history, and since that's the only sorting field, I always have to scroll down to the bottom to see what's been changed. I'm a regex/Perl monster and just that litttttttttle thing gets to me.

Sorry, but as far as I know there is no way to change the order in the game. You could always use the buttons in the top row of the changelog viewer to directly jump to the latest change, though:

changelog.png (18.35 KiB) Viewed 7101 times

Edit: I did actually change the order of my changelog history in the file (if I recall correctly), but the parser thwarted me and sorted it anyway or gave an error, not sure which.

The parser actually helped you. It doesn't really matter in what order the changelog entries are placed in the file. During my tests, I've also had cases where I changed the version number of a random entry, and the unsorted file was then displayed in sorted order by the game nevertheless, which is definitely better for users than the unsorted file.

If you don't like the sort order (and I can see that with very long changelogs, it may be useful to read it in descending order), I suggest you make a request to the developers.

[Squelch]

I was going to ask what people's feelings were on the order that changes were presented. It seems the answer came before the question was made...

It is generally a convention to order changelogs as most recent first, and I had noticed that many Mod makers are indeed listing changes in reverse order on inspection of the files. The ingame changelogs are always in chronological order, top to bottom it appears, and seems to be at odds with the convention. The Mod Portal does respect the file's order just to confuse things further

Thank you @Pi-C for this resource. I have only recently created my first mod, and called upon this thread for reference.

[Pi-C]

It is generally a convention to order changelogs as most recent first, and I had noticed that many Mod makers are indeed listing changes in reverse order on inspection of the files. The ingame changelogs are always in chronological order, top to bottom it appears, and seems to be at odds with the convention.

I hadn't thought about that before, but checking some changelogs from my Debian installation, you seem to be right. However, using ascending order in the changelog file can be useful! I use the following "hack" in my own changelogs:

Add a category "TODO:" as the last thing of a changelog entry. It's kind of a list of notes what I want to do in the future (like any normal TODO-list). When I work on a new version, I start the latest changelog entry right above the "TODO:". Whenever I'm finished with one entry from that list, I move that up, into the fitting category; whenever I have a new idea, I add it below "TODO:". This list will only ever be in the changelog for the currently released mod version, so it doesn't clutter up the file with useless junk. Putting new versions at the bottom of the file saves me the trouble to cut the list from the previous version and move it up to the current one. Very simple, but quite efficient.

The Mod Portal does respect the file's order just to confuse things further

The Mod Portal doesn't respect anything -- it is dumb and will display just about everything you can place in a text file, even changelogs that don't follow the requirements.

Thank you @Pi-C for this resource. I have only recently created my first mod, and called upon this thread for reference.

Nice to read that another modder is using it. Oh, and you're welcome!

[Pi-C]

Update: Rewrote the section on Version numbers. There's more to them than I originally thought!

[adamius]

Version 0.0.-1 is bigger than it appears.

[Pi-C]

Version 0.0.-1 is bigger than it appears.

It should be, as the first character of "-1" is not an integer. But I'll rephrase the text so that it explicitly mentions "unsigned integers".

[jockeril]

@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... )

@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

Change log category order.JPG (49.15 KiB) Viewed 7003 times

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.