Add mandatory CHANGELOG and update docs/tests

Introduce CHANGELOG.md as the project's source-of-truth and require updating its Unreleased section for every change. Update README, AGENTS.md and documentation (docs/README.md, docs/architecture.md, docs/maintenance.md, docs/testing.md) to reference and enforce the changelog. Add a unit test (tests/test_documentation_structure.py) to assert the changelog exists and contains an "## [Unreleased]" section. The changelog follows Keep a Changelog conventions and includes a 7.4.1 baseline.

Author: rafatosta

AGENTS.md

@@ -1,7 +1,8 @@
 # Guia para agentes de manutenção
 
-Antes de alterar o ZapZap, leia `docs/README.md`, `docs/architecture.md`,
-`docs/maintenance.md` e a seção pertinente de `docs/testing.md`.
+Antes de alterar o ZapZap, leia `CHANGELOG.md`, `docs/README.md`,
+`docs/architecture.md`, `docs/maintenance.md` e a seção pertinente de
+`docs/testing.md`.
 
 - Preserve comportamento, chaves e valores persistidos; migre explicitamente
   quando uma mudança for inevitável.
@@ -11,6 +12,9 @@ Antes de alterar o ZapZap, leia `docs/README.md`, `docs/architecture.md`,
 - Mantenha IDs persistidos separados de rótulos traduzidos.
 - Audite páginas, backends e plataformas irmãs quando a mudança for transversal.
 - Não considere `offscreen` prova de foco, cursor, compositor ou aparência real.
+- Registre obrigatoriamente toda mudança ou adição na seção `Unreleased` de
+  `CHANGELOG.md`, inclusive documentação, testes, manutenção interna,
+  dependências, empacotamento e workflows.
 - Não conclua uma alteração estrutural sem atualizar a documentação técnica e
   seus inventários marcados no mesmo conjunto de mudanças.
 

CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All changes and additions to ZapZap are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/2.0.0/).
+Every pull request or commit that changes the repository must add or update an
+entry under `Unreleased`, including internal, documentation, test, packaging,
+and workflow changes.
+
+This mandatory record starts after version 7.4.1. The 7.4.1 entry below is the
+historical baseline; older release summaries remain available in the GitHub
+releases and the AppStream metadata.
+
+## [Unreleased]
+
+### Added
+
+- Added this changelog as the mandatory source of truth for all project changes
+  and additions.
+
+## [7.4.1] - 2026-08-12
+
+### Added
+
+- Added an update indicator with release details and quick access to release
+  notes and downloads.
+
+### Changed
+
+- Improved reliability when ZapZap is closed by the operating system.
+- Included performance improvements.
+
+[Unreleased]: https://github.com/rafatosta/zapzap/compare/7.4.1...HEAD
+[7.4.1]: https://github.com/rafatosta/zapzap/releases/tag/7.4.1

README.md

@@ -75,6 +75,8 @@ Every contribution helps keep ZapZap free, maintained, and continuously improvin
 
 Architecture, maintenance procedures and automated-test instructions are
 available in the [technical documentation](docs/README.md).
+All project changes and additions are recorded in the
+[changelog](CHANGELOG.md).
 
 ## License
 ZapZap is licensed under the GNU General Public License v3.0 or later. See [LICENSE](LICENSE) for the full license text.

docs/README.md

@@ -31,6 +31,7 @@ Inventário de documentos técnicos:
 
 | Assunto | Fonte de verdade |
 |---|---|
+| Alterações e histórico de versões | `CHANGELOG.md` |
 | Pacotes distribuídos | `pyproject.toml`, seção `tool.setuptools.packages` |
 | Arquitetura e responsabilidades | `docs/architecture.md` |
 | Configurações persistidas | classes de domínio em `zapzap/core/config/settings/` |
@@ -40,7 +41,13 @@ Inventário de documentos técnicos:
 | Testes automatizados | `tests/test_*.py` |
 | Builds e releases | `.github/workflows/` e `.github/packaging/` |
 
