Changelog tutorial

[GrumpyJoe]

[*]Order of changelog entries
I think in all of the changelogs I've seen, new entries have been added to the top of the file. However, the in-game changelog viewer shows the oldest changelog entry at the top and the latest at the bottom. I therefore believe that order doesn't really matter. Insert new entries at the top of the file if you feel like it, or add them at the bottom if that is more to your taste. I guess you could even put them in arbitrary order if you really are into stuff like that! It should make no difference as far as the game's parser is concerned, but it could drive you and/or your mod's users into insanity.

The ingame mod manager changelog windows seems to sort them by version number
17.1
17.2
...
..



However, the mod portal changelog tab either sorts them by highest number
17.4
17.3
..
..
or simply shows the changelog.txt file, as my file is "upside down", always latest first
I´d really love to have it that way, as people generally (myself included) are lazy and a majority wont scroll down to the latest changes, but might be familiar with older ones
Should be possible, since it can also identify fields and is actually sorting already

-------------------------

Also, imho the order of field names should be reworked

I just added an "Other" category for some really unrelated info.
That tab order now is "Features" , "Bugfixes" , "All" and "Other".
Where i think "All" should be on either side, not somewhere in the middle
I´d prefer the left

[Muppet9010]

The mod portal doesn't group the change log in any way, just showing it all. The in-game view groups the changes in to tabs on the Major and I think minor version.

[Pi-C]

Posted the update, finally!

• Added example of a working changelog file and a short description of the syntax rules at the top
• Added note on the contents of VERSION fields, regarding multiple version numbers/text add-ons (section "Structure of a changelog file")
• Added note on the difference between official and custom field names
• Added section "What should go into the changelog?"
• Added note that the mod portal is not suitable for testing changelog files (section "General hints and common traps")

[Schallfalke]

Posted the update, finally!
...

It certainly looks better, especially with the beginning parts.
Just like the programming textbooks, they always have the correct syntax/code shown first, followed by each wrong syntax/code and explained why it does not work, one-by-one.
Your tutorial text has now become more "professionally" written.

[GrumpyJoe]

I wouldn´t know a programmers textbook, but as a go-to reference its very nice to have everything you need on top.
You know, like i said, people are lazy and you wanna catch them from the start.

If they then copy,paste&add and it doesn´t work cos they add a tab somewhere, they can still look it up later. However, they started to add changelogs, which is the ultimate goal.
The only thing i´d change is, put the link to Bilka´s working category post somewhere near the top, maybe after the shortlist of dos and donts
Something like categorize your changes, a link to working and prefered categories can be found >>here<<


Since at least Bilka is reading here, i´d like to know about sorting categories and the "All" tab posted above from a devs point of perspective.
I know, noone is gonna say anything beside maybe a "not so high on our priority list", if saying anything at all
I´d need to pay closer attention next patch, see if Patchnotes are sorted in a particular way.
I still think that the only issue with changelogs is that "all" category is somewhere in the middle of categories.
After this nice tutorial brought together by the community, i have no problem with changelog parser acting abit strange or unexpected. There is a go-to now for anyone who cares.
Awesome work

[Pi-C]

It certainly looks better, especially with the beginning parts.
Just like the programming textbooks, they always have the correct syntax/code shown first, followed by each wrong syntax/code and explained why it does not work, one-by-one.
Your tutorial text has now become more "professionally" written.

Thanks for the flowers! About the more "professional" writing: I guess that is because I've become almost "professional" regarding changelog files during the past few weeks. In the beginning, it really was just guesswork, now I've actually learnt a lot.

The only thing i´d change is, put the link to Bilka´s working category post somewhere near the top, maybe after the shortlist of dos and donts
Something like categorize your changes, a link to working and prefered categories can be found >>here<<

I've added the link to the passage about categories in the rules summary now. Also, things like file encoding are mentioned there now.

I still think that the only issue with changelogs is that "all" category is somewhere in the middle of categories.

But that's only if you use "custom" categories.

After this nice tutorial brought together by the community, i have no problem with changelog parser acting abit strange or unexpected. There is a go-to now for anyone who cares.

It really does help that the error messages are so much better now! Mind you, there's still room for improvement, but now, at least, they show what is wrong.

Awesome work

