Contribuição para Jami

As contribuições para Jami são sempre bem-vindas e são muito apreciadas. Há muitas maneiras de contribuir para Jami, incluindo relatar bugs e problemas, contribuir com código, ajudar a empacotar e manter Jami para sua distribuição GNU / Linux ou outro sistema operacional, bem como contribuir para esses próprios documentos.

Por favor, veja abaixo para saber como começar a contribuir para Jami!

Relatório de erros e problemas

Consulte o guia de instruções de passo a passo sobre como relatar erros e problemas que você encontra em Jami.

Código de contribuição

Se quiser começar a contribuir para o Jami, pode começar por ver as primeiras edições em: https://git.jami.net/groups/savoirfairelinux/-/issues/?sort=created_date&state=opened&label_name%5B%5D=good-first-issue

Você pode entrar em contato com os desenvolvedores diretamente, adicionando um comentário no tíquete com o qual deseja começar. Eles poderão orientá-lo durante o processo.

Em algum momento, irá precisar de fazer push de um patch em https://review.jami.net. Para mais informações sobre como fazer isso, por favor consulte o guia developer/working-with-gerrit.

Orientações para a mensagem de commit

Quando submeter um patch ao Jami, por favor siga estas diretrizes para as suas mensagens de commit:

  • A primeira linha deve incluir o componente ou o âmbito da alteração, seguido de um breve resumo da alteração no modo imperativo (por exemplo, “adicionar uma nova função”, “corrigir um erro”, “atualizar a documentação”).

  • O assunto pode usar a capitalização do componente ou do âmbito, mas o resto do título deve ser em minúsculas.

  • A segunda linha deve estar em branco.

  • A terceira linha deve ser o início de uma descrição mais longa da alteração, em frases completas, se necessário.

  • Regra 50/72: A primeira linha não deve ter mais de 50 caracteres (idealmente) e o resto da mensagem deve ter 72 caracteres por linha. Isto pode ser configurado no seu editor de texto.

  • Se a alteração estiver relacionada com um problema específico no Jami GitLab, inclua o número do problema na mensagem de confirmação. Por exemplo: GitLab: #123. Se a alteração estiver relacionada com vários problemas, liste-os todos. Se a alteração estiver relacionada com um problema que não faz parte do projeto, utilize uma hiperligação para o problema.

Modelo para uma mensagem de commit:

<Component/Scope>: <short Summary (imperative, max 50 characters)>

<Detailed description (in present tense) of what was changed and why
it was necessary, wrapped at 72 characters per line to maintain
readability. Include any important details that help others understand
the context of the change. Use this space to explain complex changes
or provide background information.>

