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:

ter uma conta do GitHub
faça sua própria cópia do ` repositório QGIS <https://github.com/qgis/QGIS>`_ (veja fork)
tenha um cliente git instalado no seu sistema
configure o seu ambiente git
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:

:ref:`Clone seu repositório <access_repository> ` em seu computador local e configure o ambiente de compilação
Crie uma nova ramificação e faça as edições para desenvolvimento
Confirme suas alterações e envie sua branch de volta para o fork remoto no GitHub. Uma pull request é oferecida como link da Web (URL) logo em seguida.
Abra uma pull request (PR) pedindo para puxar o(s) compromisso(s) do seu ramo para o ramo master no repositório upstream.
Um processo de revisão está sendo iniciado informando outros colaboradores e colaboradores sobre sua pull request. 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:

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

Conecte o repositório principal do QGIS (vamos chamá-lo de upstream) ao seu
```
git remote add upstream https://github.com/qgis/QGIS.git
```
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 INSTALAR na árvore fonte para instruções específicas sobre como construir versões de desenvolvimento.

3.2.3. Procedimento 

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.
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
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.
Commite suas alterações para o repositório git:
Ao fazer um commit, coloque um comentário descritivo e faça vários commits 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 commit.
git add path/to/your/files git commit -m "Add a comment describing your nice feature"
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.
:ref:`Envie suas alterações <submit_patch> ` com um pull-request
Com a abertura do pull-request, 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 actions 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 pull request depois que todas elas fossem aprovadas, tornando o processo de revisão mais eficiente.
Faça o rebase da master regularmente:
Recomenda-se fazer o rebase para incorporar as alterações da master à ramificação regularmente. Isso facilita a mesclagem do ramo de volta à master posteriormente. Após um rebase, você precisa fazer um git push -f para seu fork do repositório.
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 à 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. Enviando Pull Requests 

Existem algumas diretrizes que o ajudarão a inserir seus patches e pull requests no QGIS facilmente e nos ajudar a lidar com os patches que são enviados para uso fácilmente.

Em geral, é mais fácil para os desenvolvedores se enviar um pull request no GitHub. Não descrevemos Pull Requests aqui, mas encaminhamos você para a documentação de pull request 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 pull requests, existe uma ferramenta muito boa que permite fazer isso a partir da linha de comando

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 está 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 pull requests 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 pull requestsde outras pessoas para liberar a pessoa atribuída à sua.
Envie uma mensagem para a lista de discussão fazendo ‘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 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 feature da master atual.
Se você estiver codificando uma ramificação de feature, 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 request faça git fetch upstream e git rebase upstream/master (uma vez que upstream é o repositório remoto para o usuário qgis e não seu próprio remoto, verifique seu .git/config ou faça git remote -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 na master).
Atenção: Após um rebase você precisa executar git push -f para seu fork do repositório. CORE DEVS: 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 pull request para gerar automaticamente relatórios de problemas no repositório QGIS-Documentation assim que sua pull request 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 commit para fornecer mais informações aos documentadores. A mensagem de commit é então adicionada ao relatório de problema gerado:

[needs-docs] 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.
[feature] em caso de nova funcionalidade. Preencher uma boa descrição em seu PR será um bom começo.

Desenvolvedores gentís utilizam esses rótulos (não diferenciar maiúsculas de minúsculas) para que os redatores de documentos tenham com o que trabalhar e tenham uma visão geral do que fazer. MAS, por favor, também reserve um tempo para adicionar algum texto: no commit 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 fazendo um fork do QGIS e enviando pull requests.

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