3. Processo de desenvolvimento

Como é comum em projetos de código aberto, contribuições de código e documentação para o projeto são muito apreciadas. A comunidade QGIS é muito solidária. Esta seção descreve o procedimento para desenvolver e mesclar suas contribuições no projeto QGIS.

3.1. Um projeto baseado em git

A complexidade do código fonte do QGIS aumentou consideravelmente nos últimos anos. Portanto, é difícil prever os efeitos colaterais que a adição de um recurso terá. No passado, o projeto QGIS tinha ciclos de lançamento muito longos porque dava muito trabalho para restabelecer a estabilidade do sistema de software após a adição de novos recursos. Para superar esses problemas, o QGIS mudou para um modelo de desenvolvimento usando o sistema de controle de versão git: novos recursos são codificados nos ramos contribuidores primeiro e mesclados ao mestre QGIS (o principal ramo) quando estiverem acabados e estáveis.

O código fonte do QGIS está hospedado em https://github.com/qgis/QGIS.

3.1.1. Funções

Existem várias funções no GitHub. Ao ter uma conta no GitHub você já tem permissão para contribuir bifurcando o repositório e tem o papel ‘contribuinte’. Os desenvolvedores principais são ‘colaboradores’ e podem mesclar ramificações no repositório upstream e oficial.

3.1.2. Ambiente

Para começar a usar e contribuir com o repositório QGIS, você precisa:

  1. ter uma conta do GitHub

  2. faça sua própria cópia do repositório QGIS (veja fork)

  3. tenha um: referência:`cliente git instalado ` em seu sistema

  4. configure seu ambiente git <https://docs.github.com/en/github/getting-started-with-github/set-up-git#setting-up-git>`_

  5. e divirta-se!

3.1.3. Instalando o git

O projeto git fornece versões recentes do software para a maioria das plataformas. Siga as instruções em https://git-scm.com/downloads para obter e instalar a cópia correspondente ao seu sistema operacional e arquitetura. Lá, também é possível instalar um cliente git GUI para navegar e gerenciar seus repositórios (na maioria das vezes, ele instalará o git se ainda não estiver disponível).

3.2. Desenvolvimento em branches

3.2.1. Contribuições para o desenvolvimento

Depois de se inscrever no GitHub e ter bifurcado o repositório, você pode se envolver como colaborador.

Nota

Contribuições para o código QGIS podem ser feitas a partir de seu repositório bifurcado no site do GitHub. O novo código será construído automaticamente pelo ambiente de teste. Mas esse fluxo de trabalho pode revelar rapidamente seus limites quando você deseja fornecer alterações complexas. As instruções abaixo assumirão um clone local.

Você pode contribuir iniciando uma solicitação. Para fazer isso, siga estas etapas genéricas:

  1. :referência:`Clone seu repositório <access_repository> ` em seu computador local e configure o ambiente de compilação

  2. Crie uma nova ramificação e faça as edições para desenvolvimento

  3. Confirme suas alterações e envie seu ramo de volta para o fork remoto no GitHub. Uma solicitação pull é oferecida como link da Web (URL) logo em seguida.

  4. Abra uma pull solicitação (PR) pedindo para puxar o(s) compromisso(s) do seu ramo para o ramo master no repositório upstream.

  5. Um processo de revisão está sendo iniciado informando outros colaboradores e colaboradores sobre sua pull solicitação. Você deve ser reativo aos seus comentários e sugestões.

Nota

Um fluxo de trabalho Fork & Pull do Github mais detalhado está disponível em https://reflectoring.io/github-fork-and-pull/

Nota

A maioria dos projetos QGIS (site, documentação, pyQGIS API, plugins…) estão disponíveis na página do projeto GitHub e podem obter contribuições, seguindo o mesmo processo.

3.2.2. Acessando o Repositório

Para poder interagir de seu disco local com seu fork remoto e os repositórios upstream do QGIS, você precisa:

  1. Faça um clone de sua cópia em seu disco local

    cd path/to/store/the/repository
    git clone https://github.com/<yourName>/QGIS.git
    
  2. Conecte o repositório principal do QGIS (vamos chamá-lo de upstream) ao seu

    git remote add upstream https://github.com/qgis/QGIS.git
    
  3. Verifique os repositórios remotos conectados

    git remote -v
    # origin   https://github.com/<YourName>/QGIS.git (fetch)
    # origin   https://github.com/<YourName>/QGIS.git (push)
    # upstream https://github.com/qgis/QGIS.git (fetch)
    # upstream https://github.com/qgis/QGIS.git (push)
    

    Seu repositório online agora está acessível a partir de sua unidade local e você pode interagir com ele usando o nome origem. Sempre que você quiser buscar mudanças do repositório qgis/QGIS, use upstream.

