# Patch Note Generation Process

This document describes how to generate patch notes when comparing two Hytale server versions in `src-ref/`.

## Prerequisites

- Git repository with decompiled Hytale server sources
- Two tagged commits representing different Hytale versions

## Naming Convention

Patch note files follow this format:
```
{OLD_VERSION}-{NEW_VERSION}.note.md
```

Example: `2026.01.13-dcad8778f-2026.01.13-50e69c385.note.md`

## Step-by-Step Process

### 1. Identify the commits to compare

```bash
cd src-ref/
git log --oneline -10
```

Output example:
```
e1c1f50b 2026.01.13-50e69c385
604fbb28 Initial commit HY#2026.01.13-dcad8778f
```

### 2. Get overall diff statistics

```bash
# Overall stats
git diff --stat OLD_COMMIT NEW_COMMIT -- "com/hypixel/hytale/**" | tail -5

# Count total files changed
git diff --stat OLD_COMMIT NEW_COMMIT -- "com/hypixel/hytale/**" | wc -l
```

### 3. Identify modified files (not added)

```bash
git diff --diff-filter=M --name-only OLD_COMMIT NEW_COMMIT -- "com/hypixel/hytale/**"
```

These are the files that **changed** between versions - they need detailed analysis.

### 4. Identify added files

```bash
# List all added files
git diff --diff-filter=A --name-only OLD_COMMIT NEW_COMMIT -- "com/hypixel/hytale/**"

# Count added files by directory
git diff --diff-filter=A --name-only OLD_COMMIT NEW_COMMIT -- "com/hypixel/hytale/**" | \
  cut -d'/' -f4-6 | sort | uniq -c | sort -rn | head -30
```

### 5. Identify deleted files

```bash
git diff --diff-filter=D --name-only OLD_COMMIT NEW_COMMIT -- "com/hypixel/hytale/**"
```

### 6. Compare package structure

```bash
# Packages in OLD version
git ls-tree --name-only -r OLD_COMMIT -- "com/hypixel/hytale/" | cut -d'/' -f4 | sort -u

# Packages in NEW version
git ls-tree --name-only -r NEW_COMMIT -- "com/hypixel/hytale/" | cut -d'/' -f4 | sort -u
```

### 7. Analyze modified files in detail

For each modified file, get the actual diff:

```bash
git diff OLD_COMMIT NEW_COMMIT -- "path/to/modified/File.java"
```

### 8. Categorize new systems

Count files by top-level package:

```bash
git diff --diff-filter=A --name-only OLD_COMMIT NEW_COMMIT -- "com/hypixel/hytale/builtin/**" | \
  cut -d'/' -f5 | sort | uniq -c | sort -rn
```

## Patch Note Template

```markdown
# Patch Notes: {OLD_VERSION} -> {NEW_VERSION}

## Summary

| Type | Count |
|------|-------|
| Files Added | X |
| Files Modified | X |
| Files Deleted | X |

---

## Modified Files

### FileName.java
**Path:** `package/path/FileName.java`

Description of what changed...

```java
// Code snippet showing the change
```

---

## New Features & Systems

### 1. System Name (X files)
**Path:** `package/path/`

Description...

| Subpackage | Files | Description |
|------------|-------|-------------|
| `sub1/` | X | What it does |
| `sub2/` | X | What it does |

---

## Deleted Files

(List any removed files/systems)

---

## Security Improvements

(List any security-related changes)

---

*Generated from git diff between tags `OLD_TAG` and `NEW_TAG`*
```

## Useful Git Commands Reference

| Command | Purpose |
|---------|---------|
| `git diff --diff-filter=A` | Show only added files |
| `git diff --diff-filter=M` | Show only modified files |
| `git diff --diff-filter=D` | Show only deleted files |
| `git diff --stat` | Show statistics (insertions/deletions) |
| `git diff --name-only` | Show only file names |
| `git ls-tree -r COMMIT` | List all files at a commit |
| `git show COMMIT:path/file` | Show file content at specific commit |

## Notes

- Always filter to `com/hypixel/hytale/**` to exclude external libraries
- External libraries (com/google, org/jline, etc.) are not relevant for documentation
- Focus on `server/core/` for API changes that affect plugin developers
- New `builtin/` packages are gameplay systems (may not have public APIs)