NewGRF compatibility

In the course of writing a NewGRF you probably will release not only one version but you may want to provide a bug fix version or versions which add additional features to your existing NewGRF. There are various pitfalls though when it comes to keeping a NewGRF compatible with its previous versions. This page tries to list some of the most common pitfalls and changes to a NewGRF which break compatibility

Dangerous changes

Removing or changing the ID of an existing vehicle, house, industry, airport, station or industry tile or object

If you haven't defined explicitly any IDs: always add new items to the end of the list, the new vehicle is the last vehicle of that type, the new tiletype the last tiletype, the new industry the last industry; don't comment out an existing one or re-sort the items
Removing or changing a label of a railtype which was provided in an earlier version
Changing the track / non-track status of a station tile
Limiting vehicle properties, most notably the availability, capacities, cargo refit, climates, track type, powered status... (extending availability or adding additional cargos, increasing capacity,... is safe, though)
Changing the length of a vehicle (e.g. from 7/8 to 8/8 or similar).

How to avoid breaking compatibility

Tips: when you need to change a vehicle (or other thing, works also with tiles, industries objects and houses and alike) such that you break compatibility there is a way to avoid breaking compatibility:

Copy the vehicle which shall be changed and add it as a new vehicle with a new, so-far unused ID
Set the climate availability of the existing vehicle to 0.

This will make sure that existing savegames with the old vehicle will keep using it, but it won't be available for purchase anymore and the fixed vehicle will be available instead.

What to do when you have or want to break compatibility

Make use of the grf version and minimum_compatible_version in order to set your grf version and the (minimum) version of your newgrf which you're backward compatible to; set the minimum compatible version to the current version of your NewGRF when you need to break compatibility.