Delta Updates for mods hosted at Github

Players: Prerequisite in order to check and perform updates

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

Modders: how to enable:

Simply add 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 accepted 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: Package content must be the same as the repository contents for the given release tag. Otherwise, the Project Infinity Auto-Update system will reset the mod state to the tag from the latest release.

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 creating a new release if the same release already exists.

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

How Delta Updates works?

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 the update from supported websites is performed:

• the update process doesn't modify mods inside the game directory, only the directory where the user has extracted it
• update process can be only initiated by the user himself, in order 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 prerelease, 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