Importante

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

1. Uma Contribuição Passo a Passo

Nota

Embora a Documentação-QGIS seja usada para demonstrar os processos, todos os comandos e passos mostrados abaixo também se aplicam ao QGIS-Website.

Se você está lendo essas linhas, certamente é porque você está desejano contribuir com a redação da documentação do QGIS e está buscando saber como fazê-lo. Você veio ao lugar certo! O presente documento irá guiar você através dos diferentes caminhos para atingir este objetivo, mostrando a você os passos principais a seguir, os truques que você pode usar e as armadilhas que você deve saber a respeito.

For any help, do not hesitate to either ask in a comment on the issue report you are trying to fix or write to the QGIS-community-team list. Read general information on QGIS community support.

Vamos agora mergulhar no processo.

As fontes de documentação são armazenadas usando o sistema de controle de versão git e estão disponíveis no GitHub em https://github.com/qgis/QGIS-Documentation. Uma lista de problemas para corrigir e recursos para explicar pode ser encontrada em https://github.com/qgis/QGIS-Documentation/issues.

Dica

If you are a first-time contributor and do not know where to start from, you may be interested in tackling our welcoming issue reports.

Existem duas maneiras principais, não mutuamente exclusivas, de modificar os arquivos:

1. Using the GitHub web interface

2. Using Git command line tools.

1.1. Usando a interface web do GitHub

A interface web GitHub permite você fazer o seguinte:

• editar arquivos

• Pré-visualize e envie suas mudanças

• faça uma solicitação para ter suas mudanças inseridas no repositório principal

• criar, atualizar ou deletar partes

If you are not yet familiar with git and GitHub vocabulary, you may want to read the GitHub Hello-world project to learn some basic vocabulary and actions that will be used below.

Nota

Se você estiver consertando um problema relatado

Se você está fazendo mudanças para consertar um problema <https://github.com/qgis/QGIS- Documentation/issues>`_, adicione um comentário para o relatório do problema para assigná-lo a você. Isso irá evitar que mais de uma pessoa trabalhe no mesmo problema.

1.1.1. Fork QGIS-Documentação

Assuming you already have a GitHub account, you first need to fork the source files of the documentation.

Navegue pela página QGIS-Documentation repository e clique no botão no canto superior direito.