-## Regra de atualização
+## Regras de atualização
+
+Toda mudança ou adição ao repositório deve atualizar obrigatoriamente a seção
+`Unreleased` de `CHANGELOG.md` no mesmo commit ou pull request. Essa exigência
+também se aplica a documentação, testes, manutenção interna, dependências,
+empacotamento e workflows; o histórico Git e as notas geradas pelo GitHub não
+substituem o registro curado.
 
 Uma alteração estrutural não está completa sem atualizar esta documentação.
 Isso inclui adicionar, remover, renomear ou mover pacotes, funcionalidades,

docs/architecture.md

@@ -395,6 +395,7 @@ arquitetura no nome final do artefato.
 
 | Caminho | Conteúdo |
 |---|---|
+| `CHANGELOG.md` | fonte obrigatória de todas as mudanças e adições do projeto |
 | `zapzap/` | código Python distribuído e catálogos `.mo` de runtime |
 | `tests/` | testes `unittest`, fixture Qt e verificações estáticas |
 | `docs/` | documentação técnica e contratos de manutenção |

docs/maintenance.md

@@ -27,6 +27,8 @@ dados reais para testes destrutivos de conta, cache ou configurações.
    legadas.
 5. Considere Linux/Flatpak, Linux nativo, Windows e macOS quando a mudança tocar
    integração de sistema.
+6. Planeje a entrada correspondente em `CHANGELOG.md`; nenhuma mudança ou
+   adição está dispensada desse registro.
 
 ## Matriz de impacto
 
@@ -261,6 +263,36 @@ Repita para cada catálogo alterado e gere os `.mo` que o pacote distribui.
   mascarar um import anterior por monkeypatch posterior.
 - Consulte `docs/memory-benchmark.md` para cenários, schema e interpretação.
 
+## Registro obrigatório de mudanças
+
+`CHANGELOG.md`, na raiz do repositório, é a fonte de verdade do histórico do
+ZapZap. Toda mudança ou adição deve atualizar a seção `Unreleased` no mesmo
+commit ou pull request. A regra inclui funcionalidades, correções, mudanças de
+comportamento, documentação, testes, refatorações, dependências, ferramentas,
+empacotamento e workflows.
+
+Use as categorias `Added`, `Changed`, `Deprecated`, `Removed`, `Fixed` e
+`Security`. Escreva entradas curtas que expliquem o efeito da mudança; para
+trabalho interno, descreva o impacto na manutenção, confiabilidade, desempenho
+ou processo de entrega. Não copie o `git log` e não considere commits, pull
+requests ou notas automáticas do GitHub substitutos do changelog.
+
+Ao preparar uma release:
+
+1. revise todas as entradas acumuladas desde a versão anterior;
+2. transforme `Unreleased` em uma seção com versão e data no formato
+   `YYYY-MM-DD`;
+3. crie uma nova seção `Unreleased` vazia;
+4. atualize os links de comparação no final do arquivo;
+5. use a seção da versão como base para as notas do GitHub Release.
+
+O bloco `<releases>` de
+`share/metainfo/com.rtosta.zapzap.appdata.xml` existe somente para a publicação
+no Flathub. Ele não é a fonte do histórico e não precisa ser atualizado a cada
+mudança. Na preparação de uma release do Flatpak, atualize-o manualmente com um
+resumo curto e voltado ao usuário, derivado das entradas de `CHANGELOG.md`
+acumuladas entre a versão anterior e a nova.
+
 ## Contrato de documentação estrutural
 
 Toda alteração estrutural deve atualizar os documentos no mesmo commit ou pull
@@ -334,10 +366,12 @@ Workflows mantidos:
 - `release-deploy.yml`
 <!-- structure-check:workflows:end -->
 