Thanks! However, I also see weaknesses. A posting in a forum is not the right format! Too much to scroll, you can't set anchors to link to in the posting, and the formatting is just lousy. Also, with all the update notes in between, the text really is hard to read (and to maintain). I'd like to keep it that way, though, as it documents the process of unveiling the mystery quite well. However, I guess I should rewrite and condense the text and put it up as a PDF. Perhaps I'll get to it over the Easter holidays. Time to hone the LaTeX skills again!

[BlueTemplar]

Thanks! However, I also see weaknesses. A posting in a forum is not the right format! Too much to scroll, you can't set anchors to link to in the posting, and the formatting is just lousy. Also, with all the update notes in between, the text really is hard to read (and to maintain). I'd like to keep it that way, though, as it documents the process of unveiling the mystery quite well. However, I guess I should rewrite and condense the text and put it up as a PDF. Perhaps I'll get to it over the Easter holidays. Time to hone the LaTeX skills again!

That's what the wiki is for !

While (La)TeX is pretty great - especially in its more modern Lua(La)TeX version - PDFs, with their page-focused layout, are better suited for documents that you expect to print, or at least slideshow...

[Delzur]

Can we have something like "Author:" (and maybe "Requested-by", "Suggested-by") below "Date:"?
It would be nice to people that contributes with pull requests on mods

[badtouchatr]

Can we have something like "Author:" (and maybe "Requested-by", "Suggested-by") below "Date:"?
It would be nice to people that contributes with pull requests on mods

That would have to be up to the devs to add it to the parser code. This topic is mainly to explain the un-documented rules as they exist now.

[Delzur]

That would have to be up to the devs to add it to the parser code. This topic is mainly to explain the un-documented rules as they exist now.

I know, but it seems that the devs are looking at the topic, and I might simply have missed some fact

[Pi-C]

Update: Schallfalke explained why there have been cases where valid changelog files would be shown in the game, but not on the mod portal. Apparently, the changelog will always be hidden on the mod portal if the first version of a mod is uploaded. If you update the mod and the new version contains a changelog file, the changelog will be immediately available on the mod portal.

[Shenpen]

TL;DR

Teach modders to write changelogs in such a way that they make best use of Factorio's capabilities.

Why?

There are lots of mods around, and most of them have changelogs. It is good to have changelogs (you want to know before updating whether an update may break something) -- it is even better if one can read them directly in the game and doesn't have to switch to the browser and look in the mod portal. However, there are many mods where the "Changelog" button in the game's mods manager is inactive. Sometimes this happens because of a real bug (e.g. typos), sometimes the authors never really cared enough to fix such seemingly unimportant errors, and sometimes they just hadn't realized that changelog files require a special syntax.

What?

Recently, I happened to start Factorio from the terminal instead of using the shortcut in the menu. I was updating some mods and checking out others by selecting them in the game's mods manager. When the game restarted, I saw the output that is usually hidden and noticed a number of lines like these:

Code: Select all

2944.131 Error CachedChangelog.cpp:37: Failed to parse changelog for mod [insert name here]: invalid changelog file, error on line 1.

Although I'm not a modder myself, bugs do bug me and so I dug around a bit, tried to find out what was wrong, and filed bug reports against some of the mods I have installed. However, I soon realized that it would be less work to start a thread explaining modders how to write changelogs that can be parsed by and displayed in Factorio.

In short: rules and example of a working changelog file

As suggested by GrumpyJoe, here is an example of a working changelog file (snippet from Schall Alien Mutation, with some changes to categories):

Code: Select all

---------------------------------------------------------------------------------------------------
Version: 0.17.2
Date: 2019.03.21
  Balancing:
    - Updated pollution_to_join_attack values to base game 0.17.12 standard.
  Optimisations:
    - Code tidying and cleanup.
---------------------------------------------------------------------------------------------------
Version: 0.17.1
Date: 2019.03.07
  Changes:
    - Updated thumbnail for 0.17.
---------------------------------------------------------------------------------------------------
Version: 0.17.0
Date: 2019.03.01
  Info:
    - Updated to 0.17.
---------------------------------------------------------------------------------------------------
Version: 0.16.3
Date: 2019.02.07
  Optimisations:
    - Optimized code to make better order in spawn tables.
  Graphics:
    - Added icons to alien types, in case any mods are using them.
---------------------------------------------------------------------------------------------------
Version: 0.16.2
Date: 2018.12.15
  Locale:
    - Russian is available.
