3. Acesso GIT¶

Esta seção descreve como usar o repositório GIT QGIS. Antes de fazer isso, você precisa primeiro ter um git cliente instalado em seu sistema.

3.1. Instalação ¶

3.1.1. Instalar git para o GNU/Linux ¶

Usuários de distribuições baseadas em Debian podem:

sudo apt install git

3.1.2. Instalar git no Windows ¶

Usuários do Windows podem obter o msys git ou usar o git distribuído com o cygwin.

3.1.3. Instalar git para OSX ¶

O projeto git possui uma versão para download do git. Certifique-se de que o pacote corresponde ao seu processador (provavelmente x86_64, apenas os primeiros Macs Intel precisam do pacote i386).

Ao terminar de baixar, abra a imagem de disco e rode o instalador.

PPC/source note

The git site does not offer PPC builds. If you need a PPC build, or you just want a little more control over the installation, you need to compile it yourself.

Faça o download da fonte em https://git-scm.com/. Descompacte-o e, em um cd do Terminal, na pasta de origem, então:

make prefix=/usr/local
sudo make prefix=/usr/local install

Se você não precisa de nenhum dos extras, Perl, Python ou TclTk (GUI), você pode desativá-los antes de executar com:

export NO_PERL=
export NO_TCLTK=
export NO_PYTHON=

3.2. Acessando o Repositório ¶

Para clonar QGIS master:

git clone git://github.com/qgis/QGIS.git

No QGIS, mantemos nosso código mais estável no branch de lançamento atual. O master contém código para as chamadas séries de lançamento ‘instáveis’. Periodicamente, criamos o branch para lançamento do master e, em seguida, continuaremos a estabilização e incorporação seletiva de novos recursos no master.

Consulte o arquivo INSTALL na árvore de origem para obter instruções específicas sobre a construção de versões de desenvolvimento.

3.4. Fontes de documentação QGIS ¶

Se você estiver interessado em verificar as fontes de documentação do QGIS:

git clone git@github.com:qgis/QGIS-Documentation.git

Você também pode dar uma olhada no leiame incluso no repositório de documentação para mais informações.

3.5. Fontes do website QGIS ¶

Se você estiver interessado em verificar as fontes do website QGIS:

git clone git@github.com:qgis/QGIS-Website.git

Você também pode dar uma olhada no leiame incluído no repositório do website para mais informações.

3.6. Documentação GIT ¶

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

3.7. Desenvolvimento em branches ¶

3.7.1. Finalidade ¶

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 apresentava ciclos de lançamento muito longos, porque era muito trabalhoso 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 no qual os novos recursos são codificados primeiro nos branches GIT e mesclados para master (o branch principal) quando eles são finalizados e estáveis. Esta seção descreve o procedimento para branching e mescla no projeto QGIS.

3.7.2. Procedimento ¶

Comunicado inicial na lista de discussão:
Antes de começar, faça um comunicado na lista de discussão do desenvolvedor para verificar se outro desenvolvedor já está trabalhando no mesmo recurso. Entre em contato também com o consultor técnico do Comitê Diretor do Projeto (CDP). Se o novo recurso exigir alterações na arquitetura QGIS, será necessário um pedido de comentário (PDC).

Criar um branch: crie um novo branch GIT para o desenvolvimento do novo recurso.

git checkout -b newfeature

Agora você pode começar a desenvolver. Se você planeja fazer várias atividades nesse branch, gostaria de compartilhar o trabalho com outros desenvolvedores e ter acesso de gravação ao repositório upstream, você pode enviar seu repositório para o repositório oficial do QGIS fazendo:

git push origin newfeature

Nota

Se o branch já existir, suas alterações serão inseridas nele.

Rebase to master regularly: It is recommended to rebase to incorporate the changes in master to the branch on a regular basis. This makes it easier to merge the branch back to master later. After a rebase you need to git push -f to your forked repo.

Nota

Nunca use git push -f no repositório de origem! Use isso apenas para o seu branch de trabalho.

git rebase master

3.7.3. 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.8. Submitting Patches and 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 use easily.

3.8.1. Pull Requests ¶

In general it is easier for developers if you submit GitHub pull requests. We do not describe Pull Requests here, but rather refer you to the GitHub pull request documentation.

If you make a pull request we ask that you please merge master to your PR branch regularly so that your PR is always mergeable to the upstream master branch.

If you are a developer and wish to evaluate the pull request queue, there is a very nice tool that lets you do this from the command line

Please see the section below on ‘getting your patch noticed’. In general when you submit a PR you should take the responsibility to follow it through to completion - respond to queries posted by other developers, seek out a ‘champion’ for your feature and give them a gentle reminder occasionally if you see that your PR is not being acted on. Please bear in mind that the QGIS project is driven by volunteer effort and people may not be able to attend to your PR instantaneously. If you feel the PR is not receiving the attention it deserves your options to accelerate it should be (in order of priority):