-Antes de uma release, revise a versão em `zapzap/__init__.py`, metadados
-AppStream em `share/metainfo/`, artefatos desktop/ícone, catálogos compilados e
-histórico real de mudanças. Valide XML/AppStream e o manifesto Flatpak com as
-ferramentas disponíveis; avisos do Flathub podem bloquear a publicação.
+Antes de uma release, revise a versão em `zapzap/__init__.py`, consolide a
+seção correspondente de `CHANGELOG.md` e verifique artefatos desktop/ícone e
+catálogos compilados. Quando houver publicação no Flathub, produza manualmente
+um resumo do changelog no bloco `<releases>` dos metadados AppStream em
+`share/metainfo/`; valide então XML/AppStream e o manifesto Flatpak com as
+ferramentas disponíveis, pois avisos do Flathub podem bloquear a publicação.
 
 No AppImage, o nome publicado deve ser definido antes da geração do arquivo
 `.zsync`. O script de geração fornece o basename final ao `quick-sharun` pela
@@ -371,5 +405,6 @@ publicação de cada release.
 - [ ] `python tests/check_unused_code.py --packages-only` passa;
 - [ ] `python -m compileall -q zapzap tests tools run.py` passa;
 - [ ] `git diff --check` passa;
+- [ ] toda mudança ou adição foi registrada em `CHANGELOG.md`;
 - [ ] documentação estrutural e inventários foram atualizados;
 - [ ] foi feita validação gráfica real quando `offscreen` não é suficiente.

docs/testing.md

@@ -85,7 +85,7 @@ documente o que ele protege.
 | `test_deeplink.py` | validação de URLs WhatsApp e resistência a injeção de script |
 | `test_desktop_application_dbus.py` | interface `org.freedesktop.Application` e ativação D-Bus |
 | `test_dictionary_options.py` | descoberta dinâmica, nomes amigáveis, ordenação, redimensionamento e fallback de dicionários personalizados |
-| `test_documentation_structure.py` | camadas de UI e sincronização entre árvore, inventários técnicos e guia para agentes |
+| `test_documentation_structure.py` | camadas de UI, contrato mínimo do changelog e sincronização entre árvore, inventários técnicos e guia para agentes |
 | `test_donations_page.py` | URLs HTTPS oficiais, fallback externo, cartões responsivos/acessíveis, troca imediata de idioma e rota única pela sidebar, Configurações e Sobre |
 | `test_external_link_lifecycle.py` | descarte da página WebEngine transitória após abrir links externos |
 | `test_gpu_environment.py` | detecção multi-GPU, conectores e seleção de render node |

tests/test_documentation_structure.py

@@ -17,6 +17,7 @@
 TESTING_PATH = DOCS_ROOT / "testing.md"
 DOCS_INDEX_PATH = DOCS_ROOT / "README.md"
 AGENT_GUIDE_PATH = REPOSITORY_ROOT / "AGENTS.md"
+CHANGELOG_PATH = REPOSITORY_ROOT / "CHANGELOG.md"
 
 
 def documented_inventory(path: Path, name: str) -> list[str]:
@@ -103,6 +104,7 @@ def test_maintenance_entry_points_are_documented(self):
     def test_agent_guide_points_to_the_maintenance_contract(self):
         guide = AGENT_GUIDE_PATH.read_text(encoding="utf-8")
         for required_reference in (
+            "CHANGELOG.md",
             "docs/README.md",
             "docs/architecture.md",
             "docs/maintenance.md",
@@ -112,6 +114,10 @@ def test_agent_guide_points_to_the_maintenance_contract(self):
             with self.subTest(reference=required_reference):
                 self.assertIn(required_reference, guide)
 
+    def test_changelog_keeps_an_unreleased_section(self):
+        changelog = CHANGELOG_PATH.read_text(encoding="utf-8")
+        self.assertIn("## [Unreleased]", changelog)
+
 
 if __name__ == "__main__":
     unittest.main()