Tutorial:Mod changelog format - Revision history

Bilka: Protected "Tutorial:Mod changelog format": Moved to lua-api.factorio.com ([Edit=Allow only administrators] (indefinite) [Move=Allow only administrators] (indefinite))

2025-12-15T15:14:08Z

Protected "Tutorial:Mod changelog format": Moved to lua-api.factorio.com ([Edit=Allow only administrators] (indefinite) [Move=Allow only administrators] (indefinite))

← Older revision	Revision as of 15:14, 15 December 2025
(No difference)

Bilka: Moved to lua-api.factorio.com

2025-12-15T15:13:26Z

Moved to lua-api.factorio.com

Show changes

Bilka: Example showing broken code between only working code has potential to confuse - I think the source link should give enough info to be clear what the sentence means

2025-07-07T14:14:23Z

Example showing broken code between only working code has potential to confuse - I think the source link should give enough info to be clear what the sentence means

← Older revision		Revision as of 14:14, 7 July 2025
Line 79:		Line 79:
	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]]).		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. Do note that individual lines in a multiline entry will be considered duplicates of other individual lines from other multiline entries in the same category if they are identical ~~(see the second example below)~~. [https://forums.factorio.com/viewtopic.php?p=480814]		Entries for the same version and the same category may not be exact duplicates. Do note that individual lines in a multiline entry will be considered duplicates of other individual lines from other multiline entries in the same category if they are identical. [https://forums.factorio.com/viewtopic.php?p=480814]

	Example:<br>		Example:<br>
	<code>    - Fixed the missing title in character logistics window.</code>		<code>    - Fixed the missing title in character logistics window.</code>

	~~Example of a case that contains duplicate lines that may not be immediately obvious:<br>~~
	~~<pre>~~
	~~- Fixed icon having the wrong color.~~
	~~(Reported by FactorioUser)~~
	~~- Fixed items not getting cleaned up.~~
	~~(Reported by FactorioUser)~~
	~~</pre>~~

	~~In the above example, lines 2 and 4 (<code>(Reported by Factoriouser)</code>) are considered duplicates of each other.~~

	== Example changelog ==		== Example changelog ==

Sharparam: Add clarification on how duplicates in entries are handled.

2025-05-14T01:26:31Z

Add clarification on how duplicates in entries are handled.

← Older revision		Revision as of 01:26, 14 May 2025
Line 79:		Line 79:
	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]]).		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.		Entries for the same version and the same category may not be exact duplicates. Do note that individual lines in a multiline entry will be considered duplicates of other individual lines from other multiline entries in the same category if they are identical (see the second example below). [https://forums.factorio.com/viewtopic.php?p=480814]

	Example:<br>		Example:<br>
	<code>    - Fixed the missing title in character logistics window.</code>		<code>    - Fixed the missing title in character logistics window.</code>

			Example of a case that contains duplicate lines that may not be immediately obvious:<br>
			<pre>
			- Fixed icon having the wrong color.
			(Reported by FactorioUser)
			- Fixed items not getting cleaned up.
			(Reported by FactorioUser)
			</pre>

			In the above example, lines 2 and 4 (<code>(Reported by Factoriouser)</code>) are considered duplicates of each other.

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

Bilka: Translations of the modding tutorials are allowed

2023-11-13T20:42:13Z

Translations of the modding tutorials are allowed

← Older revision		Revision as of 20:42, 13 November 2023
Line 1:		Line 1:
	__NOTOC__		{{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]]).		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]]).

Ickputzdirwech: Removed {{Languages}}. added category modding

2023-11-12T09:33:28Z

Removed {{Languages}}. added category modding

← Older revision		Revision as of 09:33, 12 November 2023
Line 1:		Line 1:
	~~{{Languages}}~~__NOTOC__		__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]]).		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]]).

