Delta Updates for mods hosted at Github

Players: Prerequisite to check and perform updates

• when you extract the mod archive, make sure that every mod has an extra top-level directory

Modders: how to enable:

Simply add the mod metadata file and fill the 'Download = ' keyword with the link to your GitHub repository: https://github.com/ALIENQuake/ProjectInfinity/wiki/Adding-metadata-for-mod

Modders: what is the supported and safe workflow

If you do not use releases, everything below doesn't apply to you but you are encouraged to read this anyway.

tl;dr If you use GitHub releases to ship new versions, after creating a release do not edit it in any way. Yes, that includes manually replacing mod packages or manipulating tags. You can change the title and description.

If the mod is hosted on GitHub and you use releases to ship new versions, there are some things you must not do because bad things will happen.

To not break things, follow the usual Git + GitHub workflow:

1. Update tp2 VERSION keyword, update readme with version, and changelog
2. Create final local commit with all 'ready-to-go' changes
3. Push local commits into a remote repository
4. Create a release via the GitHub web interface or via command-line tools with the same tag as VERSION
5. If you use Infinity Auto Packager, the mod packages will be created automatically and added to the release.

Optionally: You create mod packages that you will later add to the release.

ATTENTION: Any actions, either via a customized version of IAP or manually manipulating the final package, that will result in different package content than the repository itself will break the Project Infinity mods Auto-Update feature. Don't do this.

This is the end of the road. After publishing release, you cannot:

• add other tags to the same release
• remove or replace existing tags
• replace mod packages with new ones that contain changes not present in the repository itself

If you have done ANY modification to the local files, especially if you discover mistakes, you must repeat all of the 'usual Git + GitHub workflow' steps above.

Helpful tools:

There are new tools that will ensure that not only will save you time but ensure you will follow this workflow every time and save you from trivial mistakes.

Mod Release - among other things, it prevents creating "2.0.0" release when your mod version is "1.8.0", prevents creating a new release if there are uncommitted file modifications and prevent overwriting release if it already exists.

Infinity Auto Packager - among other things, it prevents creating mod packages that might contain locally uncommitted changes

How do Delta Updates work?

Delta Updates will only download mod changes, not the whole mod again.
Because it's GitHub-based, it offers stability and consistency. It's impossible to download partial
files: you either download it correctly or don't download it at all, it's how git itself works internally.

How does the update process work?

• The update process doesn't modify mods inside the game directory, only the directory where the user has extracted it
• The update process can be only initiated by the user himself so, as to not break the desired install state
• Custom user-created files inside the mod folder will be removed

Which update channels would be offered for players?

• if the mod doesn't have any releases or prereleases, offer updates for each new commit
• if the mod has even one release, offer an update only if a new release was published
• if the mod has only prereleases, offer an update only if a new prerelease was published
• if the mod has both releases and prereleases, offer updates for releases only, do not offer the update for new prereleases unless there is a global option "Allow for prereleases" enabled