Philip Withnall
philip@tecnocode.co.uk
Will Thompson
wjt@endlessos.org
Milan Crha
mcrha@redhat.com
Como o Programas usa metadados
Rafael Fontenelle
rafaelff@gnome.org 2024

# Metadados dos programas

# Capturas de tela

O Programas exibe as capturas de tela na página de detalhes de um aplicativo. Isso normalmente deve incluir capturas de tela de várias janelas/diálogos do aplicativo, para que o usuário tenha uma noção rápida dos recursos do aplicativo, aparência e comportamento, etc.

Quando mais de uma captura de tela estiver presente no arquivo de metainfo do aplicativo, o Programas mostrará as capturas de tela em um carrossel.

Nos casos em que o arquivo de metainfo do aplicativo não contiver nenhuma captura de tela, um ícone de preenchimento de espaço como o abaixo com `Sem capturas de tela` será exibido:

O ícone de preenchimento de espaço pode parecer diferente se você estiver usando um tema de ícone personalizado.

As capturas de tela podem ficar desatualizadas conforme a UI do aplicativo muda. Então, mesmo que o Programas mostre capturas de tela para um aplicativo, é importante verificar se essas capturas de tela estão atualizadas ou desatualizadas.

Você pode melhorar as informações de captura de tela do aplicativo:

Como adicionar capturas de tela ausentes do aplicativo

# Barra de contexto do aplicativo

A barra de contexto do aplicativo no Programas é uma coleção de blocos na página de detalhes de um aplicativo, que exibe os seguintes detalhes.

Armazenamento

Segurança

Suporte a hardware

Classificação por idade

Isso mostra a barra de contexto do aplicativo para o aplicativo Programas:

Os blocos são exibidos na ordem listada acima (começando com o bloco `Armazenamento` à esquerda).

Cada bloco é abordado em detalhes abaixo.

# Armazenamento

O Programas exibe um bloco de armazenamento na página de detalhes de um aplicativo. Se o aplicativo não estiver instalado, isso exibe o tamanho estimado de download necessário para instalá-lo. Se o aplicativo estiver instalado, ele exibirá o espaço de armazenamento usado pelo aplicativo.

Os tamanhos são calculados a partir de dados fornecidos pelo backend do Programas (como flatpak ou um RPM) e não são especificados nos metadados fornecidos pelo aplicativo. Não há nada que você possa fazer para afetar este bloco editando o arquivo metainfo de um aplicativo. Ele está listado aqui para fins de integridade.

# Segurança

Programas exibe um bloco de segurança na página de detalhes de um aplicativo. Isso resume as informações sobre se o aplicativo pode ser considerado seguro para instalar e executar, ou se é necessário ter cuidado antes de confiar nele.

Este bloco combina informações sobre as permissões que o aplicativo solicita quando é executado (como permissão para ler seus arquivos), com informações sobre como o aplicativo foi desenvolvido. Aplicativos de software livre, onde o código-fonte é publicamente legível, podem ser mais seguros do que os privativofs, pois podem ser auditados.

A caixa de diálogo que aparece quando o bloco é clicado lista as diferentes permissões que o aplicativo solicita, além de algumas informações sobre sua licença e tempo de execução.

Você pode melhorar as informações de segurança:

Como corrigir informações incorretas de segurança e permissões

# Suporte a hardware

Programas exibe um bloco de suporte a hardware na página de detalhes de um aplicativo. Isso combina informações sobre os requisitos de hardware do aplicativo e os recursos de hardware do computador, com o objetivo de destacar incompatibilidades ou requisitos ausentes — ou para indicar que o aplicativo deve funcionar corretamente sem incompatibilidades.

O código analisa o seguinte hardware. Mais pode ser suportado no futuro.

Se um touchpad, mouse ou teclado está presente/é necessário

Se um gamepad é necessário

O tamanho mínimo e recomendado de exibição para o qual o aplicativo pode ser dimensionado

Não é possível detectar com segurança se um gamepad está presente, pois eles geralmente são deixados desconectados por não serem necessários para o uso normal do computador.

A caixa de diálogo que aparece quando o bloco é clicado lista os diferentes requisitos de hardware do aplicativo e se algum deles não foi atendido.

Você pode melhorar as informações de hardware:

Como adicionar informações de hardware ausentes

# Classificação por idade

