RELEASE_GUIDE.md

🚀 Release Guide - Firewall Port Manager

Hướng dẫn tạo release tự động với GitHub Actions

📋 Tổng quan

Khi bạn tạo git tag với format v*.*.* (ví dụ: v1.0.0), GitHub Actions sẽ tự động:

1. ✅ Build ứng dụng với .NET Framework
2. ✅ Cập nhật version trong AssemblyInfo.cs và MainForm.cs
3. ✅ Tạo package ZIP với tất cả files cần thiết
4. ✅ Tính toán SHA256 hashes để bảo mật
5. ✅ Tạo GitHub Release với mô tả chi tiết
6. ✅ Upload ZIP file và hash file

🛠️ Cách sử dụng

1. Test build local (khuyến nghị)

# Test build với version mặc định (1.0.0)
.\build.ps1

# Test build với version cụ thể
.\build.ps1 -Version "1.2.3"

# Clean build (xóa files cũ trước khi build)
.\build.ps1 -Version "1.2.3" -Clean

2. Tạo release trên GitHub

# Commit tất cả thay đổi
git add .
git commit -m "Release v1.0.0"

# Tạo và push tag
git tag v1.0.0
git push origin v1.0.0

3. Theo dõi build process

1. Vào GitHub repository → Actions tab
2. Xem workflow "Build and Release" đang chạy
3. Kiểm tra logs nếu có lỗi
4. Sau khi hoàn thành, vào Releases để xem kết quả

📁 Cấu trúc Release Package

Mỗi release sẽ chứa:

FirewallPortManager-v1.0.0-Windows.zip
├── FirewallPortManager.exe          # Ứng dụng chính
├── FirewallPortManager.exe.config   # Config file (nếu có)
├── *.dll                           # Dependencies (nếu có)
├── sample_rules.xml                 # Sample XML rules
├── sample_rules.json                # Sample JSON rules
└── README.txt                       # Hướng dẫn cài đặt

🔐 Bảo mật

Mỗi release bao gồm:

• SHA256 hash của ZIP file
• SHA256 hash của executable
• File HASHES.md với thông tin chi tiết

⚙️ Cấu hình nâng cao

Thay đổi workflow

Edit file .github/workflows/release.yml để:

• Thay đổi .NET Framework version
• Thêm/bớt files trong package
• Tùy chỉnh release notes
• Thay đổi naming convention

Thay đổi version format

Workflow hỗ trợ các format tag:

• v1.0.0 → Version: 1.0.0
• v2.1.3 → Version: 2.1.3
• v1.0.0-beta → Version: 1.0.0-beta

Environment variables

Workflow sử dụng:

• GITHUB_TOKEN - Tự động có sẵn
• github.ref_name - Tên tag (v1.0.0)
• github.repository - Tên repository

🐛 Troubleshooting

Build failed

1. NuGet restore failed

   • Kiểm tra packages.config hoặc project references
   • Đảm bảo NuGet packages tồn tại

2. MSBuild failed

   • Kiểm tra syntax errors trong code
   • Đảm bảo .NET Framework version đúng

3. Missing files

   • Kiểm tra file paths trong workflow
   • Đảm bảo sample files tồn tại

Release creation failed

1. Permission denied

   • Kiểm tra repository settings → Actions → General
   • Đảm bảo "Read and write permissions" được bật

2. Tag already exists

   • Xóa tag cũ: git tag -d v1.0.0 && git push origin :refs/tags/v1.0.0
   • Tạo tag mới với version khác

📝 Best Practices

Version numbering

Sử dụng Semantic Versioning:

• v1.0.0 - Major release
• v1.1.0 - Minor update (new features)
• v1.0.1 - Patch (bug fixes)
• v2.0.0-beta - Pre-release

Release notes

Workflow tự động tạo release notes, nhưng bạn có thể:

1. Edit release sau khi tạo
2. Thêm changelog chi tiết
3. Thêm screenshots hoặc demo

Testing

Luôn test local trước khi release:

# Test build
.\build.ps1 -Version "1.0.0" -Clean

# Test executable
.\release\FirewallPortManager.exe

# Verify version
Get-ItemProperty .\release\FirewallPortManager.exe | Select-Object VersionInfo

🔄 Workflow Steps

1. Trigger: Push tag v*.*.*
2. Extract version: v1.0.0 → 1.0.0
3. Update files: AssemblyInfo.cs, MainForm.cs
4. Restore packages: NuGet restore
5. Build: MSBuild Release configuration
6. Package: Copy files to release folder
7. Archive: Create ZIP file
8. Hash: Calculate SHA256
9. Release: Create GitHub release
10. Upload: Attach ZIP and hash files

📞 Support

Nếu gặp vấn đề:

1. Kiểm tra Actions logs trên GitHub
2. Test build local với build.ps1
3. Kiểm tra file permissions và repository settings
4. Tạo issue trên GitHub repository

---

Happy releasing! 🎉