Migration file order

[beco]

Hello guys!

I'm a new modder and since I'm also a professor I intend to broad the audience of the game by teaching about it. As a first mod I created (not completely ready yet) the woodcarbonization recipe ( https://mods.factorio.com/mod/woodcarbonization ).

When I created it, it conflict my first choice of name for the recipe, that I discovered only later when I tried to upload to the mods page. And so, as many Modders have to deal with migration sooner or later, I was gifted with the sooner deal.

I created a simple migration to change the recipe name from carbonization to woodcarbonization and I saved it in the file:

Code: Select all

migrations/20230122-migration.json

All good for now. But it got me wondering... The page https://lua-api.factorio.com/latest/Migrations.html explains that migration files are read by lexicographical order, but did not explain if ascending or descending order.

Suppose in the future I create a new file, say a month from now, named

Code: Select all

migrations/20230201-migration.json

Will that scheme works to read both files in the correct order. I suppose we would want to read first the January 22 file, and after that the February 1st file, right?

[DaveMcW]

It uses ascending order.

[FuryoftheStars]

I don't remember where I learned it, and I don't know if this is the "correct" way or if it's inconsequential, but I had learned to name the migration files as "mod-name_version", where version matched the mod version it's introduced with.

As such, as DaveMcW said, I believe it is ascending order.

[beco]

Thanks for your concise reply Dave.

Now with that out of the way (ascending order), with that nomenclature scheme, is that the order we want the game to apply our patches?

I suppose so.

For example, if some name changes twice, say:

carbonization -> woodcarbonization -> wood-carbonization

we want the files to have:

* 20230122 : carbonization -> woodcarbonization
* 20230201 : woodcarbonization -> wood-carbonization

And the ascending order is to apply first 20230122 and next 20230201.

Because if we try the other way around, a player with an old version will not migrate correctly.

That is, if we call the files

* zzz-20230122 : carbonization -> woodcarbonization
* aaa-20230201 : woodcarbonization -> wood-carbonization

this is not going to end well.

So, I guess by luck I used a good scheme after all. Agreed?

[beco]

I don't remember where I learned it, and I don't know if this is the "correct" way or if it's inconsequential, but I had learned to name the migration files as "mod-name_version", where version matched the mod version it's introduced with.

As such, as DaveMcW said, I believe it is ascending order.

This is a nice scheme, FuryoftheStar. Good to know!

As the version is also a monotonic ascending number, just like YYYY-MM-DD, I believe both schemes are pratically the same in the end. Thanks for sharing this idea.

[Optera]

I copied the way Factorio does it's migrations:

At major versions merge migrations into one file. In the above example:
carbonization -> wood-carbonization
woodcarbonization -> wood-carbonization

After several major versions it's also reasonable to no longer support direct migration.

[Xorimuth]

I don't remember where I learned it, and I don't know if this is the "correct" way or if it's inconsequential, but I had learned to name the migration files as "mod-name_version", where version matched the mod version it's introduced with.

As such, as DaveMcW said, I believe it is ascending order.

I don’t believe this solution always works correctly, since 1.2.30 will sort before 1.2.4. Using dates is the best method.

[Pi-C]

I had learned to name the migration files as "mod-name_version", where version matched the mod version it's introduced with.

I don’t believe this solution always works correctly, since 1.2.30 will sort before 1.2.4. Using dates is the best method.

Except that there are different date formats in use. While dates would work well for people from a culture where the YY[YY]-MM-DD notation is used, it may be different (depending on the date) for people accustomed to formats like DD-MM-YY[YY].

[Xorimuth]

I had learned to name the migration files as "mod-name_version", where version matched the mod version it's introduced with.

I don’t believe this solution always works correctly, since 1.2.30 will sort before 1.2.4. Using dates is the best method.

Except that there are different date formats in use. While dates would work well for people from a culture where the YY[YY]-MM-DD notation is used, it may be different (depending on the date) for people accustomed to formats like DD-MM-YY[YY].

I was taking it as read that YYYY-MM-DD would be used, since yes, it is the standard date format for use in software, when lexicographical ordering is useful.

[beco]

Except that there are different date formats in use. While dates would work well for people from a culture where the YY[YY]-MM-DD notation is used, it may be different (depending on the date) for people accustomed to formats like DD-MM-YY[YY].

It is not really a "cultural" thing. In my country the date is DD/MM/YY if you go for "culture". The YYYY-MM-DD is a "programmatic" thing, where you use the mathematical property of the ever-growing number. Programmers have their own culture, I guess.