Programas exibe um bloco de classificação por idade na página de detalhes de um aplicativo. Isso mostra para qual faixa etária o aplicativo deve ser adequado, com base em diferentes tipos de conteúdo que o aplicativo declarou conter. Essas informações são resumidas em um formato semelhante aos certificados de classificação de jogos ou filmes do seu país.

Por exemplo, isso destacará se um jogo contém violência ou se um aplicativo contém publicidade no aplicativo.

A caixa de diálogo que aparece quando o bloco é clicado lista os diferentes tipos de conteúdo no aplicativo e quão grave esse conteúdo é.

Você pode melhorar as informações de classificação por idade:

Como adicionar informações de classificação de conteúdo ausentes

# Licença

Programas exibe um bloco indicando se um aplicativo é software livre ou se sua licença é proprietária, especial ou desconhecida. Este bloco inclui informações mais detalhadas sobre a licença do projeto. Este bloco também lista alguns dos benefícios do software livre. Saiba mais

Às vezes, as informações de licença não estão corretas para um aplicativo e, portanto, um aplicativo que é realmente software livre será mostrado como ‘privativo’. Da mesma forma, às vezes as informações da licença são desconhecidas.

Programas realça licenças livres e de código aberto em verde, licenças privativas e especiais em amarelo, como mostrado aqui. Licenças desconhecidas são destacadas em cinza.

Você pode adicionar ou melhorar as informações da licença:

Como corrigir informações incorretas de licenciamento

# Links

Programas exibe uma lista de links de recursos do aplicativo no bloco de links. Eles são os seguintes:

| Link do site
| Link de doação
| Link de contribuição com tradução
| Link de relatório de bug
| Link de ajuda
| Link de contato

Alguns ou todos esses links podem estar presentes, dependendo se estão listados no arquivo de metainfo do aplicativo.

Nos casos em que o arquivo de metainfo do aplicativo não contém nenhum link, o seguinte bloco com um ponto de interrogação será exibido.

Você pode melhorar os links:

Como adicionar links ausentes

# Bloco de Carrossel

Aplicativos que são postos em destaque no Programas são exibidos em um carrossel na parte superior da janela principal como mostrado aqui. Cada bloco de carrossel tem uma cor de fundo que é automaticamente extraída do ícone do aplicativo. Às vezes, essa cor de fundo não é muito adequada para o aplicativo e precisa ser especificada explicitamente pelo desenvolvedor do aplicativo.

O conjunto de aplicativos que são apresentados é decidido pelos mantenedores da distribuição Linux.

Você pode melhorar o bloco de carrossel:

Como definir a cor de fundo do bloco de carrossel

# De onde vêm os metadados

Os metadados usados ​​para especificar qual hardware um software requer, para quais idades de usuários ele é adequado e os fatores que contribuem para o quão seguro ele pode ser para instalar, todos vêm do arquivo metainfo para esse software.

O arquivo metainfo é um arquivo XML. Seu formato de arquivo é especificado na especificação AppStream.

Veja o arquivo metainfo para o aplicativo Arquivos do GNOME.

appdata é o termo mais antigo para metainfo.

# O que acontece se metadados estiverem ausentes

Se alguns metadados estiverem ausentes em um aplicativo, Programas só pode adivinhar o que pode ser e, portanto, não consegue apresentar muitas informações em suas interfaces. Os palpites que Programas faz são baseados no fato de que a maioria dos softwares é projetada para computadores desktop.

Você pode ajudar a melhorar os metadados de um aplicativo!

# Como contribuir com informações ausentes

Se você descobrir que a página de um aplicativo está faltando informações ou tem informações incorretas, você pode contribuir de uma das duas maneiras:

Você pode relatar os metadados ausentes/incorretos ao rastreador de bugs do respectivo aplicativo, para que o desenvolvedor do aplicativo possa corrigi-los.

Você pode corrigir os metadados ausentes/incorretos você mesmo. Veja o aba Como fazer abaixo sobre como fazer isso.

Para ambos, primeiro você precisa encontrar a página do projeto do aplicativo. O link para a página do projeto normalmente deve estar disponível na página do aplicativo conforme mostrado aqui. Caso contrário, você precisará encontrá-lo com uma simples pesquisa no Google.

Os aplicativos são normalmente hospedados no GitLab ou GitHub. Por exemplo, os aplicativos GNOME são hospedados em gitlab.gnome.org.