---------------------------------------------------------------------------------------------------
Version: 0.16.1
Date: 2018.12.06
  Optimisations:
    - Internal name changes.
  Locale:
    - Simplified Chinese is available.
---------------------------------------------------------------------------------------------------
Version: 0.16.0
Date: 2018.11.25
  Info:
    - Initial release
  Locale:
    - English, German, traditional Chinese are available.
  License:
    - Using Bob's Copyright License. Document included.

A summary of the syntax rules (in the following, each "*" represents an obligatory space):

• Never use the tab character (\t) anywhere in the changelog file -- it's an illegal character!
• The changelog entry for each new version of your mod must begin with a header line. It must contain exactly 99 dashes ("-"), nothing else, no spaces anywhere!
• Immediately after the header line, include a unique version number. Don't indent the line! The required format is "Version:*[version number]".
• The release date is optional. If you include it, don't indent the line! The required format is "Date:*[date string]". The date string must not be empty -- if you don't know the date, just leave out the entire line!
• 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:". Here is a list of the "official" categories used by the developers for Factorio's changelog.
• Under each category, add at least one list entry. These lines must be indented with 4 spaces and begin with "-", followed by a space. One entry can span several lines. Each additional line must be indented with 6 spaces. The required format is "****-*[text]" or "******[continued text]".
• You may insert empty lines before a category line and at the end of a changelog entry. Empty lines must be really empty -- they must not contain any spaces!
• The file must be named "changelog.txt". It must be in the root directory of your mod, and it must be encoded as UTF8 without BOM!

Update (2019-06-15): It's common knowledge that once you've uploaded your mod to the mod portal, the changelog will be shown there and in the game. However, there have been cases where a flawless changelog would be displayed in the game, but not on the mod portal. Nobody really could explain that. Somebody brought up that issues with cacheing or synchronization might be the reason, and the usual suggestion was to just wait until the problem would fix itself.

Schallfalke has a better explanation. He observed that if a mod was initially released, the changelog wouldn't be shown on the modportal and it would only be shown in the game's mod manager after it had been installed. If an update of a mod was uploaded and that update contained a changelog, this changelog would be displayed on the mod portal and (if it was a valid changelog file) in the game's mod manager for both installed and new mods.

That behavior seems to make sense: Changes are in respect to the previous version, so there are no changes yet in the initial release. However, the changelog is not only used to keep track of changes -- just check out the list of categories! But wouldn't it also make sense to describe major features in the changelog of the initial release, or to give information about the localizations available etc.? Needless to say, it would help to avoid a fair bit of confusion if the changelog would always (from the initial release onwards) be shown on the mod portal. Couldn't that be implemented?

Getting started … detailed explanation

First thing you should be aware of is that your changelog has to follow some rules regarding syntax and formatting in order to be recognized by the game's parser. Consider this example:

Code: Select all

Version 0.4.1: Updated for Factorio 0.17. Fixed conflict with nanobots.

Version 0.3.2: Fixed ghost variation offset.

Version 0.3.1: Updated for Factorio 0.16.x. Decreased file size. Added a button to deselect the input field.
[…]

Every version has its own line, it shows everything one needs to know, and it is concise. That's good, isn't it? Nope. You can read it, I can read it -- but to Factorio's parser, it doesn't make any sense at all.

So, how about this?

Code: Select all

1.0.1:
- Updated mod to work with 0.17.x
---------------------------------------------------------------------------------------------------
1.0.0:
- After some hours of testing I declared this version v1.0.0; I'm quite happy with how it is now.
---------------------------------------------------------------------------------------------------
0.6.0:
- Fixed the balancing
- Upgraded the graphics to 64x64 tiles instead of the old 32x32
---------------------------------------------------------------------------------------------------
0.5.1:
- Added the Github page as the homepage URL in the info.json

The version number on a separate line allows for listing a number of different changes with improved readability, the separator lines between the version entries help to see where a new changelog entry begins -- that sure must be alright! Wrong again: I will get it, you will get it -- but Factorio's parser won't.

So, what syntax does Factorio expect?

Syntax rules

Let me start with a disclaimer: I have no clue! I am just a normal player, not a modder, and I couldn't find a guide to changelog syntax. All information I provide comes from comparing changelog files from mods I found a parsing error for in the output with changelog files from mods that could be parsed successfully.

