docs: prepare Pakker documentation
Signed-off-by: NotAShelf <raf@notashelf.dev> Change-Id: I03df3787081bde6ebf0366a24320307a6a6a6964
This commit is contained in:
parent
563ff2b187
commit
5a0a5cedeb
GPG key ID:
29D95B64378DB4BF
4 changed files with 2285 additions and 0 deletions
511
docs/MIGRATION.md
Normal file
511
docs/MIGRATION.md
Normal file
|
|
@ -0,0 +1,511 @@
|
|||
# Migrating from Pakku to Pakker
|
||||
|
||||
This guide helps you migrate from Pakku (Kotlin) to Pakker (Rust).
|
||||
|
||||
## Overview
|
||||
|
||||
Pakker is designed to be largely compatible with Pakku, maintaining the same configuration format and workflow. Most Pakku modpacks can be imported directly into Pakker with minimal changes.
|
||||
|
||||
## Key Differences
|
||||
|
||||
### Performance
|
||||
|
||||
- **Faster execution** - Rust implementation provides significant speed improvements
|
||||
- **Lower memory usage** - More efficient resource utilization
|
||||
- **Parallel operations** - Better concurrency for downloads and processing
|
||||
|
||||
### Enhanced Features
|
||||
|
||||
- **Non-interactive mode** - `add-prj` command for CI/CD workflows
|
||||
- **Advanced inspection** - Enhanced `inspect` command with dependency trees
|
||||
- **Export profiles** - More flexible profile-based export configuration
|
||||
- **Platform filtering** - Automatic platform-specific mod filtering
|
||||
|
||||
### Compatibility
|
||||
|
||||
✅ **Compatible**:
|
||||
- Configuration format (`pakku.json`)
|
||||
- Lockfile format (`pakku-lock.json`)
|
||||
- Export formats (CurseForge ZIP, Modrinth .mrpack)
|
||||
- Override directory structure
|
||||
- Project properties and metadata
|
||||
|
||||
⚠️ **Differences**:
|
||||
- Some CLI flag names (documented below)
|
||||
- New features not in Pakku
|
||||
- Performance characteristics
|
||||
|
||||
## Quick Migration
|
||||
|
||||
### Step 1: Import Existing Modpack
|
||||
|
||||
If you have an existing Pakku modpack:
|
||||
|
||||
```bash
|
||||
# Navigate to your modpack directory
|
||||
cd my-modpack
|
||||
|
||||
# Pakker will use existing pakku.json and pakku-lock.json
|
||||
pakker ls
|
||||
```
|
||||
|
||||
That's it! Pakker reads the same configuration files.
|
||||
|
||||
### Step 2: Verify Projects
|
||||
|
||||
```bash
|
||||
# List all projects
|
||||
pakker ls
|
||||
|
||||
# Inspect specific projects
|
||||
pakker inspect sodium lithium
|
||||
```
|
||||
|
||||
### Step 3: Test Export
|
||||
|
||||
```bash
|
||||
# Export for your target platform
|
||||
pakker export --profile curseforge
|
||||
pakker export --profile modrinth
|
||||
```
|
||||
|
||||
## Configuration Migration
|
||||
|
||||
### pakku.json Format
|
||||
|
||||
Pakker uses the **same format** as Pakku:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "My Modpack",
|
||||
"version": "1.0.0",
|
||||
"description": "A performance modpack",
|
||||
"author": "YourName",
|
||||
"overrides": ["overrides"],
|
||||
"serverOverrides": ["server-overrides"],
|
||||
"clientOverrides": ["client-overrides"]
|
||||
}
|
||||
```
|
||||
|
||||
### Export Profiles
|
||||
|
||||
Pakker extends Pakku's configuration with enhanced export profiles:
|
||||
|
||||
**Pakku format** (still supported):
|
||||
|
||||
```json
|
||||
{
|
||||
"exportProfiles": {
|
||||
"curseforge": {
|
||||
"filterPlatform": "curseforge"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Pakker enhancements** (new features):
|
||||
|
||||
```json
|
||||
{
|
||||
"exportProfiles": {
|
||||
"curseforge": {
|
||||
"filterPlatform": "curseforge",
|
||||
"includeNonRedistributable": false,
|
||||
"overrides": ["overrides", "curseforge-specific"]
|
||||
},
|
||||
"modrinth": {
|
||||
"filterPlatform": "modrinth",
|
||||
"includeNonRedistributable": true
|
||||
},
|
||||
"serverpack": {
|
||||
"includeClientOnly": false,
|
||||
"serverOverrides": ["server-config"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
See [EXPORT_PROFILES.md](./EXPORT_PROFILES.md) for complete documentation.
|
||||
|
||||
## Command Mapping
|
||||
|
||||
Most commands are identical or very similar:
|
||||
|
||||
| Pakku | Pakker | Notes |
|
||||
|-------|--------|-------|
|
||||
| `pakku init` | `pakker init` | Identical |
|
||||
| `pakku import` | `pakker import` | Identical |
|
||||
| `pakku add` | `pakker add` | Identical |
|
||||
| `pakku add` | `pakker add-prj` | New non-interactive variant |
|
||||
| `pakku rm` | `pakker rm` | Identical |
|
||||
| `pakku update` | `pakker update` | Identical |
|
||||
| `pakku ls` | `pakker ls` | Identical |
|
||||
| `pakku status` | `pakker status` | Identical |
|
||||
| `pakku fetch` | `pakker fetch` | Identical |
|
||||
| `pakku export` | `pakker export` | Enhanced with profiles |
|
||||
| `pakku link` | `pakker link` | Identical |
|
||||
| `pakku set` | `pakker set` | Identical |
|
||||
| `pakku cfg` | `pakker cfg` | Identical |
|
||||
| `pakku diff` | `pakker diff` | Identical |
|
||||
|
||||
### New Commands in Pakker
|
||||
|
||||
- `pakker add-prj` - Non-interactive project addition for CI/CD
|
||||
- `pakker inspect` - Enhanced project inspection with dependency trees
|
||||
- `pakker sync` - Combined update + fetch operation
|
||||
- `pakker credentials` - Credential management
|
||||
- `pakker remote` - Git remote management
|
||||
- `pakker fork` - Fork configuration
|
||||
|
||||
## Feature Comparison
|
||||
|
||||
### Project Management
|
||||
|
||||
| Feature | Pakku | Pakker | Notes |
|
||||
|---------|-------|--------|-------|
|
||||
| Add projects | ✅ | ✅ | Enhanced with `add-prj` |
|
||||
| Remove projects | ✅ | ✅ | Identical |
|
||||
| Update projects | ✅ | ✅ | Identical |
|
||||
| List projects | ✅ | ✅ | Identical |
|
||||
| Project properties | ✅ | ✅ | Identical |
|
||||
| Dependencies | ✅ | ✅ | Enhanced inspection |
|
||||
|
||||
### Export System
|
||||
|
||||
| Feature | Pakku | Pakker | Notes |
|
||||
|---------|-------|--------|-------|
|
||||
| CurseForge export | ✅ | ✅ | Identical format |
|
||||
| Modrinth export | ✅ | ✅ | Identical format |
|
||||
| Server pack | ✅ | ✅ | Enhanced filtering |
|
||||
| Export profiles | ✅ | ✅ | Extended features |
|
||||
| Override dirs | ✅ | ✅ | Identical |
|
||||
| Platform filtering | ❌ | ✅ | New in Pakker |
|
||||
| Profile-specific overrides | ❌ | ✅ | New in Pakker |
|
||||
|
||||
### Configuration
|
||||
|
||||
| Feature | Pakku | Pakker | Notes |
|
||||
|---------|-------|--------|-------|
|
||||
| pakku.json | ✅ | ✅ | Same format |
|
||||
| pakku-lock.json | ✅ | ✅ | Same format |
|
||||
| Project config | ✅ | ✅ | Identical |
|
||||
| Export profiles | ✅ | ✅ | Extended in Pakker |
|
||||
|
||||
## Migration Scenarios
|
||||
|
||||
### Scenario 1: Local Development
|
||||
|
||||
**Pakku workflow:**
|
||||
|
||||
```bash
|
||||
pakku init
|
||||
pakku add sodium lithium
|
||||
pakku fetch
|
||||
pakku export
|
||||
```
|
||||
|
||||
**Pakker workflow:**
|
||||
|
||||
```bash
|
||||
pakker init
|
||||
pakker add sodium lithium
|
||||
pakker fetch
|
||||
pakker export --profile modrinth
|
||||
```
|
||||
|
||||
No changes needed!
|
||||
|
||||
### Scenario 2: CI/CD Pipeline
|
||||
|
||||
**Pakku workflow:**
|
||||
|
||||
```bash
|
||||
# Interactive, requires user input
|
||||
pakku add sodium
|
||||
pakku add lithium
|
||||
pakku fetch
|
||||
pakku export
|
||||
```
|
||||
|
||||
**Pakker workflow:**
|
||||
|
||||
```bash
|
||||
# Fully automated
|
||||
pakker add-prj --mr sodium --yes --no-deps
|
||||
pakker add-prj --mr lithium --yes --no-deps
|
||||
pakker update --all --yes
|
||||
pakker fetch
|
||||
pakker export --profile modrinth -o dist/pack.mrpack
|
||||
```
|
||||
|
||||
Benefits: No interactive prompts, perfect for CI/CD.
|
||||
|
||||
### Scenario 3: Multi-Platform Release
|
||||
|
||||
**Pakku workflow:**
|
||||
|
||||
```bash
|
||||
# Manual export for each platform
|
||||
pakku export
|
||||
# Manually select CurseForge
|
||||
pakku export
|
||||
# Manually select Modrinth
|
||||
```
|
||||
|
||||
**Pakker workflow:**
|
||||
|
||||
```bash
|
||||
# Script multiple exports
|
||||
pakker export --profile curseforge -o dist/cf.zip
|
||||
pakker export --profile modrinth -o dist/mr.mrpack
|
||||
pakker export --profile serverpack -o dist/server.zip
|
||||
```
|
||||
|
||||
Benefits: Scriptable, reproducible builds.
|
||||
|
||||
## Migrating CI/CD Workflows
|
||||
|
||||
### GitHub Actions
|
||||
|
||||
**Before (Pakku):**
|
||||
|
||||
```yaml
|
||||
- name: Setup Pakku
|
||||
run: |
|
||||
# Install Pakku
|
||||
|
||||
- name: Build modpack
|
||||
run: |
|
||||
pakku fetch
|
||||
pakku export
|
||||
```
|
||||
|
||||
**After (Pakker):**
|
||||
|
||||
```yaml
|
||||
- name: Setup Pakker
|
||||
run: |
|
||||
# Install Pakker
|
||||
cargo install pakker
|
||||
|
||||
- name: Build modpack
|
||||
run: |
|
||||
pakker fetch
|
||||
pakker export --profile curseforge -o dist/curseforge.zip
|
||||
pakker export --profile modrinth -o dist/modrinth.mrpack
|
||||
```
|
||||
|
||||
### GitLab CI
|
||||
|
||||
**Before (Pakku):**
|
||||
|
||||
```yaml
|
||||
build:
|
||||
script:
|
||||
- pakku fetch
|
||||
- pakku export
|
||||
```
|
||||
|
||||
**After (Pakker):**
|
||||
|
||||
```yaml
|
||||
build:
|
||||
script:
|
||||
- pakker fetch
|
||||
- pakker export --profile curseforge -o curseforge.zip
|
||||
- pakker export --profile modrinth -o modrinth.mrpack
|
||||
artifacts:
|
||||
paths:
|
||||
- "*.zip"
|
||||
- "*.mrpack"
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Projects Not Found After Migration
|
||||
|
||||
**Problem**: Pakker can't find projects that worked in Pakku.
|
||||
|
||||
**Solution**: Verify lockfile format:
|
||||
|
||||
```bash
|
||||
# Check lockfile
|
||||
cat pakku-lock.json
|
||||
|
||||
# Re-fetch projects
|
||||
pakker fetch
|
||||
|
||||
# If issues persist, re-add problematic projects
|
||||
pakker rm problematic-mod
|
||||
pakker add-prj --mr problematic-mod --yes
|
||||
```
|
||||
|
||||
### Export Format Differences
|
||||
|
||||
**Problem**: Exported packs look different.
|
||||
|
||||
**Solution**: Pakker may organize files slightly differently. Both formats are valid:
|
||||
|
||||
```bash
|
||||
# Inspect export
|
||||
unzip -l curseforge.zip
|
||||
|
||||
# Verify manifest
|
||||
jq . manifest.json
|
||||
```
|
||||
|
||||
If needed, configure export profiles to match Pakku behavior exactly.
|
||||
|
||||
### Performance Issues
|
||||
|
||||
**Problem**: Pakker seems slower than expected.
|
||||
|
||||
**Solution**: Pakker should be faster than Pakku. Check:
|
||||
|
||||
```bash
|
||||
# Enable logging
|
||||
pakker -vv fetch
|
||||
|
||||
# Check network connectivity
|
||||
pakker status
|
||||
|
||||
# Verify credentials (for rate limits)
|
||||
pakker credentials
|
||||
```
|
||||
|
||||
### Configuration Not Recognized
|
||||
|
||||
**Problem**: Some configuration options don't work.
|
||||
|
||||
**Solution**: Ensure you're using compatible options:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "My Pack",
|
||||
"version": "1.0.0",
|
||||
"overrides": ["overrides"]
|
||||
}
|
||||
```
|
||||
|
||||
Pakker supports all Pakku options plus new ones. Check [EXPORT_PROFILES.md](./EXPORT_PROFILES.md) for new features.
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Test Before Full Migration
|
||||
|
||||
```bash
|
||||
# Copy modpack to test directory
|
||||
cp -r my-modpack my-modpack-test
|
||||
cd my-modpack-test
|
||||
|
||||
# Test with Pakker
|
||||
pakker ls
|
||||
pakker fetch
|
||||
pakker export --profile modrinth
|
||||
|
||||
# Verify exports match expectations
|
||||
```
|
||||
|
||||
### 2. Update CI/CD Gradually
|
||||
|
||||
1. Test Pakker locally first
|
||||
2. Update a single workflow
|
||||
3. Verify builds succeed
|
||||
4. Roll out to all workflows
|
||||
|
||||
### 3. Use New Features
|
||||
|
||||
Take advantage of Pakker enhancements:
|
||||
|
||||
```bash
|
||||
# Non-interactive project addition
|
||||
pakker add-prj --mr sodium --yes
|
||||
|
||||
# Enhanced inspection
|
||||
pakker inspect sodium
|
||||
|
||||
# Profile-based exports
|
||||
pakker export --profile production -o release.mrpack
|
||||
```
|
||||
|
||||
### 4. Keep Backward Compatibility
|
||||
|
||||
If you need to support both Pakku and Pakker:
|
||||
|
||||
```json
|
||||
{
|
||||
"exportProfiles": {
|
||||
"curseforge": {
|
||||
"filterPlatform": "curseforge"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Use the common subset of features that both support.
|
||||
|
||||
## Getting Help
|
||||
|
||||
### Resources
|
||||
|
||||
- [Pakker Documentation](./README.md)
|
||||
- [Command Reference](./COMMANDS.md)
|
||||
- [Export Profiles](./EXPORT_PROFILES.md)
|
||||
|
||||
### Common Issues
|
||||
|
||||
| Issue | Solution |
|
||||
|-------|----------|
|
||||
| Project not found | Try explicit platform: `pakker add-prj --mr <name>` |
|
||||
| Export fails | Check export profile configuration |
|
||||
| Missing files | Run `pakker fetch` |
|
||||
| Slow performance | Verify network, add credentials |
|
||||
| Config not recognized | Check pakku.json syntax with `jq` |
|
||||
|
||||
### Support Channels
|
||||
|
||||
- GitHub Issues: Report bugs and feature requests
|
||||
- Documentation: Check docs/ directory
|
||||
- Examples: See examples/ directory
|
||||
|
||||
## Migration Checklist
|
||||
|
||||
- [ ] Backup existing modpack directory
|
||||
- [ ] Install Pakker
|
||||
- [ ] Verify `pakker ls` shows all projects
|
||||
- [ ] Test `pakker fetch` downloads files
|
||||
- [ ] Test export for your target platform
|
||||
- [ ] Update CI/CD workflows
|
||||
- [ ] Test automated builds
|
||||
- [ ] Update documentation
|
||||
- [ ] Train team members on new commands
|
||||
- [ ] Monitor for issues
|
||||
|
||||
## Feature Roadmap
|
||||
|
||||
Pakker aims for full Pakku compatibility plus enhancements. If you find missing features, please report them!
|
||||
|
||||
**Current Status:**
|
||||
- ✅ Core functionality (add, remove, update, export)
|
||||
- ✅ Multi-platform support
|
||||
- ✅ Export profiles
|
||||
- ✅ CI/CD workflows
|
||||
- ✅ Dependency resolution
|
||||
|
||||
**Planned:**
|
||||
- Custom export rules
|
||||
- Advanced project filtering
|
||||
- Enhanced remote sync
|
||||
- Plugin system
|
||||
|
||||
## Summary
|
||||
|
||||
Migrating from Pakku to Pakker is straightforward:
|
||||
|
||||
1. **No configuration changes** needed for basic usage
|
||||
2. **Same commands** for most operations
|
||||
3. **Enhanced features** available when ready
|
||||
4. **Better performance** out of the box
|
||||
5. **CI/CD friendly** with non-interactive modes
|
||||
|
||||
Most users can start using Pakker immediately with existing Pakku modpacks!
|
||||
Loading…
Add table
Add a link
Reference in a new issue