# Como adicionar capturas de tela de aplicativos ausentes

As informações de captura de tela de um aplicativo são armazenadas no elemento `<screenshots>` dentro do `<component>` do aplicativo em seu arquivo metainfo.

O número recomendado de capturas de tela para um aplicativo é entre 5 e 10. As capturas de tela devem estar idealmente no formato PNG com proporção de 16:9 e largura mínima de 620 pixels.

Por exemplo, aqui estão as entradas de captura de tela para o aplicativo Programas:

<screenshots> <screenshot type="default"> <image>https://gitlab.gnome.org/GNOME/gnome-software/raw/HEAD/data/metainfo/ss-overview.png</image> <caption>Overview panel</caption> </screenshot> <screenshot> <image>https://gitlab.gnome.org/GNOME/gnome-software/raw/HEAD/data/metainfo/ss-details.png</image> <caption>Details panel</caption> </screenshot> </screenshots>

# Como corrigir informações incorretas de segurança e permissões

As informações de segurança e permissões para um aplicativo vêm de diferentes fontes, dependendo de como o aplicativo é empacotado. Para aplicativos empacotados tradicionalmente, por exemplo, no formato RPM ou DEB, não há informações de segurança ou permissões disponíveis e nada pode ser feito para adicioná-las a um aplicativo.

Para aplicativos flatpak, as informações vêm do manifesto flatpak do aplicativo, especificando quais buracos no isolamento (sandbox) o aplicativo requer. Cada um desses buracos normalmente contribui para diminuir o nível de segurança exibido do aplicativo em Programas — movendo-o de ‘seguro’ para ‘potencialmente inseguro’ para ‘inseguro’.

Para melhorar o nível de segurança de um aplicativo, seu isolamento de sandbox deve ser tornado o mais fechado possível, removendo permissões de sandbox onde elas não são necessárias, e usando portais em vez de permissões de sandbox quando possível. O uso de portais não diminui o nível de segurança exibido de um aplicativo no Programas.

Por exemplo, se o aplicativo solicitar acesso de leitura/gravação ao sistema de arquivos completo (`--filesystem=host`), ele realmente precisa disso ou precisa acessar arquivos apenas em alguns locais específicos? Se sim, o portal de arquivos pode ser usado, ou permissões do sistema de arquivos mais específicas podem ser especificadas.

Se o aplicativo funciona no Wayland e precisar funcionar no X11 apenas como fallback, sem usar recursos especiais do X11, ele pode usar `--socket=fallback-x11` em vez de `--socket=x11`?

Orientações sobre permissões específicas ou outros formatos de empacotamento podem ser adicionadas aqui no futuro.

Leitura adicional:

# Como adicionar informações de hardware ausentes

As informações de hardware de um aplicativo são armazenadas nos elementos `<requires>`, `<recommends>` e `<supports>` dentro do `<component>` do aplicativo em seu arquivo metainfo.

Programas entende os elementos `<control>` e `<display_length>`.

Consulte esta postagem de blog ou esta postagem de blog para obter exemplos de metadados.

# Como adicionar informações de classificação de conteúdo ausentes

As informações de classificação de conteúdo para um aplicativo são armazenadas no elemento `<content_rating>` dentro do `<component>` do aplicativo em seu arquivo metainfo.

Os aplicativos devem usar o padrão OARS 1.1 para preencher este elemento. Se o elemento `<content_rating>` não for especificado, a classificação de conteúdo do aplicativo será desconhecida. Se for especificado, mas estiver vazio, o aplicativo não terá conteúdo que possa ser inadequado para qualquer público.

Use o gerador de OARS para produzir informações de classificação de conteúdo adequadas para um aplicativo.

# Como corrigir informações de licenciamento incorretas

As informações de licenciamento de um aplicativo são armazenadas no elemento `<project_license>` dentro do `<component>` do aplicativo em seu arquivo metainfo.

O conteúdo neste elemento deve ser uma expressão SPDX que descreve a licença ‘principal’ para o projeto. Normalmente, deve ser a licença do código e não incluir a licença da documentação ou conteúdo auxiliar.

Se a expressão SPDX for uma licença única, ou uma combinação de várias licenças, que são todas aprovadas pela FSF ou OSI, o aplicativo é considerado ‘software livre’ e o bloco de licença diz isso. Caso contrário, é considerado ‘privativo’.