In short, what I've written here boils down to more or less qualified guesswork. That means the information and explanations I can give are likely to be either wrong or incomplete. This posting can only a be starting point, making modders aware that their changelog files may need some tweaking. I would appreciate it very much if anybody with more knowledge on this matter -- modders or even devs -- would correct me where I've been wrong, or add more information. Perhaps there even is a document laying out the rules for changelog files that can be parsed by the game? If so, please link to it!

Now, on to the real stuff …

• Structure of a changelog file (I use the -- working -- file from Schall Lamp Contrast as an example here)
  • The changelog file is a normal text file containing one or more changelog entries.
    Update (2019-03-08): It should be named "changelog.txt" and be stored right in the root directory of your mod.
    Update (2019-03-12): According to steinio, it may be required that the changelog file is encoded as UTF-8 without Byte Order Mark (BOM).
    Update (2019-03-23): Bilka confirmed that changelog files encoded as UTF-8-BOM will break parsing. So, please encode your changelog files in plain UTF-8, without BOM!
• Structure of a changelog entry
  • A changelog entry starts with a header line. If the parser encounters such a line, it will look for a new changelog entry in the following lines next line.

    Code: Select all

    ---------------------------------------------------------------------------------------------------

  • A header line contains only dashes ("-"). I guess, technically it would be enough if the first character is a dash; then again, humans can make more sense of it if the header lines span the whole line width.
    
    Implications: This means that the first line the first non-empty line of the changelog file must be a line with only dashes. It also means that the last non-empty line of the changelog file must not be a line containing only dashes -- otherwise the parser will throw an error because it expects to find another changelog entry. (I mention this explicitely because these seem to be the most common mistakes causing the parser to abort with an error message. Apparently, many modders consider a line consisting of only dashes to be a separator line, so they omit it at the start of their file. Also, it seems some modders want to make their changelog file look neat, so they use dashed lines as top and bottom borders.)
    
    Update (2019-03-19): It is now official that the header line must be the first non-empty line in the changelog file. That means it doesn't matter if you hit ENTER a couple of times before starting the first header line. However, keep in mind that a line containing only space characters does not qualify as an empty line!
    
    Update (2019-03-29): According go badtouchatr, the header lines must consist of exactly 99 dashes.
  • After the header line, add a version field:

    Code: Select all

    ---------------------------------------------------------------------------------------------------
    Version: 0.17.0
    

    Update (2019-03-19): Please note that "Version: …" must start at column 1 of the line, there must be no spaces preceding it! Also, no empty line is allowed between this line and the previous header line!
    
    Update (2019-04-16): The version field should only contain one version number, no additional text. This will work as expected:

    Code: Select all

    Version: 0.17.0
    

    These will be parsed without an error, but the result will not be what you expect:

    Code: Select all

    Version: 0.17.0 [BETA]
    Version: 0.17.0/0.17.1
    Version: 0.17.0-0.17.2
    

    Apparently, version numbers may only contain digits and dots. If the field contains any other other character, parsing will stop right there. So, all of the three lines shown above would be rendered as

    Code: Select all

    Version: 0.17.0
    

    If only little has changed between two versions -- e.g. if you updated your mod to the latest version of Factorio in 0.17.0 and decided to add a changelog in 0.17.1 after reading this tutorial -- it seems to make sense to use the latest version number. So, instead of

    Code: Select all

    Version: 0.17.0/0.17.1
    

    I'd recommend using

    Code: Select all

    Version: 0.17.1
    

    because that was the version where the last change documented in this block has been implemented.
  • Add a date field (optional):

    Code: Select all

    ---------------------------------------------------------------------------------------------------
    Version: 0.17.0
    Date: 2019.03.01
    

    Update (2019-03-19): Please note that "Date: …" must start at column 1 of the line, there must be no spaces preceding it! There may be empty lines before or after it.
    
    I'm not sure whether the date field is actually required by the game's parser. However, it is nice to know when a mod has been updated by the author, so just include it, please! By the way, it shouldn't matter to the parser whether you write "2019.03.01", "2019-03-01", "01.03.2019", or whatever. I take it that everything after "Date:" is just interpreted as a string by the parser.
    
    Update (2019-03-08): As Blue Templar pointed out, the date format does matter to humans! Factorio is played around the world, and people in different countries are used to interpret date strings differently. "08/03/2019" could be read as "March 8, 2019", but also as "August 3, 2019". So Blue Templar suggests that the value of the date field should be given in Coordinated Universal Time (UTC), which I strongly support as having all mods using one time format makes things unambigious. A date string with the current time in UTC notation looks like this:

    Code: Select all

    Date: 2019-03-08 21:49:16+01:00
    

    For more information about this format, please refer to RFC 3339.
    
    Update (2019-03-19): According to my tests, the date field is optional. However, if you set it, it must not be empty! The contents of the date field must be a non-empty string -- ideally the current date and time (UTC), but something like "November 2018" would also be possible. If you don't remember when you have released a version, you could just insert a space after the colon ("Date: "). In this case, you could also leave out that line altogether: the game's parser will then kindly insert "Date: " on its own.
    
    Important: Take care to use unique version numbers and dates! I've seen one mod where the parser complained about a duplicate date field. Actually, the author had just copied the version and date fields, so there were two entries with the same version/date string in the changelog file.
    (I would have expected the parser to stumble over the duplicate version field, which should have been parsed first -- don't know why it didn't.)
    If you release more than one version on the same day, I'd suggest to add the time to the datefield, like this:
    

    Code: Select all

    Date: 2019-03-01 11:36:25+01:00
    

    Update (2019-03-08): Time format changed to UTC, as suggested by Blue Templar.
  • So far, we have just defined the header: There is a line signifying the beginning of a new entry, there is the version number, and there is the date of when the changes have been implemented. Now it's time for the content! Just add a description of your changes, optionally [spoiler](?)[/spoiler] embedding them in by adding other fields:
    

    Code: Select all

    ---------------------------------------------------------------------------------------------------
    Version: 0.17.0
    Date: 2019.03.01
      Features:
        - Updated to 0.17.
    

    That's it!
    
    Update (2019-03-08): According to my tests, all information must be provided as contents of a field. Here is an example that doesn't work:

    Code: Select all

    ---------------------------------------------------------------------------------------------------
    Version: 0.17.0
    Date: 2019.03.01
    
    Added magnificent new features!
    

