Documentation/patch-note-process.md

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

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

# 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)

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

# 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

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

6. Compare package structure

# 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:

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

8. Categorize new systems

Count files by top-level package:

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

# 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)