Na sua conta GitHub você encontrará o repositório da Documentação-QGIS (https://github.com/<YourName>/QGIS-Documentation). Este repositório é uma cópia do repositório de Documentação-QGIS oficial onde você tem acesso completo de gravação e você pode fazer mudanças sem afetar a documentação oficial.

1.1.2. Faça mudanças

Há diferentes formas de contribuir para a documentação do QGIS. Nós mostramos elas separadamente abaixo, mas você pode alternar entre um processo e outro sem nenhum problema.

Alternativa 1: Use o atalho Editar no GitHub

Pages on the QGIS documentation website can be edited quickly and easily by clicking on the Edit on GitHub link at the top right of each page, or in the drop-down menu at the bottom of the left sidebar.

1. Isso abrirá o arquivo no ramo qgis:master com uma mensagem no topo da página dizendo a você que você não tem acesso para escrever neste repositório e que suas mudanças serão aplicadas a uma novo ramo do seu repositório.

2. Faça suas mudanças. Uma vez que a documentação é escrita usando a sintaxe reStructureText, dependendo das suas mudanças, talvez você precise se basear em writing guidelines.

3. Once you have finished modifying the file, press Commit changes… and add a short title explaining your changes. You can also provide a more detailed explanation, if necessary.

4. Press Propose changes, saving the modifications to your repository. This will generate a dedicated branch (patch-xxx) in your repository and the web browser will open the Comparing changes page.

   • If the issue you are addressing does not need any further changes, jump to the Share your changes via Pull Request section below.

   • Se há mudanças adicionais que você queira fazer antes de enviá-las ao QGIS, siga os seguintes passos:

     1. Navigue até seu fork de QGIS-Documentation (https://github.com/<YourName>/QGIS-Documentation)

     2. Click on and search for the new patch-xxx branch.

     3. Select it. The button will now display Branch: patch-xxx.

     4. Jump down to the Modify files section below.

Alternativa 2: Crie um ramo ad hoc no seu repositório de documentação

Você pode editar arquivos diretamente do seu fork da Documentação QGIS .

First, make sure that your master branch is up to date with upstream, i.e. qgis/QGIS-Documentation:master branch. To do so:

1. Vá para a página principal do seu repositório, ou seja, https://github.com//QGIS-Documentation. O ramo mestre deve estar ativo com uma menção se está atualizado com qgis/QGIS-Documentação:mestre ou não.

   Se houver comprometimento antes do ramo a montante, é melhor você usar a alternativa anterior botão de atalho ` até alinhar seu ramo ``mestre`.

   Se houver apenas compromete por trás:

   1. Expand the Sync fork drop-down menu on the right. You can:

      • Compare the branches and see new changes in the upstream branch you do not yet have in yours

      • Fetch and merge: brings changes from the upstream branch into yours.

   2. Click Fetch and merge: after the process, your branch is mentioned as up to date with qgis/QGIS-Documentation:master.

2. Click on in the upper left corner of your forked QGIS-Documentation repository and enter a unique name in the text field to create a new branch. It is advised that the name of the new branch relates to the problem you intend to fix. Convenient for identifying the branch later.

3. Press Create branch <branch_name> from master. The button should now display branch_name.

4. You are ready to start new changes on top of your new branch.

Atenção

Faça suas alterações em um ad hoc branch, nunca no master branch

Por convenção, evite fazer mudanças no seu ramo master exceto quando você mescla as modificações do ramo master do qgis/QGIS-Documentation na sua cópia do repositório da Documentação-QGIS. Ramos separados permitem que você trabalhe em múltiplos problemas ao mesmo tempo sem interferir em outros ramos. Se você cometer um erro você sempre poderá deletar um ramo e começar novamente criando um novo ramo a partir do ramo principal.

1.1.3. Modificar arquivos

1. Make sure the branch you want to modify is active: its name is displayed in the top left menu or in the page URL.

2. Browse the source files to the file that needs modifications.

3. Press the ^{Edit this file} button.

4. Update the text following the writing guidelines

5. Once you have finished modifying the file, press Commit changes… and add a short title explaining your changes. You can also provide a more detailed explanation, if necessary.

6. Make sure Commit directly to the <branch_name> branch is selected.

7. Press Commit changes to save your modifications in the branch.

8. To update or add a new image file:

   1. Browse your branch to the folder of the file to update or add.

   2. Top right, use the Add files ► Upload files menu to select and load files from your drive. You can find hints for formatting an image for the docs at Gerenciando Capturas de Tela.

   3. If a file of the same name already exists, it gets overwritten.

   4. Commit once again your changes to the target branch.

9. Repeat the previous steps for any other files that need to be updated to fix the issue.

1.1.4. Compartilhe suas alterações via Solicitação de recebimento

You need to make a pull request to integrate your changes into the official documentation.

Iniciar uma nova solicitação pull

1. If you used the Edit on GitHub link, after you commit your changes, GitHub automatically opens a new page comparing the changes you made in your patch-xxx branch to the qgis/QGIS-Documentation:master branch.

2. In all the cases, the comparing changes page can be reached by going to the “Pull requests” page of your repository and click on New pull request.

Comparar alterações

Se você vê duas caixas de diálogo, uma que diz base:master e a outra compare:branch_name (veja a figura), isso somente irá mesclar suas mudanças de um de seus ramos para o seu ramo principal. Para consertar isso, clique no link compare across forks.

Fig. 1.8 Se a sua página Comparação de alterações tiver esta aparência, clique no link compare entre forks.

Você deve ver quatro menus drop-down. Isso permitirá que você compare as alterações que você fez em sua ramificação com a ramificação principal na qual deseja mesclar. Eles são:

• base fork: o fork em que você quer mesclar suas mudanças

• base: o branch do fork base no qual você deseja mesclar suas alterações

• head fork: o fork que tem as alterações que você deseja incorporar no base fork

•  compare: o ramo com essas alterações

Selecione qgis/QGIS-Documentation como base fork com master como base, defina o head fork para o no seu repositório <YourName>/QGIS-Documentation, e defina comparar com o seu branch modificado.

Fig. 1.9 Comparando alterações entre qgis/QGIS-Documentation e seu repositório

Uma verificação verde com as palavras Capaz de mesclar mostra que suas alterações podem ser mescladas na documentação oficial sem conflitos.

Clique no botão Create pull request.

Aviso

Se você vir |githubNãoMescla|

This means that there are conflicts. The files that you are modifying are not up to date with the branch you are targeting because someone else has made a commit that conflicts with your changes. You can still create the pull request but you’ll need to fix any conflicts to complete the merge.

Dica

Apesar de ser traduzida, a versão mais recente da documentação do QGIS ainda é mantida e os problemas existentes foram corrigidos. Se você estiver corrigindo problemas para uma versão diferente, altere base de mestre para o ramo apropriado liberar_... nas etapas acima.

Descreva sua solicitação de pull

A text box will open: fill in a title and any relevant description of the changes you are proposing.

If this relates to a particular issue, add the issue number to your comments. This is done by entering # and the issue number (e.g. #1234). If preceded by terms like fix or close, the concerned issue will be closed as soon as the pull request is merged.

Adicione links a todas as páginas de documentação que você está alterando.

Clique em Criar pull request.

Revisar e comentar a solicitação de pull

As seen above, anyone can submit modifications to the documentation through pull requests. Likewise anyone can review pull requests with questions and comments. Perhaps the writing style doesn’t match the project guidelines, the change is missing some major details or screenshots, or maybe everything looks great and is in order. Reviewing helps to improve the quality of the contribution, both in form and substance.

Para revisar uma pull request:

1. Vá para a página pull requests page e clique na pull request que você deseja comentar.

2. Na parte inferior da página, você encontrará uma caixa de texto onde pode deixar comentários gerais sobre a pull request.

3. Para adicionar comentários sobre linhas específicas,

   1. Click on and find the file you want to comment on. You may have to click on < > ^{Display the source diff} to see the changes.

   2. Role até a linha que você deseja comentar e clique no |githubMaisAzul|. Isso abrirá uma caixa de texto permitindo que você deixe um comentário.

Comentários de linha específicos podem ser publicados:

• como comentários únicos, usando o botão Adicionar comentário único. Eles são publicados conforme você avança. Use isso apenas se você tiver poucos comentários a adicionar ou ao responder a outro comentário.

• or as part of a review, pressing the Start a review button. Your comments are not automatically sent after validation, allowing you to edit or cancel them afterwards, to add a summary of the main points of the review or global instructions regarding the pull request and whether you approve it or not. This is the convenient way since it’s more flexible and allows you to structure your review, edit the comments, publish when you are ready and send a single notification to the repository followers and not one notification for each comment. Get more details.

Fig. 1.10 Comentando uma linha com uma sugestão de alteração

Os comentários da linha podem incorporar sugestões que o escritor da pull request pode aplicar à pull request. Para adicionar uma sugestão, clique no :sup: Insira uma sugestão na parte superior da caixa de texto do comentário e modifique o texto no bloco de sugestões.

Dica

**Prefira enviar sugestões à sua pull request como um lote **

Como autor da pull request, ao incorporar diretamente os comentários dos revisores em sua pull request, evite usar o botão :guilabel:`Confirmar sugestão’ na parte inferior do comentário, quando você tiver muitas sugestões para abordar e preferir adicioná-las como uma confirmação em lote, isso é:

1. Mude para a aba |githubArquivosAlterados|

2. Pressione Adicionar sugestão ao lote para cada reformulação que você gostaria de incluir. Você verá um contador aumentando à medida que avança.

3. Pressione qualquer um dos botões :guilabel:`Sugestões de empenho ` quando estiver pronto para aplicar as sugestões ao seu pull request e digite uma mensagem descrevendo as alterações.

Isso adicionará todas as modificações ao seu ramo como um único resultando em um histórico de alterações mais legível e menos notificações para os seguidores do repositório. Aliás, proceder assim também economizará muitos cliques.

Fazer correções

Uma nova solicitação irá ser adicionada automaticamente à Pull requests list. Outros editores e administradores irão revisar sua solicitação e eles irão fazer sugestões ou pedir por correções.

Uma solicitação pull também acionará verificações de compilação automatizadas (por exemplo, para primeira formatação, sintaxes de código python) e os relatórios são exibidos na parte inferior da página. Se um erro for encontrado, uma cruz vermelha aparecerá ao lado do seu commit. Clique na cruz vermelha ou em Detalhes na seção de resumo na parte inferior da página de pull request para ver os detalhes do erro. Você terá que corrigir quaisquer erros ou avisos relatados antes que suas alterações sejam submetidas ao repositório ``qgis/QGIS-Documentação`.

You can make modifications to your pull request until it is merged with the main repository, either to improve your request, to address requested modifications, or to fix a build error:

1. Click on the tab in your pull request page

2. Press … menu on the right of the filename that you want to modify, and select Edit file.

3. The file opens in edit mode; add your modifications and commit.

Qualquer mudança adicional será automaticamente adicionada à sua solicitação se você fez tais mudanças no mesmo ramo que você enviou em sua solicitação. Por essa razão, você deveria fazer mudanças adicionais apenas se essas mudanças são relacionadas ao problema que você está tentando consertar nessa solicitação.

Se você deseja corrigir outro problema, crie um novo branch para essas alterações e repita as etapas acima.

Um administrador vai mesclar sua contribuição após a correção de quaisquer erros de compilação e depois que você e os administradores estiverem satisfeitos com suas alterações.

1.1.5. Excluir seu ramo mesclado

Você pode deletar seu ramo após suas mudanças serem mescladas. Deletar ramos velhos evita que você tenha ramos inúteis e desatualizados no seu repositório.

1. Navegue até seu fork do repositório QGIS-Documentação (https://github.com/<YourName>/QGIS-Documentation).

2. Clique na aba Ramos. Abaixo de Suas ramificações você verá uma lista de suas ramificações.

3. Clique no botão |excluir selecionado| :sup: Ícone Deletar esse ramo para excluir quaisquer ramos indesejados.

1.2. Usando as ferramentas de linha de comando Git

A interface da web do GitHub é uma maneira fácil de atualizar o repositório de documentação do QGIS com suas contribuições, mas não oferece ferramentas para:

• agrupe seus comprometimentos e limpe seu histórico de alterações

• conserte possíveis conflitos com o repositório principal

• construa a documentação para testar suas mudanças

Você precisa instalar git no seu disco rígido para ter acesso a ferramentas mais avançadas e poderosas e ter uma cópia local do repositório. Algumas ferramentas básicas que você pode precisar com frequência estão mostrados abaixo. Você também terá regras importantes para respeitar, mesmo se optar pela interface da web.

Nos exemplos de código abaixo, as linhas que começam com $ mostram comandos que você deve digitar enquanto # são comentários.

1.2.1. Repositório local

Agora você está pronto para obter um clone local do seu repositório da Documentação QGIS.

Você pode clonar seu repositório QGIS usando o URL da web da seguinte maneira:

# move to the folder in which you intend to store the local repository
$ cd ~/Documents/Development/QGIS/
$ git clone https://github.com/<YourName>/QGIS-Documentation.git

A antiga linha de comando é simplesmente um exemplo. Você deve adaptar o caminho e a URL do repositório, substituindo <YourName> pelo seu nome de usuário do github.

Verifique o seguinte:

# Enter the local repository
$ cd ./QGIS-Documentation
$ git remote -v
origin  https://github.com/<YourName>/QGIS-Documentation.git (fetch)
origin  https://github.com/<YourName>/QGIS-Documentation.git (push)
$ git branch
* master

• origin é o nome do repositório remoto do seu repositório QGIS-Documentation.

• master é o default main branch. Você nunca deve usá-lo para contribuir! Nunca!

Alternatively you can clone your QGIS repository using the SSH protocol:

# move to the folder in which you intend to store the local repository
$ cd ~/Documents/Development/QGIS/
$ git clone [email protected]:<YourName>/QGIS-Documentation.git

Dica

Permission denied (publickey) error?

If you get a Permission denied (publickey) error with the former command, there may be a problem with your SSH key. See GitHub help for details.

Verifique o seguinte se você usou o protocolo SSH:

# Enter the local repository
$ cd ./QGIS-Documentation
$ git remote -v
origin  [email protected]:<YourName>/QGIS-Documentation.git (fetch)
origin  [email protected]:<YourName>/QGIS-Documentation.git (push)
$ git branch
* master

Você pode começar a trabalhar aqui, mas no processo de longo prazo, você terá muitos problemas quando enviar sua contribuição (chamada Pull Request no processo do github), pois a ramificação principal do repositório qgis/QGIS-Documentação divergirá de seu local /repositório remoto. Em seguida, você precisa acompanhar o repositório remoto principal e trabalhar com ramificações.

1.2.2. Adicione um outro repositório remoto

Para poder acompanhar o trabalho no projeto principal, adicione um novo repositório remoto no seu repositório local. Este novo repositório remoto é o repositório Documentação QGIS do projeto QGIS:

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

Da mesma forma, você pode usar o protocolo SSH para adicionar um repositório remoto ao seu repositório local:

$ git remote add upstream [email protected]:qgis/QGIS-Documentation.git
$ git remote -v
origin  [email protected]:<YourName>/QGIS-Documentation.git (fetch)
origin  [email protected]:<YourName>/QGIS-Documentation.git (push)
upstream        [email protected]:qgis/QGIS-Documentation.git (fetch)
upstream        [email protected]:qgis/QGIS-Documentation.git (push)

Agora você tem a escolha entre dois repositórios remotos:

• origin para colocar seu branch local em seu repositório remoto

• upstream to merge (if you have right to do so) your contribution to the official one OR to update your master branch of local repository from the master branch of the official repository.

Nota

upstream é apenas um rótulo, um tipo de nome padrão, mas você pode chamá-lo como quiser.

1.2.3. Atualize sua ramificação base

Antes de trabalhar em uma nova contribuição, você sempre deve atualizar seu branch principal em seu repositório local. Supondo que você esteja disposto a enviar alterações à documentação de teste, execute as seguintes linhas de comando:

# switch to master branch (it is easy to forget this step!)
$ git checkout master
# get "information" from the master branch in the upstream repository
# (aka qgis/QGIS-Documentation's repository)
$ git fetch upstream master
# merge update from upstream/master to the current local branch
# (which should be master, see step 1)
$ git merge upstream/master
# update **your** remote repository (aka <YourName>/QGIS-Documentation)
$ git push origin master

Agora você tem seus repositórios locais e remotos que têm seu master branch atualizado com o master branch oficial da Documentação QGIS. Você pode começar a trabalhar em sua contribuição.

Nota

Mude o branch se desejar contribuir para o documento lançado

Junto com a documentação de teste, continuamos a corrigir problemas na última versão, o que significa que você também pode contribuir com ela. Siga o código de amostra da seção anterior, substituindo mestre pelo ramo correspondente da documentação mais recente.

1.2.4. Contribua para o seu branch de produção

Now that your base branch is updated, you need to create a dedicated branch in which you add your contribution. Always work on a branch other than the base branch! Always!

# Create a new branch
$ git checkout -b myNewBranch
# checkout means go to the branch
# and -b flag creates a new branch if needed, based on current branch
# Let's check the list of existing branches (* indicates the current branch)
$ git branch
master
release_2.18
...
* myNewBranch
# You can now add your contribution, by editing the concerned file(s)
# with any application (in this case, vim is used)
$ vim myFile
# once done
$ git add myFile
$ git commit

Algumas palavras sobre os comandos commit/push:

• Tente commit apenas uma contribuição (alteração atômica), ou seja, resolver apenas um problema

• tente explicar com cuidado o que você muda no título do seu commit e na descrição. A primeira linha é um título e deve começar por uma letra maiúscula e ter 80 caracteres, não termina com um .. Seja conciso. Sua descrição pode ser mais longa, terminar com um . e você poderá fornecer muito mais detalhes.

• use um # com um número para se referir a um problema. Marque o item com Corrigir se você corrigir o ticket: seu commit fechará o ticket.

Agora que suas alterações foram salvas e commited no seu local branch, você precisa enviá-las ao seu repositório remoto para criar uma pull request:

$ git push origin myNewBranch

1.2.5. Compartilhe suas alterações

Agora você pode ir ao seu repositório do github e create a Pull Request conforme mostrado anteriormente. Certifique-se de criar um PR de seu branch para o branch remoto que você deseja repositório oficial da Documentação QGIS.

1.2.6. Limpe seu repositório local e remoto

After your PR has been merged into the official QGIS-Documentation, you can delete your branch. If you work a lot this way, in few weeks you will get a lot of unuseful branches. So keep your repository clean this way:

# delete local branch
$ git branch -d myNewBranch
# Remove your remote myNewBranch by pushing nothing to it
$ git push origin :myNewBranch

E não se esqueça de atualizar o branch master no seu repositório local!

1.3. Leitura complementar

• Além da interface da web do Github e das ferramentas de linha de comando git mostradas acima, também existem aplicativos da GUI que você pode usar para criar e gerenciar suas contribuições para a documentação.

• Quando as alterações na pull request apresentam conflito com as alterações recentes enviadas para o branch de destino, os conflitos precisam ser resolvidos antes que a mescla seja possível:

  • if the conflict relates to few competing lines, a Resolve conflicts button is available in the GitHub pull request page. Press the button and resolve the issue as explained at Resolving a merge conflict on GitHub

  • if the conflict involves files renaming or removal, then you’d need to resolve the conflict using git command lines. Typically, you have to first rebase your branch over the target branch using git rebase targetBranch call and fix the conflicts that are reported. Read more at Resolving a merge conflict using the command line

• Sometimes, at the end of the proofreading process, you may end up with changes split into multiple commits that are not necessarily worth it. Git command lines help you squash these commits to a smaller number and more meaningful commit messages. Some details at Using git rebase on the command line