• Order of changelog entries
  I think in all of the changelogs I've seen, new entries have been added to the top of the file. However, the in-game changelog viewer shows the oldest changelog entry at the top and the latest at the bottom. I therefore believe that order doesn't really matter. Insert new entries at the top of the file if you feel like it, or add them at the bottom if that is more to your taste. I guess you could even put them in arbitrary order if you really are into stuff like that! It should make no difference as far as the game's parser is concerned, but it could drive you and/or your mod's users into insanity.
• Structure of fields
  A field consists of FIELDNAME:FIELDCONTENTS. The colon after FIELDNAME seems to be is mandatory. Apparently (see the previous code snippet) FIELDCONTENTS may must begin with a space (version/date) or a linebreak (other fields).
  
  FIELDNAME apparently can contain spaces. It should start with a capital letter -- that may not be required by the game parser, but it helps human parsers (i.e., the users of your mod).
  
  A properly indented list structure may not be is mandatory, but helps your users to parse the file -- especially, if you have more than just one field in your changelog entry:
  

  Code: Select all

  ---------------------------------------------------------------------------------------------------
  Version: 0.17.0
  Date: 2019.03.01
    Features:
      - Updated to 0.17.
  ---------------------------------------------------------------------------------------------------
  Version: 0.16.0
  Date: 2019.01.31
    Features:
      - Replaced the vanilla lamp graphics for higher contrast circuit display.
      - Lamps are not colliding with vehicles, allowing walk or drive over.
      - Options on lamp base style, to fit concrete tile or for stronger contrast in signal display.
      - Options on lamp glow size. (Default: 3.  Vanilla: 6.)
      - Options on reorder priority on signal colour. (Default: vanilla settings.)
      - Options on enable colour display on white signal. (Default: off.)
      - Options on enable colour display on grey signal. (Default: off.)
      - Options on enable colour display on black signal. (Default: off.)
      - Options on priority on white signal. (Default: L1.)
      - Options on priority on grey signal. (Default: L2.)
      - Options on priority on black signal. (Default: L3.)
    Locale:
      - English, German, traditional Chinese, simplified Chinese are available.
    License:
      - Using Bob's Copyright License.  Document included.
  

  Update (2019-03-12): Steinio hinted before that , possibly, no tabs may be used in changelog files. This has been confirmed now by Muppet9010. So, please, don't use tabs in the changelog file, only spaces are allowed!
  
  Update (2019-03-19): According to my tests, the game's parser is rather finicky regarding indentation. It adheres to these rules:
  1. "Version:" and "Date:" must start at column 1.
  2. All other field names must be indented by 2 spaces and start at column 3. The line must end with the colon, no space characters are allowed after it!
  3. Start a list (one or more lines) after the line with the field name. Each line of this list must be indented by 4 spaces and start with a dash followed by a space ("- ") at column 5. Consequently, the actual text starts at column 7. If you have very long lines, they will be wrapped so that the new lines start at column 5. You may insert a linebreak instead. In this case, you must insert at least 4 spaces to avoid parsing errors; however, you should insert 6 spaces, so the text aligns correctly.