Nota

No QGIS, mantemos nosso código mais estável na ramificação da versão atual. O ramo master contém código para a chamada série de lançamentos ‘instável’. Periodicamente, ramificaremos uma versão do master e, em seguida, continuaremos a estabilização e a incorporação seletiva de novos recursos no master.

Veja o arquivo :fonte:`INSTALAR <INSTALL.md>` na árvore fonte para instruções específicas sobre como construir versões de desenvolvimento.

3.2.3. Procedimento

  1. Anúncio inicial na lista de discussão ou repositório de problemas:

    Antes de começar, faça um anúncio na lista de discussão do desenvolvedor para ver se outro desenvolvedor já está trabalhando no mesmo recurso. Você também pode mencionar seu interesse como um comentário no relatório do problema, se houver um no repositório. Se o novo recurso exigir alguma alteração na arquitetura do QGIS, uma Proposta de Aprimoramento QGIS (QEP) é necessária.

  2. Crie uma ramificação em seu repositório local:

    Crie um novo ramo git para o desenvolvimento do novo recurso, com base no estado mais recente do ramo master.

    git fetch upstream master
    git checkout -b newfeature upstream/master
    
  3. Agora você pode começar a desenvolver:

    Codifique suas alterações em seu disco local com seu IDE usual. Lembre-se de escrever o conjunto de testes para suas modificações, quando apropriado.

  4. Confirme suas alterações no repositório git:

    Ao fazer um compromisso, coloque um comentário descritivo e faça vários compromisso pequenos se as alterações em vários arquivos não estiverem relacionadas. Por outro lado, preferimos que você agrupe as alterações relacionadas em um único compromisso.

    git add path/to/your/files
    git commit -m "Add a comment describing your nice feature"
    
  5. Agora, você pode querer compartilhar seu trabalho com os membros da comunidade QGIS. Envie seu novo recurso para seu repositório de bifurcação online fazendo:

    git push origin newfeature
    

    Nota

    Se a ramificação já existir, suas alterações serão inseridas nela, caso contrário, ela será criada.

  6. :referência:`Envie suas alterações <submit_patch> ` com um pull-solicitação

    Com a abertura do pull-solicitação, o conjunto de testes automatizado é acionado e verifica se suas alterações seguem as diretrizes de codificação do QGIS e não quebram nenhum recurso existente. Você precisaria corrigir quaisquer problemas relatados antes que sua ramificação fosse mesclada upstream.

    Dica

    Usamos GitHub ações para gerenciar os testes a serem executados no repositório. Por conveniência, você pode habilitar as ações em seu repositório para que os testes sejam executados quando você enviar as alterações. Você abriria a solicitação pull depois que todas elas fossem aprovadas, tornando o processo de revisão mais eficiente.

  7. Faça o rebase para o mestre upstream regularmente:

    Recomenda-se fazer o rebase para incorporar as alterações no master à ramificação regularmente. Isso facilita a mesclagem do ramo de volta ao master posteriormente. Após um rebase, você precisa git força -f para seu repositório bifurcado.

    git pull --rebase upstream master
    git push -f origin newfeature
    

Nota

Consulte os sites a seguir para obter informações sobre como se tornar um mestre do GIT.

3.2.4. Teste antes de mesclar de volta ao master

Quando você terminar o novo recurso e ficar satisfeito com a estabilidade, faça um comunicado na lista de desenvolvedores. Antes de mesclar novamente, as alterações serão testadas por desenvolvedores e usuários.

3.3. Como enviar solicitações de pull

Existem algumas diretrizes que o ajudarão a obter seus patches e solicitações de pull no QGIS facilmente e nos ajudar a lidar com os patches que são enviados para uso fácil.

Em geral, é mais fácil para os desenvolvedores se você enviar solicitações de pull do GitHub. Nós não descrevemos as solicitações de pull aqui, mas indicamos a documentação de solicitação de pull do GitHub.

Se você fizer um pull request, pedimos que você mescle o master com seu ramo PR regularmente para que seu PR seja sempre mesclável com o ramo master upstream.

Se você é um desenvolvedor e deseja avaliar a fila de solicitações pull, existe uma ferramenta muito boa que permite fazer isso a partir da linha de comando <https://changelog.com/posts/git-pulls-command-line-tool -for-github-pull-requests>`_

