Importante

A tradução é um esforço comunitário você pode contribuir. Esta página está atualmente traduzida em 82.18%.

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
make your own copy of the QGIS repository (see fork)
tenha um cliente git instalado no seu sistema
set up your git environment
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.
Proper formatting, spell check, and code quality control
Proper formatting, spell check, and code quality control are managed from a pre-commit git hook.

This can be automated by running:
pre-commit install
The spell checker script can also be run alone with:
./scripts/astyle_all.sh
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"
Without the -m option, a new editor window will open for you to write your commit message.

Here are some recommendations about commit description format.
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 

There are a few guidelines that will help you to get your patches and pull requests into QGIS easily, and help us deal with the patches that are sent to us easily.

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.

Pull requests will cause various checks of the Continuous Integration (CI) system to run: building for different environments and running tests, running code linters, spell checkers, etc. Make sure to look at the results of those checks and try to address issues they raise. Of course, you can ask a question in the pull request if you need help from other developers to understand and/or resolve an issue.

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):

Help review others’ pull requests to free the person assigned to yours.
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. Pull Requests merge criteria 

Pull requests must be approved by at least one Core Developer (a developer with push rights to the qgis/QGIS GitHub repository). Before merging, the Core Developer must ensure that the PR passes all reasonable CI checks. Some exceptions exist to this rule, e.g., when a check is broken for unrelated reasons (such as broken third party services, or a lint/code analysis/spell check test failing from other parts of a modified file).

Pull requests created by a Core Developer must also be approved by at least another Core Developer.

A PR must remain open for at least 24 hours following submission, even if it has already been approved. This is to allow wider feedback to be gathered prior to merge, and to permit pre-merge feedback from developers in other time zones. Exceptions to this policy are:

Approved pull requests for backports to stable branches
“Emergency” pull requests, e.g., those which fix broken master builds, CI infrastructure or which represent a time-sensitive security risk
Trivial fixes. The definition of “trivial” is left open to common sense and developer discretion, but is expected to include non-risky changes like typo fixes, translation string fixes, tab order changes, or similar.

3.5. 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.