• Notes on field names
  • Be consistent! If you want to use a field name like "Bugfixes", use it always in your file -- don't write "Bugfixes: …" in one changelog entry and "Bugfix: …" in another!
  • Think of these field names as categories! Seems like some cool stuff is possible if you do it right. Have a look at this screenshot, for example:
    
    asphaltroads_all.png
    
    Notice the long row of tabs at the top of the screen? These correspond to field names used in the changelog file.
    
    asphaltroads_minorfeatures.png
    
    This screenshot just shows a list of minor features. Apparently, the parser compiles a list of all changelog entries containing a category field name ("Minor Features" in this case), and then shows the contents of that field in the tab's window. That's some quite impressive magic, isn't it? Just structure your changelog file/entries correctly and you've got filters automated -- if that isn't in the spirit of Factorio, I don't know what is …
    
    The filtering goes even further. There is a version selector at the top left of the screen. See this screenshot:
    
    schalllampcontrast_0.17.png
    
    But something is missing, right? Remember, we had the following fields defined:

    Code: Select all

    ---------------------------------------------------------------------------------------------------
    Version: 0.17.0
    Date: 2019.03.01
      Features:
        - Updated to 0.17.
    ---------------------------------------------------------------------------------------------------
    Version: 0.16.0
    Date: 2019.01.31
      Features:
        - Replaced the vanilla lamp graphics for higher contrast circuit display.
        […]
      Locale:
        - English, German, traditional Chinese, simplified Chinese are available.
      License:
        - Using Bob's Copyright License.  Document included.
    

    So, where are the tabs for "Locale" and "License"? Well, they are created -- if you set the filter to version 0.16:
    
    schalllampcontrast_0.16.png
    
    Update (2019-03-08): Bilka was so kind to provide a list of FIELDNAMEs that are guaranteed to work. He also mentioned that he is not sure about custom FIELDNAMEs used by mods -- they could work, or they might cause a parsing error.
    
    Update (2019-04-16): It seems you can really use any string you want as a field name. Bilka explained the differences between using official and custom field names: If only official field names (the ones used by the developers in the vanilla game) are used, the All tab will always be the last one on the right; if you make up your own, they will be placed to the right of the All tab, so All is harder to find.
• Empty lines
  You may use empty lines to visually separate blocks. However, please make sure these lines are really empty, as in "empty string"! Neither space nor tabulator characters are allowed. Just hit ENTER to insert an empty line -- and if your editor provides an option like that, activate "Remove trailing spaces on save"!

What should go into the changelog?

So far, I've explained what is needed so your changelog will be displayed in the game. The question of what information should be mentioned there is hardly less important, however. Here are my thoughts on that matter, with suggestions for what categories to use:

• Info: I'd use this for anything important that should stand out from the mass of regular changes:
  • Initial release
  • Update to a new major version (e.g. 0.17) of Factorio
  • New or changed dependencies
  Why dependencies? They are listed on the main page of the mods manager, after all! -- True. But the information provided there is only correct for mods that are not installed yet. If a mod already is installed, the information contained in info.json (e.g. mod description, author, and dependencies) is displayed for the currently installed version. If you click on the changelog button, however, the changelog from the latest version of the mod will be displayed.
  
  Most people will have the latest version of the game installed. Some, however, might prefer to wait a bit longer to avoid newly introduced bugs -- and others may even be unable to update because of some obscure, unfixed bug. So, if you change your mod in such a way that it depends on the latest version of the base mod or a library, there may be people it might not work for after the update. If you add the changed dependencies to your changelog, these people will know that updating the mod might be dangerous before they try. If nothing else, including such information in the changelog is being polite to your users.