Em geral, quando você envia um PR, você deve assumir a responsabilidade de segui-lo até a conclusão - responda às perguntas postadas por outros desenvolvedores, procure um ‘campeão’ para seu recurso e dê a ele um lembrete gentil ocasionalmente se perceber que seu PR é não sendo atuado. Por favor, tenha em mente que o projeto QGIS é impulsionado pelo esforço voluntário e as pessoas podem não conseguir atender ao seu PR instantaneamente. Nós verificamos as solicitações pull recebidas, mas às vezes perdemos algumas coisas. Não se ofenda ou se assuste. Tente identificar um desenvolvedor para ajudá-lo e entre em contato com eles perguntando se eles podem ver seu patch. Se você sentir que o PR não está recebendo a atenção que merece, suas opções para acelerar devem ser (em ordem de prioridade):

  • Ajude a revisar as solicitações de pull de outras pessoas para liberar a pessoa atribuída à sua.

  • Envie uma mensagem para a lista de discussão ‘marketing’ do seu PR e como será maravilhoso tê-lo incluído no código base.

  • Envie uma mensagem para a pessoa a quem seu PR foi atribuído na fila de PR.

  • Envie uma mensagem para Marco Hugentobler (que gerencia a fila de PR).

  • Envie uma mensagem ao comitê de direção do projeto pedindo que ajudem a ver seu PR incorporado ao código base.

3.3.1. Melhores práticas para criar um pull request

  • Sempre inicie uma ramificação de recurso do mestre atual.

  • Se você estiver codificando uma ramificação de recurso, não “mescle” nada nessa ramificação, em vez disso, faça o rebase conforme descrito no próximo ponto para manter seu histórico limpo.

  • Antes de criar um pull solicitação faça git buscar upstream e git rebase upstream/master (dado upstream é o controle remoto para o usuário qgis e não seu próprio controle remoto, verifique seu .git/config ou faça git remoto -v | grep github.com/qgis).

  • Você pode fazer um git rebase como na última linha repetidamente sem causar nenhum dano (desde que o único propósito do seu ramo seja ser mesclado no master).

  • Atenção: Após um rebase você precisa git força -f para seu repositório bifurcado. DISPOSITIVOS PRINCIPAIS: NÃO FAÇA ISSO NO REPOSITÓRIO PÚBLICO QGIS!

3.3.2. Etiquetas especiais para notificar os documentadores

Existe um rótulo especial (Precisa de Documentação) que pode ser atribuído pelos revisores a sua solicitação pull para gerar automaticamente relatórios de problemas no repositório QGIS-Documentação assim que sua solicitação pull for mesclada. Lembre-se de mencionar se seu recurso merece esse rótulo.

Além disso, você pode adicionar tags especiais às suas mensagens de confirmação para fornecer mais informações aos documentadores. A mensagem de confirmação é então adicionada ao relatório de problema gerado:

  • [documentos de necessidades] para instruir os escritores de documentos a adicionar alguma documentação extra após uma correção ou adição a uma funcionalidade já existente.

  • [recurso] em caso de nova funcionalidade. Preencher uma boa descrição em seu PR será um bom começo.

Por favor, os desenvolvedores usem esses rótulos (não diferenciam maiúsculas de minúsculas) para que os redatores de documentos tenham problemas para trabalhar e tenham uma visão geral do que fazer. MAS, por favor, também reserve um tempo para adicionar algum texto: no compromisso OU nos próprios documentos.

3.3.3. Diligência prévia

QGIS está licenciado sob a GPL. Você deve fazer todos os esforços para garantir que você envie apenas patches que não sejam prejudicados por direitos de propriedade intelectual conflitantes. Também não envie código que você não esteja feliz em ter disponibilizado sob a GPL.

3.4. Obtendo acesso de gravação GIT

O acesso de gravação à árvore de origem do QGIS é feito por convite. Normalmente, quando uma pessoa envia vários (não há um número fixo aqui) patches substanciais que demonstram competência básica e compreensão das convenções de codificação C++ e QGIS, um dos membros do PSC ou outros desenvolvedores existentes podem indicar essa pessoa ao PSC para conceder acesso de gravação . O nomeador deve fornecer um parágrafo promocional básico de por que eles acham que essa pessoa deve obter acesso de gravação. Em alguns casos, concederemos acesso de gravação a desenvolvedores não C++, por exemplo. para tradutores e documentadores. Nesses casos, a pessoa ainda deve ter demonstrado capacidade de enviar patches e, idealmente, deve ter enviado vários patches substanciais que demonstrem sua compreensão de modificar a base de código sem quebrar as coisas, etc.

Nota

Desde a mudança para o GIT, é menos provável que concedamos acesso de gravação a novos desenvolvedores, pois é trivial compartilhar código no github bifurcando o QGIS e emitindo solicitações pull.

Sempre verifique se tudo compila antes de fazer qualquer compromissos/pull request. Tente estar ciente de possíveis quebras que seus compromisso podem causar para pessoas construindo em outras plataformas e com versões mais antigas/mais recentes de bibliotecas.