Send a message to the mailing list ‘marketing’ your PR and how wonderful it will be to have it included in the code base.
Send a message to the person your PR has been assigned to in the PR queue.
Send a message to Marco Hugentobler (who manages the PR queue).
Send a message to the project steering committee asking them to help see your PR incorporated into the code base.

3.8.1.1. Melhores práticas para criar um pull request ¶

Always start a feature branch from current master.
If you are coding a feature branch, don’t “merge” anything into that branch, rather rebase as described in the next point to keep your history clean.
Before you create a pull request do git fetch origin and git rebase origin/master (given origin is the remote for upstream and not your own remote, check your .git/config or do git remote -v | grep github.com/qgis).
You may do a git rebase like in the last line repeatedly without doing any damage (as long as the only purpose of your branch is to get merged into master).
Attention: After a rebase you need to git push -f to your forked repo. CORE DEVS: DO NOT DO THIS ON THE QGIS PUBLIC REPOSITORY!

3.8.1.2. Special labels to notify documentors ¶

Besides common tags you can add to classify your PR, there are special ones you can use to automatically generate issue reports in QGIS-Documentation repository as soon as your pull request is merged:

[needs-docs] to instruct doc writers to please add some extra documentation after a fix or addition to an already existing functionality.
[feature] in case of new functionality. Filling a good description in your PR will be a good start.

Please devs use these labels (case insensitive) so doc writers have issues to work on and have an overview of things to do. BUT please also take time to add some text: either in the commit OR in the docs itself.

3.8.1.3. For merging a pull request ¶

Option A:

click the merge button (Creates a non-fast-forward merge)

Option B:

Checkout the pull request
Test (Also required for option A, obviously)
checkout master, git merge pr/1234
Optional: git pull --rebase: Creates a fast-forward, no “merge commit” is made. Cleaner history, but it is harder to revert the merge.
git push (NEVER EVER use the -f option here)

3.9. Patch file naming ¶

If the patch is a fix for a specific bug, please name the file with the bug number in it e.g. bug777fix.patch, and attach it to the original bug report in GitHub.

If the bug is an enhancement or new feature, it’s usually a good idea to create a ticket in GitHub first and then attach your patch.

3.10. Create your patch in the top level QGIS source dir ¶

This makes it easier for us to apply the patches since we don’t need to navigate to a specific place in the source tree to apply the patch. Also when I receive patches I usually evaluate them using merge, and having the patch from the top level dir makes this much easier. Below is an example of how you can include multiple changed files into your patch from the top level directory:

cd QGIS
git checkout master
git pull origin master
git checkout newfeature
git format-patch master --stdout > bug777fix.patch

This will make sure your master branch is in sync with the upstream repository, and then generate a patch which contains the delta between your feature branch and what is in the master branch.

3.10.1. Getting your patch noticed ¶

QGIS developers are busy folk. We do scan the incoming patches on bug reports but sometimes we miss things. Don’t be offended or alarmed. Try to identify a developer to help you and contact them asking them if they can look at your patch. If you don’t get any response, you can escalate your query to one of the Project Steering Committee members (contact details also available in the Technical Resources).

3.10.2. Due Diligence ¶

QGIS is licensed under the GPL. You should make every effort to ensure you only submit patches which are unencumbered by conflicting intellectual property rights. Also do not submit code that you are not happy to have made available under the GPL.

3.11. Obtaining GIT Write Access ¶

Write access to QGIS source tree is by invitation. Typically when a person submits several (there is no fixed number here) substantial patches that demonstrate basic competence and understanding of C++ and QGIS coding conventions, one of the PSC members or other existing developers can nominate that person to the PSC for granting of write access. The nominator should give a basic promotional paragraph of why they think that person should gain write access. In some cases we will grant write access to non C++ developers e.g. for translators and documentors. In these cases, the person should still have demonstrated ability to submit patches and should ideally have submitted several substantial patches that demonstrate their understanding of modifying the code base without breaking things, etc.

Nota

Since moving to GIT, we are less likely to grant write access to new developers since it is trivial to share code within github by forking QGIS and then issuing pull requests.

Always check that everything compiles before making any commits / pull requests. Try to be aware of possible breakages your commits may cause for people building on other platforms and with older / newer versions of libraries.

When making a commit, your editor (as defined in $EDITOR environment variable) will appear and you should make a comment at the top of the file (above the area that says ‘don’t change this’). Put a descriptive comment and rather do several small commits if the changes across a number of files are unrelated. Conversely we prefer you to group related changes into a single commit.