• Bugfixes: As a rule of thumb, if a line contains the words "fixes" or "fixed", it should be filed under this category. You probably should use "Bugfixes:" even if you've only changed one bug: "Bugfixes:" is an official category, the singular form ("Bugfix:") is not -- and the in-game changelog viewer will sort tabs differently if custom categories are used (see above).
• Feature/Minor Feature/Major Feature: If you've added something you're really proud of, use these categories to make the new feature stand out!
• Changes: Almost everything else should go here, except for
• License/Translation/Locale: Again, these categories are important enough to stand out. "License:" is not an official category, however, so you should be aware that using it will mess up the order of the tabs.

I think these categories should be more than enough in most cases. If you want to use others, just do it! There are more official categories to choose from, and in case you need something else, you could always create your own.

General hints and common traps

• Be sure to structure all of your changelog entries correctly! A file like this:

  Code: Select all

  ---------------------------------------------------------------------------------------------------
  Version: 0.17.0
  Date: 2019.03.01
    Features:
      - Updated to 0.17.
  
  Version: 0.16.0
  Date: 2019.01.31
    Features:
      - Replaced the vanilla lamp graphics for higher contrast circuit display.
      - Lamps are not colliding with vehicles, allowing walk or drive over.
      […]
  

  would not throw a parsing error because it starts with a header line. However, it would be parsed differently than expected: The parser would only see "Version: 0.17.0". "Version: 0.16.0" and everything that follows would be considered as part of the description for version 0.17.0.
• Test and test again, and again! If the parser aborts with an error in line 1, it doesn't mean that there are no errors later on. The parser will abort at the first error it finds, so if you correct that error and try again, it may abort at another line. Please, do yourself and your users a favor and correct everything until the file is parsed correctly!
• How to check for errors: This assumes that your mod does have a changelog file! If there is no file named "changelog.txt" in your mod's root directory, the parser won't need to be started for your mod, so there will be no debugging output. In this case, please create a changelog -- it's useful to have!
  1. Start the game from the command line, so you can see debugging output.
  2. In the main menu, click on "Mods" (or whatever that is translated to in your game's locale).
  3. Look up your mod under the "Manage" tab and select it.
  4. If your changelog file failed to parse, you will see now an error message in the debugging output. In this case, quit the game, fix the error, and restart at step 1!
     
     Update (2019-03-21): Actually, debugging output is appended to factorio-current.log. So, you don't have to start the game from the command line if you watch that file.
• Update (2019-03-12): Don't use tabs in changelog files, indent lists with spaces instead!
• Update (2019-03-12): Again: Make sure your changelog file starts with a header line (a line that contains only dashes)!
• Update (2019-03-12): Again: The last non-empty line of your changelog file must never, ever be a line that contains only dashes!
• Update (2019-03-12): It is a lot of work to replace all those tabs with spaces, and removing all those spaces at the end of a line. Fortunately, a lot of IDEs and editors have options like "Replace tabs with spaces" or "Remove trailing spaces on save" -- use these, if you don't already! Alternatively, if you are on Linux, this oneliner will help you:

  Code: Select all

  sed -i -e 's/\t/  /g' -e 's/\s*$//' changelog.txt
  

  The switch "-i" causes sed to overwrite your file, so be sure to make a back-up!
• Update (2019-04-16): Beware! "The changelog is displayed on the mod portal" is not a valid test! Apparently, if you upload your mod, the changelog file will be extracted and displayed as is -- without any regard for the syntax rules imposed by the in-game parser. So, it is possible that the changelog will fail to parse even though it is displayed on the mod portal. Use the in-game changelog viewer for testing, and check factorio-current.log for error messages, please!

Conclusion

That was all information I could think of. I hope you don't think me presumptuous for telling you how to do such easy and/or boring stuff like writing a changelog! Well, just see it this way: The devs and some modders (I don't think anybody would use every mod that is out there!) have provided me with a wonderful game that I've spent way too many hours on already, and I just want to do something for it in return -- and if this should help to improve the overall quality of the game, it's just so much the better for everyone!

As stated above, there may be things I've got wrong or that are missing. If so, you are very welcome to leave your comments in the thread!

============
Changes:
2019-03-08
- Fixed some typos
- Edited section "Add a date field"
- Added link to list of guaranteed-to-work field names (section "Notes on field names")
- Added information about name/location of the changelog file (section "Structure of a changelog file")

