# Auto Generate Update Pack Guide

This page explains how to use the workflows under `tools/update-pack` to generate DLC hot-update packages.

## This Wiki only support Version `3.6.5` and above of DLC Manager.

## 1. Preparation
- First, create your modpack repository from this template: [Github Link](https://github.com/CoZooo/Modpack-Template)
- Make sure `version.dc` exists under `DLC/info/` (or another path if you set `VERSION_DC_PATH`), used to store current `base` and `dlc` versions.
- Add the files and directories (path) you want to ignore changes to `.gitignore`.
- Optional: add one of the following files in the repository root as update notes:
  - `changelog`, `CHANGELOG`

### Recommended: GitHub Desktop
It is recommended to manage the repository with GitHub Desktop.

Steps:
1. Install [GitHub Desktop](https://desktop.github.com/) and sign in with your GitHub account.
2. Open your modpack repository in GitHub Desktop (`File -> Add local repository...` or `Clone`).
3. Continue normal commit/push in GitHub Desktop.

### Optional: Enable Git LFS (Large Files)
If your repository includes large files (above 100MB, such as `.jar` and `.zip`), it is recommended to enable Git LFS.

Steps:
1. Open terminal from GitHub Desktop (`Repository -> Open in Terminal`) and run:
   ```bash
   git lfs install
   git lfs track "*.jar"
   git lfs track "*.zip"
   ```
2. Commit and push the generated `.gitattributes` file.

Note:
- For new collaborators, run `git lfs pull` after first clone to ensure real files are downloaded instead of pointer files.

## 2. Auto Generate Update Package
Workflow: `auto-generate-update-pack.yml`

Trigger methods:
- Automatically triggered on push to `main`.
- Can also be run manually.

In auto mode, an update package is generated only when a version change is detected in `version.dc`.

### Repository Variables
- `AUTO_UPDATE_WORKFLOW`
  - Purpose: whether push-triggered auto generation is enabled.
  - Allowed: `false` / `true`
  - Default: `true`
- `VERSION_DC_PATH`
  - Purpose: path to `version.dc`.
  - Default: `DLC/info/version.dc`
- `CLIENT_BRANCH`
  - Purpose: branch names treated as client package in auto push mode.
  - Format: comma-separated branch names, case-insensitive.
  - Example: `client,client-release,feature-client`
- `SERVER_BRANCH`
  - Purpose: branch names treated as server package in auto push mode.
  - Format: comma-separated branch names, case-insensitive.
  - Example: `server,server-release,feature-server`
- `AUTO_UPDATE_PLATFORM`
  - Purpose: platform used in auto mode.
  - Allowed: `universal` / `client` / `server`
  - Default: `universal`
- `AUTO_SYNC_TO_GITEE`
  - Purpose: whether to sync to Gitee in auto mode.
  - Allowed: `false` / `true`
  - Default: `false`
- `AUTO_SYNC_TO_GITCODE`
  - Purpose: whether to sync to GitCode in auto mode.
  - Allowed: `false` / `true`
  - Default: `false`

## 3. Gitee Sync
Workflow: `sync-github-release-to-gitee.yml`

### Required Configuration
Repository Variables:
- `GITEE_USERNAME`: Gitee username
- `GITEE_REPO`: Gitee repository name
- `GITEE_SYNC_FILE`: whether to sync release assets by default in this workflow. Default: `false`

Secrets:
- `GITEE_TOKEN`: Gitee access token

## 4. GitCode Sync
Workflow: `sync-github-release-to-gitcode.yml`

### Required Configuration
Repository Variables:
- `GITCODE_USERNAME`: GitCode username
- `GITCODE_REPO`: GitCode repository name
- `GITCODE_SYNC_FILE`: whether to sync release assets by default in this workflow. Default: `false`

Secrets:
- `GITCODE_TOKEN`: GitCode access token

## 5. Manual Generate Update Package
Workflow: `generate-update-pack.yml`

Required inputs:
- `from_ref`
  - Purpose: diff start point.
  - Allowed: tag / commit / branch.
  - Can be empty: system auto-selects a valid start point.
- `to_ref`
  - Purpose: diff end point.
  - Allowed: tag / commit / branch.
  - Default when empty: latest commit (`HEAD`).
- `platform`
  - Purpose: target platform of the update package.
  - Allowed: `universal` / `client` / `server`.
- `base`
  - Purpose: base-pack version before update.
  - Example: `3.12.0`
- `base_new`
  - Purpose: base-pack version after update.
  - Example: `3.12.1`
- `dlc`
  - Purpose: DLC version before update.
  - Example: `1.0.0`
- `dlc_new`
  - Purpose: DLC version after update.
  - Example: `1.0.1`
- `sync_to_gitee`
  - Purpose: whether to sync to Gitee after publishing to GitHub.
  - Allowed: `false` / `true`
- `sync_to_gitcode`
  - Purpose: whether to sync to GitCode after publishing to GitHub.
  - Allowed: `false` / `true`

Note:
- `base/base_new` and `dlc/dlc_new` cannot both stay unchanged, or the workflow exits with an error.

## from_ref / to_ref Input Notes
- `to_ref`
  - Usually leave it empty to use latest commit (`HEAD`).
  - When needed, fill with a branch name, tag, or commit hash.
- `from_ref`
  - Specifies where the diff starts.
  - Common choices:
    - Previous hot-update tag (recommended).
    - A historical commit (if you only want a subset of commits).
    - A branch or tag name.
  - When empty, a valid diff base is selected automatically.