In other languages:

Tutorial:Mod changelog format: Difference between revisions

From Official Factorio Wiki
Jump to navigation Jump to search
(More version and date info, decide to call the thing between the dash lines "version section")
(Made some opinionated changes)
 
(5 intermediate revisions by one other user not shown)
Line 1: Line 1:
{{Languages}}__NOTOC__
This is the format required to display mod changelogs in the in-game mod browsing GUI. The changelog.txt file needs to be located in the root of the mod folder (See [[Tutorial:Mod_structure#Files]]).


TODO
The [https://mods.factorio.com/ mod portal] website does ''not'' require this changelog format, it will display the changelog.txt content as plain text.
mod portal doesnt parse changelog like this
completely empty lines are ignored?
mod structure tutorial link for where the file should be


* Parsing errors can be found in the [[log file]] in the [[user data directory]].
Parsing errors are written to the [[log file]] found in the [[user data directory]].


<!-- maybe https://forums.factorio.com/67140 -->
It may be simpler to copy and modify the [[#Example changelog]] than to start from scratch.
<!-- maybe link to vs code extension that has changelog hinting from jarg -->


== Important general format ==
== Formatting rules ==
The changelog format consists of one or multiple version sections, which are read line by line. Each version section has to start with the [[#Version section start]] line. Each version section describes exactly one mod version with an arbitrary amount of categories that each may have an arbitrary amount of entries.
 
Completely empty lines will be skipped by the parser, except the line after [[#Version section start]], which may not be empty.
 
=== General ===
* Do not use tabs.
* Do not leave whitespace at the end of lines ("trailing spaces").
 
It is recommended to set up the text editor to enforce this automatically. Usage of tabs and trailing spaces is likely to result in confusing error messages.
 
=== Version section start ===
The line must be 99 dashes exactly: <code>---------------------------------------------------------------------------------------------------</code>.
 
The following line must be a [[#Version]] line. It cannot be empty.
=== Version ===
The line must start with exactly <code>Version:&nbsp;</code> (note the space after the colon). The remaining part of the line will be parsed as the version the section is about.<br>
The version itself is formatted as <code>number.number.number</code> (as in <code>major.minor.sub</code>), for example <code>0.6.4</code>. Each number can range from 0 to 65535. <code>0.0.0</code> is not considered a valid version.
 
There may not be two version sections with the same version.<br>
This line is mandatory.
 
Example:<br>
<code>Version: 0.12.35</code>
=== Date ===
The line must start with exactly <code>Date:&nbsp;</code> (note the space after the colon). The remaining part of the line will be parsed as the date the version was released. There are no restrictions for the format of the date itself.
 
There may not be two date lines within the same version section.<br>
This line is optional.
 
Example:<br>
<code>Date: 01. 06. 2016</code>
=== Category ===
The line must start with exactly two spaces. The remaining part of the line will be parsed as the category. The line must end with a colon. When displaying the changelog, this colon is removed.


* Do not use tabs
This line and the entry lines following it are optional.
** Indentation is done with two spaces
* Do not leave whitespace at the end of lines ("trailing spaces")


Usually, text editors can enforce this automatically, it is recommended to set this up.
There are no restrictions for the format of the category itself.
<div class="toccolours mw-collapsible mw-collapsed" style="width: 60em;">
However, some categories are recognized by the game and sorted before the "All" tab in the GUI:
<div class="mw-collapsible-content">
* Major Features
* Features
* Minor Features
* Graphics
* Sounds
* Optimizations
* Balancing
* Combat Balancing
* Circuit Network
* Changes
* Bugfixes
* Modding
* Scripting
* Gui
* Control
* Translation
* Debug
* Ease of use
* Info
* Locale
</div></div>


== Example ==
Example:<br>
It may be simpler to copy this example into your changelog and modify it than to start from scratch.
<code>&nbsp;&nbsp;Minor Features:</code>
=== Entry ===
 
The line must start with exactly four spaces followed by exactly <code>- </code>&nbsp;(note the space after the dash) for a single line entry. For a multiline entry, lines after the first line must start with exactly six spaces.
 
If an entry is used, a previous line in the version section must be a [[#Category]] line. The entry is then associated with the category (see [[#Example changelog]]).
 
Entries for the same version and the same category may not be exact duplicates.
 
Example:<br>
<code>&nbsp;&nbsp;&nbsp;&nbsp;- Fixed the missing title in character logistics window.</code>
== Example changelog ==
It may be simpler to copy and modify this example than to start from scratch.
<pre>---------------------------------------------------------------------------------------------------
<pre>---------------------------------------------------------------------------------------------------
Version: 1.1.60
Version: 1.1.60
Line 26: Line 91:
     - This is an entry in the "Features" category.
     - This is an entry in the "Features" category.
     - This is another entry in the "Features" category.
     - This is another entry in the "Features" category.
    - This general section is the 1.1.60 version section.
   Balancing:
   Balancing:
     - This is a multiline entry in the "Balancing" category.
     - This is a multiline entry in the "Balancing" category.
       There is some extra information here because it is needed for the example.
       There is some extra text here because it is needed for the example.
       Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
       Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
   Bugfixes:
   Bugfixes:
     - Fixed that item requests didn't subtract items picked up from ground when reviving ghosts. (https://forums.factorio.com/102329)
     - Fixed that canceling syncing mods with a save would exit the GUI.
     - Fixed burner inserter would not fuel itself when drop target was full. (https://forums.factorio.com/102449)
     - Fixed a desync when fast-replacing burner generators.
---------------------------------------------------------------------------------------------------
---------------------------------------------------------------------------------------------------
Version: 1.1.66
Version: 1.1.59
Date: 19. 08. 2022
Date: 06. 05. 2022
  Bugfixes:
    - This general section is the 1.1.59 version section.
    - This is an entry in the "Bugfixes" category.
    - Fixed grenade shadows.
---------------------------------------------------------------------------------------------------
Version: 0.1.0
Date: 24. 12. 2012
   Major Features:
   Major Features:
     - Initial release.
     - Initial release.
    - This general section is the 0.1.0 version section.
</pre>
</pre>


== Formatting rules ==
== See also ==
[[#Important general format]] applies everywhere and will lead to confusing error messages if not followed.
* [https://forums.factorio.com/67140 Forum thread about the changelog format]
 
* [[Tutorial:Mod structure]]
TODO One section per version.
 
=== Version section start ===
Must start with exactly <code>---------------------------------------------------------------------------------------------------</code> followed by a newline.
 
The next line must be a [[#Version]] line.
=== Version ===
Must start with exactly <code>Version: </code>, note the space after the colon. The remaining part of the line will be parsed as the version the section is about. TODO version format<br>
There may not be two version sections with the same version.<br>
This line is mandatory.
=== Date ===
Must start with exactly <code>Date: </code>, note the space after the colon. The remaining part of the line will be parsed as the date the version was released. TODO no format restrictions (beside not putting a newline in there lol)
TODO duplication is fine<br>
This line is optional.
=== Category ===
 
Must start with exactly two spaces. The remaining part of the line will be parsed as the category. Must end with a colon (reminder, no whitespace at end of line!). This colon is removed for the purpose of display. TODO names and sorting
 
=== Entry ===
 
Must start with exactly four spaces followed by exactly <code>- </code> (note the space after the dash) for a single line entry. For a multiline entry, lines after the first line must start with exactly six spaces.<br>
Entries in the same version and the same category may not be exact duplicates.
TODO

Latest revision as of 14:59, 7 December 2022

This is the format required to display mod changelogs in the in-game mod browsing GUI. The changelog.txt file needs to be located in the root of the mod folder (See Tutorial:Mod_structure#Files).

The mod portal website does not require this changelog format, it will display the changelog.txt content as plain text.

Parsing errors are written to the log file found in the user data directory.

It may be simpler to copy and modify the #Example changelog than to start from scratch.

Formatting rules

The changelog format consists of one or multiple version sections, which are read line by line. Each version section has to start with the #Version section start line. Each version section describes exactly one mod version with an arbitrary amount of categories that each may have an arbitrary amount of entries.

Completely empty lines will be skipped by the parser, except the line after #Version section start, which may not be empty.

General

  • Do not use tabs.
  • Do not leave whitespace at the end of lines ("trailing spaces").

It is recommended to set up the text editor to enforce this automatically. Usage of tabs and trailing spaces is likely to result in confusing error messages.

Version section start

The line must be 99 dashes exactly: ---------------------------------------------------------------------------------------------------.

The following line must be a #Version line. It cannot be empty.

Version

The line must start with exactly Version:  (note the space after the colon). The remaining part of the line will be parsed as the version the section is about.
The version itself is formatted as number.number.number (as in major.minor.sub), for example 0.6.4. Each number can range from 0 to 65535. 0.0.0 is not considered a valid version.

There may not be two version sections with the same version.
This line is mandatory.

Example:
Version: 0.12.35

Date

The line must start with exactly Date:  (note the space after the colon). The remaining part of the line will be parsed as the date the version was released. There are no restrictions for the format of the date itself.

There may not be two date lines within the same version section.
This line is optional.

Example:
Date: 01. 06. 2016

Category

The line must start with exactly two spaces. The remaining part of the line will be parsed as the category. The line must end with a colon. When displaying the changelog, this colon is removed.

This line and the entry lines following it are optional.

There are no restrictions for the format of the category itself.

However, some categories are recognized by the game and sorted before the "All" tab in the GUI:

  • Major Features
  • Features
  • Minor Features
  • Graphics
  • Sounds
  • Optimizations
  • Balancing
  • Combat Balancing
  • Circuit Network
  • Changes
  • Bugfixes
  • Modding
  • Scripting
  • Gui
  • Control
  • Translation
  • Debug
  • Ease of use
  • Info
  • Locale

Example:
  Minor Features:

Entry

The line must start with exactly four spaces followed by exactly -  (note the space after the dash) for a single line entry. For a multiline entry, lines after the first line must start with exactly six spaces.

If an entry is used, a previous line in the version section must be a #Category line. The entry is then associated with the category (see #Example changelog).

Entries for the same version and the same category may not be exact duplicates.

Example:
    - Fixed the missing title in character logistics window.

Example changelog

It may be simpler to copy and modify this example than to start from scratch.

---------------------------------------------------------------------------------------------------
Version: 1.1.60
Date: 06. 06. 2022
  Features:
    - This is an entry in the "Features" category.
    - This is another entry in the "Features" category.
    - This general section is the 1.1.60 version section.
  Balancing:
    - This is a multiline entry in the "Balancing" category.
      There is some extra text here because it is needed for the example.
      Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
  Bugfixes:
    - Fixed that canceling syncing mods with a save would exit the GUI.
    - Fixed a desync when fast-replacing burner generators.
---------------------------------------------------------------------------------------------------
Version: 1.1.59
Date: 06. 05. 2022
  Bugfixes:
    - This general section is the 1.1.59 version section.
    - This is an entry in the "Bugfixes" category.
    - Fixed grenade shadows.
---------------------------------------------------------------------------------------------------
Version: 0.1.0
Date: 24. 12. 2012
  Major Features:
    - Initial release.
    - This general section is the 0.1.0 version section.

See also