[GitLab: #<issuenumber>] or [Link to issue]

Por exemplo:

ConversationView: add a new function

Adds a new function to the ConversationView class that allows
the user to sort conversations by date. This function is necessary
to improve the user experience and make it easier to find specific
conversations.

GitLab: #123

Embalagem Jami

Existem duas formas possíveis de empacotar o Jami: + Através do nosso processo interno para criar pacotes disponíveis na Snap Store ou em https://dl.jami.net + Através do processo de empacotamento da sua distribuição GNU/Linux favorita

Nota

O Jami é um projeto bastante complexo com muitas dependências. Esta não é uma tarefa rápida e fácil e requer alguma manutenção.

Se escolher a segunda opção, aqui estão algumas notas úteis: + Para o nosso lançamento oficial, mantemos uma certa versão do Qt, porque o Qt é uma grande dependência e precisamos de garantir que o Jami funciona com a versão que usamos. Cada pequena mudança na versão do Qt pode quebrar o Jami ou trazer algumas pequenas mudanças indesejadas (por exemplo, 6.2->6.4 quebrou o pipeline de vídeo) + Nós também bifurcamos o pjproject devido ao ICE sobre TCP que não está planeado no upstream + libupnp recebeu alguns patches para ter certeza de que é construído com a API non-blocking. + FFMpeg recebeu algumas correções para partilha de ecrã. + Pode verificar como as dependências são construídas em daemon/contrib/src

Para o empacotamento interno, tudo está localizado em extras/packaging/gnu-linux. Pode seguir os patches anteriores para entender as suas necessidades, por exemplo: https://review.jami.net/c/jami-client-qt/+/28036

Utilizamos 3 canais: + Internal para testes + Nightly/Beta/Edge para beta público + Stable para lançamentos públicos

Geralmente usamos o internal quando testamos uma nova distribuição ou quando empacotamos uma nova versão do Qt. Em seguida, tentamos gerar um nightly por semana e um stable por mês (se os testes unitários forem verdes).

Os pacotes são enviados para: + dl.jami.net (2 máquinas, com um rsync a cada 15 minutos) + Loja Ubuntu (snapcraft.io/jami)

Se quiser adicionar uma nova distribuição, precisará de: + Adicionar Dockerfile + Alterar Makefile + Atualizar script de empacotamento + Cruzar os dedos + Testar o pacote numa VM

Nota

O Chromium é uma parte difícil de construir. Os 3 problemas comuns que temos são:

  • O CCG é demasiado recente:

    • Geralmente, a correção consiste em importar patches do gerrit do chromium para corrigir problemas do GCC

  • O Python é demasiado recente:

    • Geralmente, a correção consiste em utilizar o PyEnv para obter um ambiente virtual com a versão correta do Python

  • Dependências em falta:

    • Durante o passo de configuração do Qt, a lista de componentes construídos é listada e as dependências em falta são listadas. Geralmente, a instalação de um pacote ou a atualização do node.js resolve o problema

    • Note-se que, se o Qt for gerado sem o chromium, temos de remover o pacote da cache das máquinas de construção para voltar a gerar um novo pacote (/var/cache/jami)

Se você quiser remover uma distribuição: + Se uma distribuição for EOL OU se houver 2 LTS mais recentes, podemos remover a distribuição (por exemplo, ubuntu 20, 22, 24 - remove ubuntu 20) removendo os arquivos e verificações relacionados

Nota

Para as próximas grandes mudanças, queremos:

  • Usar CMake em vez de autotools para jami-daemon

  • Usar o núcleo22 em vez do núcleo20 no snap

  • Suporte a Flatpak/AppImage? Isso pode simplificar o empacotamento personalizado para RPMs/Debs

  • Gerar apenas um deb em vez de um por distribuição. O mesmo para RPMs

  • Usar o Jenkinsfile para gerar pacotes para Linux/Windows/MacOs ao mesmo tempo, se possível

Para informações internas (por exemplo, como publicar em lojas, ver a wiki interna).

Contribuindo para esta documentação

As contribuições para estes documentos são sempre bem-vindas e apreciadas, desde pequenas correções até novos capítulos.

Esta página irá percorrer os passos para criar uma nova página ou enviar uma correção. O processo de revisão de patch é o mesmo que:doc:` para qualquer outro projeto Jami <how-to-submit-a-patch>`, por isso não vamos explicar cada comando.

Nota

Ao contribuir para esta documentação, concorda em disponibilizar as suas contribuições no âmbito da versão:doc:fdl, Versão 1.3 ou de qualquer versão posterior publicada pela Free Software Foundation; sem Secções Invariantes, sem textos de capa frontal e sem textos de capa back.

Também promete que é o autor das suas alterações, ou que as copiou de uma obra de domínio público ou de uma obra publicada sob uma licença gratuita compatível com a:doc:fdl.

Nota

Se quiser ajudar a traduzir esta página, pode juntar-se ao projeto e começar a traduzir esta página em https://explore.transifex.com/savoirfairelinux/jami/

Dependências

Você precisará de Git instalado e configurado para usar seu par de teclas SSH, e uma conta no Jami Gerrit, onde você enviaria seus patches para revisão. Se você precisar de ajuda com isso, consulte:doc:o início do nosso guia de submissão de patch <how-to-submit-a-patch> (TODO).

Se você quiser visualizar as suas alterações localmente no seu navegador da web, você precisa instalar o Sphinx, o Read the Docs Sphinx theme, e o parser Markdown ST.

$ pip install --upgrade sphinx sphinx_rtd_theme myst_parser

Se você quiser usar o recurso de auto-construção e auto-refrescamento, também instale sphinx-autobuild.

$ pip install --upgrade sphinx-autobuild

Clonagem do repositório

Clone o repositório e configure as configurações de empurrão assim:

$ git clone "ssh://USERNAME@review.jami.net:29420/jami-docs.git"
$ cd jami-docs
$ git config remote.origin.push HEAD:refs/for/master

Talvez você queira fazer o checkout de uma nova ramificação para cada contribuição/alteração antes de fazer qualquer alteração nos arquivos, de modo que possa facilmente fazer git pull quaisquer alterações futuras do upstream em sua ramificação local principal:

$ git checkout -b my-example-change

Editar uma página

As páginas são escritas em marcado ou reStructuredText. Você pode clicar em “View page source” na parte superior de qualquer página para abrir a fonte bruta da página e ver como foi escrita.

Vá em frente e faça as suas alterações nos arquivos .rst ou .md.

Revisão do seu trabalho

A partir da base do repositório, executar:

$ make clean && make html

A página inicial está localizada em _build/html/index.html.

Nota

Esta documentação atualmente não é construída com a última versão do sphinx. Por favor, veja este problema no GitLab para uma solução alternativa e atualizações sobre este problema.

Para criar automaticamente a documentação e atualizar o seu navegador web sempre que você salvar alterações, execute:

$ make clean && make watch

Mantenha isto em execução em segundo plano, e depois navegue para http://127.0.0.1:8000 (* não * o arquivo.html local).

A salvar o seu trabalho

$ git add source/file/you/edited.md
$ git commit

Consulte as diretrizes para mensagens de commit para saber como escrever uma boa mensagem de commit.

A submissão de uma alteração

A primeira vez que você tentar empurrar suas alterações, Gerrit vai se queixar de que você não tem um Change-ID em seu commit, e fornecer um comando scp para instalar o gancho de commit.

$ git commit --amend --no-edit
$ git push

Modificar o seu trabalho

Um revisor pode pedir-lhe que faça alterações ao seu patch antes de o fundir. Isso não é problema! Basta fazer as alterações, git adi` eles, e executar git compromissos -amend` para modificar o patch. Observe o interruptor --amend, que é necessário para dizer a git para amend/tweak o novo compromisso existente em vez de fazer um novo compromisso. Este é o fluxo de trabalho para atualizar uma mudança proposta ao usar Gerrit.

Adicionar uma página

Se decidir adicionar uma página inteira nova à documentação, deverá adicioná-la também à directiva toctree do referido capítulo.

Por exemplo, se você adicionou uma nova página chamada hosting-jams-on-aws-guide.md do manual de usuário Jami na pasta user, você deve adicioná-la na diretriz toctree do user/index.rst, sem a extensão de arquivo:

.. toctree::

   ...
   bug-report-guide
   hosting-jams-on-aws-guide