2019-03-12
- Made my own changelog cleaner by adding dates to update notifications
- Added note about file encoding (section "Structure of a changelog file")
- Added note that tabs are not allowed in changelog files (sections "Structure of fields"/"General hints and common traps")
- For emphasis, added another note on the issue of dashed lines at start/end of changelog files (section "General hints and common traps")

2019-03-19
- Verified/corrected information I wasn't sure about before (sections "Structure of a changelog entry" and "Structure of fields")
- Added note on rules for indentation (section "Structure of fields")
- Added note on editors (section "General hints and common traps")

2019-03-21
- Added note about debugging output appended to factorio-current.log (section "General hints and common traps")

2019-03-23
- Added note about correct file encoding for changelog files (section "Structure of a changelog file")

2019-03-29
- Added note about number of dashes in header lines (section "Structure of a changelog entry")

2019-04-06
- Added section "Empty lines"

2019-04-16
- Added example of a working changelog file and a short description of the syntax rules at the top (section "In short: rules and example of a working changelog file")
- Added note on the contents of VERSION fields, regarding multiple version numbers/text add-ons (section "Structure of a changelog file")
- Added note on the difference between official and custom field names
- Added section "What should go into the changelog?"
- Added note that the mod portal is not suitable for testing changelog files (section "General hints and common traps")

2019-06-15
- Added explanation why sometimes valid changelog files would be shown in the game, but not on the mod portal (section "In short: rules and example of a working changelog file")

Or you can just put any text into a changelog.txt with 99 dashes. Works fine for the mod-portal.

[Pi-C]

Or you can just put any text into a changelog.txt with 99 dashes. Works fine for the mod-portal.

That's not the point! The mod-portal will display anything you throw at it. This tutorial is about making changelogs that can be parsed and presented directly inside the game. If you don't follow the in-game parser's syntax rules, the users of your mods won't be able to browse your changelog directly from the game and must make the additional effort to switch to a browser, go to the mod-portal, and look for your mod. As for myself, I want to know whether it's worth the trouble to update a mod (and then restart the game -- with about a hundred mods active, restarting takes quite some time!), so I've made it a habit to check the changelog first. If I can't access the changelog directly from the game, chances are I won't download your next version.


Another thing: It's not really necessary to quote the entire text of the tutorial just to add a short comment to it. The tutorial was already quite long when I first published it, and has increased in length even more over time. Quoting it in its entirety just forces people to scroll down a long, long way, at the danger of scrolling too far (and missing your addition, or even subsequent postings) -- that's just as inconvenient as not including a working changelog with your mod!

[Shenpen]

It's not really necessary to quote the entire text of the tutorial just to add a short comment to it.

Is actually an illustrative point!

Will there be a succinct version of this "guide" at a later point?

[Pi-C]

Will there be a succinct version of this "guide" at a later point?

I've been advised against making a PDF version of it. Bilka mentioned he'd put up a wiki based on this -- but I guess there's more important work he has to do right now.

[Shenpen]

Will there be a succinct version of this "guide" at a later point?

I've been advised against making a PDF version of it. Bilka mentioned he'd put up a wiki based on this -- but I guess there's more important work he has to do right now.

Perhaps a tv-series then.

[Bilka]

Will there be a succinct version of this "guide" at a later point?

I've been advised against making a PDF version of it. Bilka mentioned he'd put up a wiki based on this -- but I guess there's more important work he has to do right now. :-)

Perhaps a tv-series then.

This is episode one

[Shenpen]

Exelent. I'm certain that will motivate a lot reading. Then people just need to "learn to code".

[Pi-C]

This is episode one

Wow, that's an immense improvement, thanks! Modders who have thought of including a changelog (as a separate file changelog.txt, not just on the information page in the mod-portal) will see immediately that there is a difference between changelogs on the mod-portal and in-game, and can act on it if they want to.

But could we take that one step further, please? There still are many mods around that don't contain a changelog file. What if we just pretend that every mod does, but changelog.txt is just considered to be empty if it's not present? The effect should be that the changelog tab in the mod-portal is always shown, and if a mod doesn't contain a changelog the modder can see that something may be missing. I believe that not including a changelog usually happens because people just don't think of it -- not because they are against it. So bringing it to their attention by showing the tab seems like a good idea to me.

[darkfrei]

It would be nice to change the changelog direct by the mod portal. Why I need to upload new mod version just for adding/ fixing changelog?