Se um aplicativo estiver sendo exibido como ‘privativo’ quando você acha que não deveria ser, é provável que o elemento `<project_license>` inclua a licença de documentação para o projeto. Remova-o.

Por exemplo, altere os metadados da licença de:

<project_license>GPL-2.0+ and CC-BY-SA-3.0</project_license>

para

<project_license>GPL-2.0+</project_license>

Leitura adicional:

Não coloque (de forma geral) a licença de documentação no appdata

# Como adicionar links ausentes

Os links para um aplicativo são armazenados como elementos `<url>` dentro do `<component>` do aplicativo em seu arquivo metainfo.

Adicione quantos tipos de link documentados na especificação do appstream estiverem disponíveis para o aplicativo. Se nenhuma página adequada existir para um determinado tipo de link, ele não precisa ser incluído.

Por exemplo, aqui estão os links de recursos para o aplicativo Programas:

<url type="bugtracker">https://gitlab.gnome.org/GNOME/gnome-software/-/issues</url> <url type="contact">https://discourse.gnome.org/tag/gnome-software</url> <url type="contribute">https://welcome.gnome.org/app/Software/</url> <url type="donation">https://www.gnome.org/donate/</url> <url type="homepage">https://apps.gnome.org/Software</url> <url type="translate">https://l10n.gnome.org/module/gnome-software/</url> <url type="vcs-browser">https://gitlab.gnome.org/GNOME/gnome-software/</url>

# Como definir a cor de fundo do bloco de carrossel

A cor de fundo do bloco de carrossel normalmente é extraída automaticamente do ícone do aplicativo. Se essa cor for insatisfatória, no entanto, ela pode ser substituída usando o elemento `<branding/>` do appstream com cores declaradas (desde a série 47.x). A vantagem é que mais clientes podem usar as cores.

Por exemplo, aqui estão algumas entradas de “branding”:

<branding> <color type="primary" scheme_preference="light">#ff00ff</color> <color type="primary" scheme_preference="dark">#993d3d</color> </branding>

Observe que o atributo `scheme_preference` é ignorado, o Programas escolhe a melhor cor para o tema por conta própria.

Resta, para compatibilidade com versões anteriores, a possibilidade de adicionar o seguinte XML ao elemento metainfo `<component>` do aplicativo:

<custom> <value key="GnomeSoftware::key-colors">[(124, 53, 77), (99, 16, 0)]</value> </custom>

mas o elemento `<branding/>` tem precedência.

O valor de `GnomeSoftware::key-colors` é um GVariant de formato de texto com o tipo `a(yyy)` e representa um conjunto não ordenado de cores-chave para o aplicativo. Cada elemento do conjunto é uma cor no formato RGB variando de `(0, 0, 0)` a `(255, 255, 255)`.

As cores devem ser escolhidas de modo que:

Sejam identificáveis ​​ao aplicativo, combinando com a marca do aplicativo de alguma forma, se possível.

Contraste com a borda do ícone do aplicativo, para que, quando forem usadas como plano de fundo atrás dele, o ícone possa ser distinguido.

Contraste com a cor do texto em primeiro plano no tema Adwaita (`#2e3436`) e em sua variante escura (`#eeeeec`). Isso geralmente significa escolher uma cor com um nível médio de brilho.

O contraste pode ser verificado usando o aplicativo Contraste.

Pelo menos uma cor deve ser especificada. Mais podem ser especificadas se uma cor não puder satisfazer todos os requisitos acima, e o Programas escolherá a mais apropriada para uso no bloco do carrossel. Se exatamente uma cor for especificada, seu brilho e saturação podem ser modificados para melhorar o contraste com a cor de primeiro plano. Se mais de uma cor for especificada, aquela com o melhor contraste com a cor de primeiro plano será escolhida, e seu brilho e saturação não serão modificados.

# Como testar as alterações de cor de fundo do bloco de carrossel

Modifique o arquivo metainfo para seu aplicativo e execute o Programas com:

gnome-software --show-metainfo=/caminho/do/app.metainfo.xml,icon=/caminho/do/ícone/do/aplicativo.png

A página de detalhes do seu aplicativo será exibida. Se você navegar de volta para a página de visão geral de Programas, seu aplicativo será o único no carrossel de ‘em destaque’.