Make the changelog parser more lenient, please!

[Pi-C]

About a month ago, I posted a changelog tutorial because I didn't like that the changelog button in the game's mods manager was inactive for so many mods I looked at. I strongly feel that every mod should have a changelog (it's a courtesy to prospective users, and a necessity if the update is known to break something), and that it should be accessible inside the game. You -- the developers -- have already provided a wonderful tool to allow that. Unfortunately, it seems to be rather hard to use this tool -- and the lack of official documentation doesn't make it any easier.

With the tutorial, I've tried to educate modders about writing changelogs that make use of the great abilities of the in-game parser. When I posted the first version, what little information I could provide came from comparing changelogs that did parse correctly against others that didn't. It was based mainly on guesswork, and some things I'd figured out were incorrect or incomplete, but with very helpful input from the community and developers (thanks again, Bilka!), and after playing around with several "real" changelogs to find mistakes, I was able to add a lot of information over time. (It's still WIP; just as I'm writing this, somebody has pointed out a new problem in the other thread.)

By now, I've probably spent more time carefully looking over non-working changelogs than most people who care to read this. I think I know all of the common errors, and I've even found some of the rarer ones. Therefore, I believe I can rightfully claim to be quite competent in changelog matters now.

In the past few weeks, quite a number of changelogs had entries like "Added changelog", or "Fixed changelogs not showing in game". This clearly shows that many modders are willing to provide parsable changelogs once they've learnt about what is needed.

Yes, dear developers, believe it or not: There still are many people out there who are totally unaware that something like a special syntax for changelog files even exists!

However, some of them failed, and even though they thought they had done everything correctly, their changelogs couldn't be parsed. By any means, that is definitely not because they've been too stupid to follow some clearly laid out rules, but because the rules are absurdly strict! One modder even added "It's apparently a science field" to his "fixed changelog" entry -- that should show how hard it is to follow the rules, even if one wants to. I therefore appeal to you, the developers: Please, make the changelog parser more lenient, more tolerant of minor mistakes!

There definitely are bugs that are clearly down-to-earth bugs, and it is perfectly OK that parsing such a bug results in an error. I'm thinking of the header line starting with a dot instead of a dash, for example, or the missing line break in front of the header line (so it was glued to the end of the previous line). But there are also bugs that are really hard to find, and completely unnecessary. A space after a colon results in an error? An empty line, with just a tabulator before the line break, breaks parsing? So does a header line with 100 instead of 99 dashes? No, this can't be serious! That must be somebody's idea of a joke, but it's a bad joke by my book.

In my opinion, there are two things you could do to help modders write working changelog files:

1. Relax the rules, for example by using a kind of pre-processor that converts wrong changelog files to the right format! Most minor mistakes could be caught with regular expressions. I'll use sed-commands in the following, but I guess C and Lua allow for regular expressions as well.
   • Globally replace tabs with a space:

     Code: Select all

     's/\t/ /g'

   • Delete empty lines, including lines that contain only spaces:

     Code: Select all

     '/^ *$/d'

   • Make sure the first line is a header line:

     Code: Select all

     '1 s/^ *\([^-][^-].\+\)$/---------------------------------------------------------------------------------------------------\n\1/'

   • Make sure the last line is not a header line:

     Code: Select all

     '$ s/^ *-\+ *$//'

   • Make sure all headerlines have the required format:

     Code: Select all

     's/^ *-\+ *$/---------------------------------------------------------------------------------------------------/'

   • Delete lines with empty Date fields:

     Code: Select all

     '/^ *[Dd][Aa][Tt][Ee] *: *$/d'

   • Correctly format Version lines:

     Code: Select all

     's/^ *\[Vv][Ee][Rr][Ss][Ii][Oo][Nn] *:\(.\+\)*$/Version: /\1/'

   • Correctly format any remaining Date lines:

     Code: Select all

     's/^ *[Dd][Aa][Tt][Ee] *: *\(.\+\) *$/Date: \1/'

   • Make sure the other field/category names are formatted correctly:

     Code: Select all

     's/^ *\([^:]\+\) *: *-* *\(.\+\) *$/  \1:\n    - \2/'

   • Make sure the actual entries are indented correctly:

     Code: Select all

     's/^ *-* *\(.\+\) *$/    - \1/'

   • Just to make sure, remove any trailing spaces:

     Code: Select all

     's/ *$//'

   Really, that would have been enough to make most of the wrong changelog files I've seen work out of the box. Anything else -- empty or duplicate version fields, spelling errors, the examples mentioned above etc. -- can rightfully be regarded as a true bug, and should result in a parsing error. Which brings me to …
2. … the error messages. Make them more expressive, please! A message like this is good:

   Code: Select all

   Failed to parse changelog for mod [insert mod name here]: invalid changelog file, error on line 4, missing category.

   because it tells exactly what is wrong here. But a message like

   Code: Select all

   Failed to parse changelog for mod  [insert mod name here]: invalid changelog file, error on line 123.

   doesn't give any clue what could be wrong. Considering that most of the buggy files fail to parse because of too many (or not enough) spaces or dashes, or because they contain the wrong kind of white space characters (i.e. tabulators), such error messages are not really useful.

I perfectly understand that there may be more serious bugs you -- the developers -- have to care about.

Actually, I'm confined to version 0.17.14 because of a still-unfixed bug introduced in 0.17.15, and two of the mods I wanted to use are disabled because they depend on base >= 0.17.14, so I'm definitely an interested party there!

But with a few small changes (yes, I know it's easy to say that if you don't have to implement them) you could make life much easier for a lot of the modders and, consequently, their -- and your! -- users. Just do so, pretty please!

[bobucles]

I took a shot at a dumb mod and played with the changelog. Damn that thing is brutal. If it doesn't like what you have, it simply discards it. Pretty brutal for a text document.

[steinio]

+1

[badtouchatr]

I agree. I just added a new mod to the portal today. It shows up fine in the in-game portal, but doesn't show up on https://mods.factorio.com/mod/scraplib

No errors in the log file, either.

[Pi-C]

It shows up fine in the in-game portal, but doesn't show up on https://mods.factorio.com/mod/scraplib

Now you've got me hooked! I've read something to the tone of "It shows up fine in the in-game portal" already today, in a private message. I'm not a modder and have used the mod portal only to look for interesting mods, or to file bugs and request features, so I'm quite ignorant about it.

How does publishing a mod work, actually? Do you upload the mod and things like the changelog are extracted automatically and put on a separate page? I had assumed you'd have to create a page for a mod and input all of the text there on your own. Also, I therefore believed that "it shows up fine on the mod portal" wouldn't be a valid test for errors in the changelog file. My assumption was that it "works" there because all that happens on the mod portal is displaying a static text file, while the in-game parser performs some magic to get at the individual chunks of information that can then be sorted and filtered by version and category. Is that wrong?

[badtouchatr]

To publish a mod, you would click on the "Submit mod" button near the top of the mods page. Then, it has a big box to click where you will actually upload the .zip file. You fill in a Description for it, then select a Category, and a license. Click the "Submit" button at the bottom, and ... voila, it's submitted!

So yeah, I don't know why the changelog shows up perfectly in-game, but on the mods site, nothing. Could be they're still working out their own bugs for whatever changes they made recently to the mod portal. *Throws hands up in the air*

[bobingabout]

I think the fact that it specifically has to be UTF-8 without BOM, or it FAILS is pretty brutal. I write a document in plain text, no special or extended characters, and save in whatever the standard output is of my text editor, and it just doesn't work. For the longest time, I just didn't bother having a change log in the mod, because the changelog file is way too brutal, especially when the same file actually works fine on the mod portal.

[Pi-C]

To publish a mod, you would click on the "Submit mod" button near the top of the mods page. Then, it has a big box to click where you will actually upload the .zip file. You fill in a Description for it, then select a Category, and a license. Click the "Submit" button at the bottom, and ... voila, it's submitted!

OK, seems like the mod portal is working similar to the in-game changelog viewer: It creates links/buttons for Information, Downloads, and Discussion by default, and adds some for FAQ and Changelog if the mod provides them.

However, my assumption that "My changelog appears on the mod portal, therefore it will also be parsed in-game" is wrong, seems to be correct. Apparently, if there is a changelog file in the mod, it will be extracted and displayed as is, even if the in-game parser would choke on it. Otherwise, this wouldn't be possible.

So yeah, I don't know why the changelog shows up perfectly in-game, but on the mods site, nothing. Could be they're still working out their own bugs for whatever changes they made recently to the mod portal. *Throws hands up in the air*

I guess it must be something like this! There's really nothing wrong with your changelog, it works for me in the game.

[jamiechi1]

I have been using notepad++ for years and had to set it to utf-8 (without BOM) to edit html and javascript properly. So I haven't seen some of the issues others see.
I believe the reason for the differences in how things are parsed versus in-game, is due to the different environments.
The web page most likely uses javascript (in html) and the game uses c++ internally. (Different parsers)

There definately needs a formal document somewhere to explicitly define the required document mark up required.
White space, including linefeeds should be ignored in processing the change log information, just as it is ignored for the most part in many languages such as Lua and C++.

Maybe XML should be used for the change logs. This will make it easier to define exactly where things go and what they are.

Maybe a better option is to make it simple like windows used to do in an 'ini' file. An example of a simple 'ini' file format is what they use in the fallout games ini files. Square brackets to delineate sections and simple text with no need to worry about encoding styles.

Keep it simple.

[Pi-C]

For the longest time, I just didn't bother having a change log in the mod, because the changelog file is way too brutal,

This post I've completely failed to notice before. I'd assumed your mods didn't have changelogs because you have so many of them that required too much time to take care of …

especially when the same file actually works fine on the mod portal.

I don't think there actually is a parser like the in-game parser on the mod portal -- it must be that the changelog file is extracted from the mod's zip file and used as it is:

Example of a changelog text on the mod portal that wouldn't be parsed by Factorio

bad_changelog_modportal.png (21.22 KiB) Viewed 6062 times

There definately needs a formal document somewhere to explicitly define the required document mark up required.

Definitely. You can require very strict syntax rules -- but then you must provide documentation and not let people find out the rules by trial and error. If you don't want to do that, the rules must be easy, and the parser must be tolerant enough to accept anything thrown at it except grave errors, e.g. duplicate version numbers or text not belonging to any category.

White space, including linefeeds should be ignored in processing the change log information, just as it is ignored for the most part in many languages such as Lua and C++.

Right, ignore white space, let any line that contains at least two dashes in a row and nothing else (/^[[:space:]]*---*[[:space:]]*$/) be a header line, and most changelogs would be parsed without an error.

Maybe XML should be used for the change logs. This will make it easier to define exactly where things go and what they are.

True, but …

Keep it simple.

… I think leaving the current format, just without the white space requirements, would actually be more simple to write:

• Any line with any number of dashes, and nothing else (except for white space) marks a new entry.
• Version/Date lines have their values on the same line as the field name. That's justified because these lines are special as they define exactly a specific changelog entry.
• All other field names/categories are marked by a colon (plus optional white space) at the end of the line.
• All other lines -- whether they start with a dash or not -- are regarded as a list element of the last defined category.

That's not hard to memorize, and it's intuitive because you can indent lines or insert linefeeds between categories just as you like. Final formatting for the display in the game should be left to the parser -- that can take care of a consistent format for all mods.

[bobingabout]

For the longest time, I just didn't bother having a change log in the mod, because the changelog file is way too brutal,

This post I've completely failed to notice before. I'd assumed your mods didn't have changelogs because you have so many of them that required too much time to take care of …

Well, that's also a factor. I couldn't get it to work on the first attempt. I did a bit more playing with it, but couldn't figure out what I was doing wrong.

So I moved on, and did something else, like add more features.


The latest versions of the mod do actually have change logs in them now, but they only go back to 0.15.0, and only 3 mods have been released since then. Power, Warfare and Logistics. I've done a lot of unreleased changes.

[Pi-C]

So I moved on, and did something else, like add more features.

The latest versions of the mod do actually have change logs in them now, but they only go back to 0.15.0, and only 3 mods have been released since then. Power, Warfare and Logistics.

Well, that's a starting point! Would be nice to have a complete version history, but honestly: 0.15.0 goes back far enough. Most people would just care about what happens in current versions anyway, I guess. Whether updating a mod might break something or whether the mod has cool new features, that's of real interest.

[Rseding91]

So, I read all of the posts so far here. I agree the error(s) should be more explicit about what is incorrect. I don't agree that any of them should be made more lenient.

Factorio doesn't do "it's close, so I'll fix it" logic - the thing is either correct or incorrect - and in the case of changlog files they're incorrect if they don't match the exact formatting required by the changlog system.

We specifically don't allow any variance because there's no reason for it. If the thing is wrong... then it's wrong.

[badtouchatr]

So, I read all of the posts so far here. I agree the error(s) should be more explicit about what is incorrect. I don't agree that any of them should be made more lenient.

Factorio doesn't do "it's close, so I'll fix it" logic - the thing is either correct or incorrect - and in the case of changlog files they're incorrect if they don't match the exact formatting required by the changlog system.

We specifically don't allow any variance because there's no reason for it. If the thing is wrong... then it's wrong.

Still .... then why isn't the "exact formatting required by the changlog system" published somewhere for modders to see, instead of making users have to figure it out by trial and error?

Also, even following the "exact formatting" seems to work sometimes, and not others, in the case of my recently uploaded mod, where the changelog appears fine in-game, but doesn't show up at all on https://mods.factorio.com. What's up with that?

[Mxdanger]

So, I read all of the posts so far here. I agree the error(s) should be more explicit about what is incorrect. I don't agree that any of them should be made more lenient.

Factorio doesn't do "it's close, so I'll fix it" logic - the thing is either correct or incorrect - and in the case of changlog files they're incorrect if they don't match the exact formatting required by the changlog system.

We specifically don't allow any variance because there's no reason for it. If the thing is wrong... then it's wrong.

Still .... then why isn't the "exact formatting required by the changlog system" published somewhere for modders to see, instead of making users have to figure it out by trial and error?

Also, even following the "exact formatting" seems to work sometimes, and not others, in the case of my recently uploaded mod, where the changelog appears fine in-game, but doesn't show up at all on https://mods.factorio.com. What's up with that?

Yeah, I would have to agree. If the changelog formatting is made so that there should be no guessing because it should simply be either right or wrong with no in-between, then there should be clear documentation for mod developers to reference so they don't have to guess and figure it out by trial and error.

[Pi-C]

Factorio doesn't do "it's close, so I'll fix it" logic - the thing is either correct or incorrect - and in the case of changlog files they're incorrect if they don't match the exact formatting required by the changlog system.

Others have already taken issue with this, and rightly so. To quote myself:

You can require very strict syntax rules -- but then you must provide documentation and not let people find out the rules by trial and error. If you don't want to do that, the rules must be easy, and the parser must be tolerant enough to accept anything thrown at it except grave errors …

The current situation is one that I'd expect to read about in a story or novel by Franz Kafka (who happened to be from Prague, too). I really like his writing, but I prefer reading about Kafkaesque situations over seeing them in real life.

By now, there already is an unofficial tutorial on changelog syntax made by your users. If you don't want to waste time on publishing an official document laying down the syntax rules, could you (or one of your colleagues) at least go over the tutorial and point out what exactly is still missing there? I plan to condense the information in that thread into a PDF -- after all the updating, it looks really messy on the forum now. But I'd like to be the information to be correct and complete, otherwise such a document wouldn't be very useful. So, some form of official contribution would be very appreciated!

Another point: I had a closer look at the changelogs displayed on the mod portal. People seem to think that what is working there should also work in-game. I assume there is no changelog parser at the mod portal (see the image posted here). However, the formatting of the displayed changelogs there could give people wrong ideas.

This changelog from Schall Lamp Contrast is known to work in-game:

Working changelog, as shown on the mod portal

changelog_modportal_schalllampcontrast.png (72.65 KiB) Viewed 5999 times

I would blame nobody for looking at this on the mod portal and taking it as reference. However, if they took hints from how it is displayed there, their changelog wouldn't be parsed by the game: There is no line drawn above the first entry, but there is one at the bottom -- and the in-game parser considers both things as illegal. As a matter of fact, I've seen these two errors occurring together in one changelog many times, so that seems to be a real issue. It would be great if you could at least make the display on the mod portal be in line with the requirements of the game's parser.

[Bilka]

By now, there already is an unofficial tutorial on changelog syntax made by your users. If you don't want to waste time on publishing an official document laying down the syntax rules, could you (or one of your colleagues) at least go over the tutorial and point out what exactly is still missing there? I plan to condense the information in that thread into a PDF -- after all the updating, it looks really messy on the forum now.

I've been actively replying to your thread, I hope I'm enough to be your official guy :p I don't think anyone on the team has more knowledge on the changelog than what you already collected. Well, perhaps the person who implemented the parser knows more, but they clearly did not care enough to document it. (A common pattern, cough prototype documentation cough). I have had a changelog documentation on my plan for a long time now, I will probably go over yours and port it to the wiki once I am mostly done with the 0.17 updating of the rest of the wiki (that should be soon!).

[badtouchatr]

Pi-C: I agree 99.9999993% (sorry, rounding error )

I'm going to reserve judgment until I make the next update, but I'm leaning towards one of these possibilities:

- something doesn't work right for the very first time you upload a new mod, or
- the parser is just acting moody.

[Bilka]

As a sidenote, some of the errors have already been improved a bit. I changed the "no colon after category error" to instead say "category line does not end in colon", because that is what it is actually checking - a space after the colon will throw this error. The "duplicate date" error now says "duplicate date or version" and the basically empty "error on line x" now says what it expects the line to start with.

[Pi-C]

I've been actively replying to your thread,

I know that! I've immediately included (rather, linked to) the list of category names you provided, and I've also acknowledged your contribution in the original post of this thread.

I hope I'm enough to be your official guy :p

I'm sorry if I made a wrong impression, I really didn't mean to belittle you! However, you seemed a bit unsure about "custom" categories. Also, it's been about a month since you made that post, and several things have been added in the meantime. So I thought it wouldn't hurt if somebody could look over everything that is there now.

I don't think anyone on the team has more knowledge on the changelog than what you already collected. […] I have had a changelog documentation on my plan for a long time now, I will probably go over yours and port it to the wiki once I am mostly done with the 0.17 updating of the rest of the wiki (that should be soon!).

Thanks, that would be wonderful! I won't make that PDF, then. Means some more time for me to actually play again.