Ir para o conteúdo

Como publicar a extensão Anotae nas lojas

Diátaxis: how-to. Guia passo a passo para mantenedores.

Este guia descreve como empacotar e submeter a extensão Anotae ao Chrome Web Store (Chrome/Edge) e ao Firefox Add-ons (AMO).

A submissão é sempre manual — o workflow release-extension.yml gera os artefatos e os disponibiliza para download, mas nunca envia automaticamente para as lojas.

Pré-requisitos

  • Acesso à conta de desenvolvedor do Chrome Web Store (Google account vinculada ao Developer Dashboard).
  • Acesso ao painel de desenvolvedor do Firefox AMO (conta em accounts.firefox.com com app cadastrado).
  • Node.js 22+ e npm instalados localmente (para validar antes de submeter).
  • web-ext instalado: npm i -g web-ext (ou npx web-ext).

Passo 1 — Preparar a versão

1.1 Atualizar extension/package.json

{
  "version": "0.15.3"
}

Mantenha a versão sincronizada com o app desktop quando a extensão depender de funcionalidades novas. O workflow release-extension.yml valida essa consistência antes de empacotar.

1.2 Atualizar extension/CHANGELOG.md

Documente as mudanças da versão que será publicada sob um novo cabeçalho ## [X.Y.Z] — AAAA-MM-DD.

1.3 Validar localmente

cd extension
npm ci
npm run typecheck
npm test
npm run build:chrome
npm run build:firefox
npx web-ext lint --source-dir dist/firefox --warnings-as-errors

Corrija todos os erros antes de avançar.

Passo 2 — Gerar os artefatos via GitHub Actions

  1. Acesse a aba Actions do repositório no GitHub.
  2. Selecione o workflow Release Extension.
  3. Clique em Run workflow (canto superior direito).
  4. Preencha:
  5. version: ex. 0.15.3 (deve bater com package.json).
  6. dry_run: true para testar sem comprometer; false para release real.
  7. Aguarde a execução.
  8. Na aba Summary do workflow, você verá o checklist de artefatos gerados.
  9. Baixe os artefatos da seção Artifacts:
  10. extension-chrome-0.15.3.zip
  11. extension-firefox-0.15.3.xpi
  12. (arquivos .sha256 de verificação de integridade)

Verificar integridade dos artefatos localmente

sha256sum -c extension-chrome-0.15.3.sha256
sha256sum -c extension-firefox-0.15.3.sha256

Passo 3 — Publicar no Chrome Web Store

  1. Acesse Chrome Web Store Developer Dashboard.
  2. Selecione o app Anotae na lista.
  3. Clique em Package → Upload new package.
  4. Faça o upload do arquivo .zip gerado.
  5. Preencha / revise:
  6. Short description (≤ 132 chars): descritiva, sem palavras proibidas.
  7. Detailed description: português brasileiro, mencionar que é 100% offline e open-source (AGPL-3.0).
  8. Screenshots: mínimo 1, máximo 5 (1280×800 ou 640×400 px).
  9. Category: Productivity.
  10. Privacy practices: declarar que a extensão não coleta dados de usuário (porque é 100% local).
  11. Clique em Submit for review.
  12. Tempo de revisão: 1-3 dias úteis para extensões novas; horas para atualizações.

Pontos de atenção para aprovação

  • Permissions justification: a extensão usa nativeMessaging (comunicação com o app desktop) e tabs (detectar URL ativa). O reviewer pode pedir justificativa — descreva que não há envio de dados para servidores externos.
  • Privacy policy URL: aponte para https://anot.ae/privacy ou para o arquivo PRIVACY-IMPACT-ASSESSMENT.md no GitHub (se o site ainda não estiver no ar).
  • Two-factor authentication: obrigatório para conta de desenvolvedor Chrome.

Passo 4 — Publicar no Firefox Add-ons (AMO)

  1. Acesse Firefox Add-ons Developer Hub.
  2. Selecione o add-on Anotae ou clique em Submit a New Add-on.
  3. Selecione On this site (hosted by Mozilla).
  4. Faça o upload do arquivo .xpi.
  5. Preencha / revise:
  6. Name: Anotae
  7. Summary (≤ 250 chars): breve e precisa.
  8. Description: português, mencionar open-source (AGPL-3.0), 100% local.
  9. Categories: Productivity.
  10. Privacy policy: mesma URL da seção anterior.
  11. Add-on flags: "This add-on requires extra review" — marque se usar nativeMessaging (a Mozilla revisa manualmente extensões com essa permissão).
  12. Na seção Source code, faça upload do código-fonte completo (tarball do repositório ou somente extension/). A Mozilla exige código-fonte para extensões com código minificado.
  13. Clique em Submit Version.
  14. Aguarde a revisão: pode levar 1-10 dias úteis.

Dica: upload do código-fonte

# Na raiz do repositório:
tar -czf anotae-extension-src-0.15.3.tar.gz \
  extension/ \
  --exclude='extension/node_modules' \
  --exclude='extension/dist'

Passo 5 — Pós-publicação

  1. Documente a data de submissão e aprovação em extension/CHANGELOG.md.
  2. Crie uma entrada no CHANGELOG.md principal do repositório.
  3. Anuncie na comunidade/issues do GitHub.
  4. Atualize os links de instalação no README.md principal e no site https://anot.ae.

Troubleshooting

Chrome Web Store rejeita com "Violation: Deceptive behavior"

A extensão declara permissões que o reviewer não consegue mapear a funcionalidades observáveis. Adicione screenshots demonstrando cada permissão em uso e revise a descrição para ser explícita sobre o que cada permissão faz.

Firefox AMO rejeita por "lacks a privacy policy"

Certifique-se de que a URL da política de privacidade está preenchida e acessível publicamente (não requer login).

web-ext lint falha com "manifestVersion 3 is not supported"

Instale a versão mais recente: npm i -g web-ext@latest. A partir da versão 7.x, o web-ext suporta Manifest V3 para Firefox.

Upload do .zip Chrome falha silenciosamente

O Chrome Web Store tem limite de 10 MB para o .zip. Se o build incluir assets pesados, revise o vite.config.ts para excluí-los.

Recursos