File size: 7,412 Bytes
ba0c4c4
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
# 🚀 Release Process - BirdNET Uploader Windows Portable

Este documento descreve o fluxo completo para construir, testar e publicar a versão Windows portable do BirdNET Uploader.

## Visão Geral do Fluxo

```
┌──────────────────┐     ┌──────────────────┐     ┌──────────────────┐
│  1. Build Local  │ → │  2. Upload HF    │ → │ 3. Update App    │
│  PyInstaller     │     │  (Dataset)       │     │ Links & Deploy   │
└──────────────────┘     └──────────────────┘     └──────────────────┘
```

## Requisitos

- **Python 3.11+** com `pip` configurado
- **Hugging Face CLI**: `huggingface-cli` instalado
- **Token HF**: Com permissão `write` em dataset (obtenha em https://huggingface.co/settings/tokens)
- **Espaço em disco**: ~3 GB (para build + temp files)
- **Windows 10/11** para build do .exe (ou use CI/CD)

## Passo a Passo

### 1️⃣ Build Local do Executável

```powershell
# Navegar para o diretório do projeto
cd C:\Users\seu_usuario\Documents\Python\BirdNET-Uploader-App

# Instalar dependências de build
python -m pip install -q pyinstaller

# Executar o build (demora ~5-10 minutos)
python build/release_uploader.py --version 1.0.0
```

**Resultado:**
- Arquivo criado: `build/release/birdnet-uploader-1.0.0-windows.zip` (~100 MB)
- Arquivo criado: `build/release/birdnet-uploader-1.0.0-windows.zip.sha256`

### 2️⃣ Criar Dataset no Hugging Face (Primeira Vez)

Acesse https://huggingface.co/new-dataset e configure:

- **Repository name**: `birdnet-uploader-releases`
- **License**: `mit`
- **Private**: Deixe **desmarcado** (público)

### 3️⃣ Upload para Hugging Face

```powershell
# Definir variáveis de ambiente
$env:HF_TOKEN = "hf_xxxxxxxxxxxx"  # Seu token HF

# Executar script de upload
.\scripts\upload_release.ps1 `
  -Version 1.0.0 `
  -RepoId "your-org/birdnet-uploader-releases"
```

Ou usar o script Python direto:

```powershell
python scripts/upload_release_to_hf.py `
  --repo-id your-org/birdnet-uploader-releases `
  --version 1.0.0 `
  --token $env:HF_TOKEN
```

### 4️⃣ Atualizar Links na Aplicação Web

Após upload bem-sucedido, você receberá URLs como:

```
https://huggingface.co/datasets/your-org/birdnet-uploader-releases/resolve/main/releases/v1.0.0/birdnet-uploader-1.0.0-windows.zip
```

**Atualize** [src/uploader/web_ui.py](../src/uploader/web_ui.py):

```python
# Procure por "with gr.Group("Download")" e atualize a URL
new_url = "https://huggingface.co/datasets/your-org/birdnet-uploader-releases/resolve/main/releases/v1.0.0/birdnet-uploader-1.0.0-windows.zip"
```

### 5️⃣ Deploy no Hugging Face Spaces

Se você tem um Space com o app:

```bash
# Commit e push as alterações
git add src/uploader/web_ui.py
git commit -m "Release 1.0.0: Update Windows portable download link"
git push

# O Space será atualizado automaticamente (ou você pode forçar rebuild)
```

## Verificação Pré-Release

Antes de publicar, valide:

### ✅ Teste Local do Executável

```powershell
# Extrair o ZIP
Expand-Archive -Path "build/release/birdnet-uploader-1.0.0-windows.zip" `
  -DestinationPath "temp_test"

# Testar interface web
cd temp_test/birdnet-uploader
.\birdnet-uploader.exe

# Abrir navegador em http://localhost:7860
# Testar login, upload de arquivo pequeno, etc.
```

### ✅ Validar Checksum

```powershell
# Verificar integridade do arquivo
$hash = Get-FileHash -Path "build/release/birdnet-uploader-1.0.0-windows.zip" -Algorithm SHA256
$hash.Hash  # Compare com arquivo .sha256
```

### ✅ Testar Download do HF

```powershell
# Depois do upload, baixar e validar
$url = "https://huggingface.co/datasets/your-org/birdnet-uploader-releases/resolve/main/releases/v1.0.0/birdnet-uploader-1.0.0-windows.zip"

# Download manual via navegador ou curl
curl -L -o test_download.zip $url

# Validar tamanho e integridade
Get-Item test_download.zip | Format-List Length
```

## Estrutura do Dataset HF

Após upload, seu dataset terá esta estrutura:

```
birdnet-uploader-releases/
├── releases/
│   ├── v1.0.0/
│   │   ├── birdnet-uploader-1.0.0-windows.zip
│   │   └── birdnet-uploader-1.0.0-windows.zip.sha256
│   ├── v1.1.0/
│   │   ├── birdnet-uploader-1.1.0-windows.zip
│   │   └── birdnet-uploader-1.1.0-windows.zip.sha256
│   └── README.md (opcional)
└── ...
```

## Automação com GitHub Actions

Para automatizar o build e upload (futuro):

```yaml
# .github/workflows/release.yml
name: Build and Release Windows Portable

on:
  push:
    tags:
      - 'v*.*.*'

jobs:
  build-and-upload:
    runs-on: windows-latest
    
    steps:
      - uses: actions/checkout@v4
      
      - uses: actions/setup-python@v4
        with:
          python-version: '3.11'
      
      - name: Install dependencies
        run: |
          python -m pip install -r requirements.txt
          python -m pip install pyinstaller
      
      - name: Build Windows executable
        run: python build/release_uploader.py --version ${{ github.ref_name }}
      
      - name: Upload to Hugging Face
        env:
          HF_TOKEN: ${{ secrets.HF_TOKEN }}
        run: |
          python scripts/upload_release_to_hf.py `
            --repo-id jrrribeiro/birdnet-uploader-releases `
            --version ${{ github.ref_name }}
```

## Troubleshooting

### Erro: "File not found" durante build

```
Release file not found: build/release/birdnet-uploader-1.0.0-windows.zip
```

**Solução**: Execute `python build/release_uploader.py --version 1.0.0` primeiro.

### Erro: "Authentication failed" durante upload

```
HfApi.upload_file(): Invalid token or insufficient permissions
```

**Solução**:
1. Gere novo token em https://huggingface.co/settings/tokens
2. Certifique-se de ter permissão `write`
3. Execute `huggingface-cli login` novamente

### Executável não abre após download

**Solução**:
1. Desative Windows Defender temporariamente (é falso positivo)
2. Ou execute: `powershell -Command "Unblock-File -Path 'birdnet-uploader.exe'"`

### Arquivo ZIP muito grande (>200 MB)

**Causa**: Dependências desnecessárias incluídas

**Solução**: Atualize `build/pyinstaller_uploader.spec` para excluir módulos desnecessários:

```python
# No spec file, adicione em excludes:
excludes=['PIL', 'scipy', 'sklearn', 'torch', ...]
```

## Documentação para Usuários

Após publicar, compartilhe o [WINDOWS_PORTABLE_SETUP.md](./WINDOWS_PORTABLE_SETUP.md) com instruções de instalação.

## Checklist de Release

- [ ] Build local completado sem erros
- [ ] Teste do executável realizado
- [ ] Checksum verificado
- [ ] Dataset criado no HF (primeira vez)
- [ ] Upload concluído com sucesso
- [ ] Links atualizados em `src/uploader/web_ui.py`
- [ ] Changes commitadas e pushed
- [ ] Space/App atualizado
- [ ] Documentação atualizada
- [ ] Versão marcada no Git (git tag v1.0.0)

## Versioning

Use **Semantic Versioning**:
- **Major.Minor.Patch** (ex: 1.0.0, 1.1.0, 1.1.1)
- Major: Mudanças incompatíveis
- Minor: Novo recurso compatível
- Patch: Bugfix compatível

## Suporte

Dúvidas? Abra uma issue em: https://github.com/jrrribeiro/BirdNET-Uploader-App/issues