Line 117:		Line 117:
	* [https://forums.factorio.com/67140 Forum thread about the changelog format]		* [https://forums.factorio.com/67140 Forum thread about the changelog format]
	* [[Tutorial:Mod structure]]		* [[Tutorial:Mod structure]]

			[[Category:Modding]]

Therenas: Made some opinionated changes

2022-12-07T14:59:38Z

Made some opinionated changes

← Older revision		Revision as of 14:59, 7 December 2022
Line 1:		Line 1:
	{{Languages}}__NOTOC__		{{Languages}}__NOTOC__
	This is the format required ~~by the in-game changelog viewer~~ to display mod changelogs in the ~~browse mods~~ GUI. The changelog.txt file ~~is expected~~ to be located in the root of the mod folder~~, see~~ [[Tutorial:Mod_structure#Files]].		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 ~~online~~ [https://mods.factorio.com/ mod portal] does ''not'' require this changelog format, it will display ~~any~~ changelog.txt ~~file~~ content.		The [https://mods.factorio.com/ mod portal] website does ''not'' require this changelog format, it will display the changelog.txt content as plain text.

	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]].

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

	== Formatting rules ==		== Formatting rules ==
	The changelog ~~is expected to consist~~ 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 ~~is expected to describe~~ exactly one mod version with an arbitrary amount of categories that each may have an arbitrary amount of entries.		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, ~~with the exception that~~ the line after [[#Version section start]] may not be empty.		Completely empty lines will be skipped by the parser, except the line after [[#Version section start]], which may not be empty.

	=== General ===		=== General ===
Line 20:		Line 20:

	=== Version section start ===		=== Version section start ===
	The line must be exactly <code>---------------------------------------------------------------------------------------------------</code>.		The line must be 99 dashes exactly: <code>---------------------------------------------------------------------------------------------------</code>.

	The ~~next~~ line must be a [[#Version]] line. It cannot be empty.		The following line must be a [[#Version]] line. It cannot be empty.
	=== Version ===		=== Version ===
	The line 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.<br>		The line 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.<br>
	The version itself is ~~expected in the format~~ <code>number.number.number</code> ~~for~~ <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.		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>		There may not be two version sections with the same version.<br>
Line 33:		Line 33:
	<code>Version: 0.12.35</code>		<code>Version: 0.12.35</code>
	=== Date ===		=== Date ===
	The line 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. There are no restrictions for the format of the date itself.		The line 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. There are no restrictions for the format of the date itself.

	There may not be two date lines within the same version section.<br>		There may not be two date lines within the same version section.<br>
Line 41:		Line 41:
	<code>Date: 01. 06. 2016</code>		<code>Date: 01. 06. 2016</code>
	=== Category ===		=== 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.

	~~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. This colon is removed for the purpose of display.~~		This line and the entry lines following it are optional.

	This line and ~~its following~~ entry lines are optional.

	There are no restrictions for the format of the category itself.		There are no restrictions for the format of the category itself.
Line 78:		Line 77:
	The line 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.		The line 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.

	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]].		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 in the same version and the same category may not be exact duplicates.		Entries for the same version and the same category may not be exact duplicates.

	Example:<br>		Example:<br>

Bilka: Bilka moved page User:Bilka/Tutorial:Mod changelog format to Tutorial:Mod changelog format without leaving a redirect: Page is finished

2022-11-11T17:06:39Z

Bilka moved page User:Bilka/Tutorial:Mod changelog format to Tutorial:Mod changelog format without leaving a redirect: Page is finished

← Older revision		Revision as of 17:06, 11 November 2022
(No difference)

Bilka: Reordered, added general parsing expectations

2022-11-11T17:06:21Z

Reordered, added general parsing expectations

← Older revision		Revision as of 17:06, 11 November 2022
Line 1:		Line 1:
			{{Languages}}__NOTOC__
	This is the format required by the in-game changelog viewer to display mod changelogs in the browse mods GUI. The changelog.txt file is expected to be located in the root of the mod folder, see [[Tutorial:Mod_structure#Files]].		This is the format required by the in-game changelog viewer to display mod changelogs in the browse mods GUI. The changelog.txt file is expected to be located in the root of the mod folder, see [[Tutorial:Mod_structure#Files]].

	The online [https://mods.factorio.com/ mod portal] does ''not'' require this changelog format, it will display any changelog.txt file content.		The online [https://mods.factorio.com/ mod portal] does ''not'' require this changelog format, it will display any changelog.txt file content.

	~~TODO~~		Parsing errors can be found in the [[log file]] in the [[user data directory]].
	~~completely empty lines are ignored?~~

	* Parsing errors can be found in the [[log file]] in the [[user data directory]].		It may be simpler to copy and modify the [[#Example changelog]] than to start from scratch.
	* 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 -->~~		== Formatting rules ==
			The changelog is expected to consist 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 is expected to describe exactly one mod version with an arbitrary amount of categories that each may have an arbitrary amount of entries.
	== ~~Important general format~~ ==

	* Do not use tabs
	** 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~~.		Completely empty lines will be skipped by the parser, with the exception that the line after [[#Version section start]] may not be empty.

	== ~~Formatting rules~~ ==		=== General ===
	~~[[#Important general format]] applies everywhere and will lead to confusing error messages if~~ not ~~followed~~.		* Do not use tabs.
			* Do not leave whitespace at the end of lines ("trailing spaces").

	~~TODO One section per version~~.		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 ===		=== Version section start ===
	The line must be exactly <code>---------------------------------------------------------------------------------------------------</code>.		The line must be exactly <code>---------------------------------------------------------------------------------------------------</code>.

	The next line must be a [[#Version]] line.		The next line must be a [[#Version]] line. It cannot be empty.
	=== Version ===		=== Version ===
	The line 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.<br>		The line 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.<br>
Line 49:		Line 44:
	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. This colon is removed for the purpose of display.		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. This colon is removed for the purpose of display.

	This line and ~~the~~ following entry lines are optional.		This line and its following entry lines are optional.

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

Bilka: category information

2022-11-11T15:37:05Z

category information

← Older revision		Revision as of 15:37, 11 November 2022
Line 25:		Line 25:

	=== Version section start ===		=== Version section start ===
	~~Must~~ be exactly <code>---------------------------------------------------------------------------------------------------</code>.		The line must be exactly <code>---------------------------------------------------------------------------------------------------</code>.

	The next line must be a [[#Version]] line.		The next line must be a [[#Version]] line.
	=== Version ===		=== 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.<br>		The line 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.<br>
	The version itself is expected in the format <code>number.number.number</code> for <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.		The version itself is expected in the format <code>number.number.number</code> for <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.

Line 38:		Line 38:
	<code>Version: 0.12.35</code>		<code>Version: 0.12.35</code>
	=== Date ===		=== 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. There are no restrictions for the format of the date itself.		The line 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. There are no restrictions for the format of the date itself.

	There may not be two date lines within the same version section.<br>		There may not be two date lines within the same version section.<br>
Line 47:		Line 47:
	=== Category ===		=== 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~~		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. This colon is removed for the purpose of display.

			This line and the following entry lines are optional.

			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:<br>
			<code>  Minor Features:</code>
	=== Entry ===		=== 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.		The line 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.

			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 in the same version and the same category may not be exact duplicates.		Entries in the same version and the same category may not be exact duplicates.
Line 57:		Line 89:
	Example:<br>		Example:<br>
	<code>    - Fixed the missing title in character logistics window.</code>		<code>    - Fixed the missing title in character logistics window.</code>

	== Example changelog ==		== 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