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.
Para qualquer ajuda, não hesite em perguntar através de um comentário no relatório de problema que você está tentando consertar ou escrever à lista da comunidade e time do QGIS <https://lists.osgeo.org/mailman/listinfo/qgis-community-team>`_. Mais detalhes em Participe da Documentação.
Vamos agora mergulhar no processo.
Documentation sources are stored using the git version control system and are available on GitHub at https://github.com/qgis/QGIS-Documentation. A list of issues to fix and features to explain can be found at 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 reports.
There are two main ways, not mutually exclusive, to modify the files:
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
Se você ainda não está familiarizado com o vocabulário do git e do GitHub, talvez você queira ler o projeto do GitHub Hello-world para aprender um vocabulário básico e ações que serão usadas abaixo.
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-Documentation
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. Make changes
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.
Alternative 1: Use the Edit on GitHub shortcut
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.
Isso abrirá o arquivo no ramo
qgis:mastercom 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.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.
When you finish, make a short comment about your changes and click on Propose changes. This will generate a new branch (
patch-xxx) in your repository.After you click on Propose changes, github will navigate to the Comparing changes page.
Se você terminou de fazer mudanças, salte para Compare changes na seção Share your changes via Pull Request abaixo.
Se há mudanças adicionais que você queira fazer antes de enviá-las ao QGIS, siga os seguintes passos:
Navigue até seu fork de QGIS-Documentation (
https://github.com/<YourName>/QGIS-Documentation)Clique em
e procure pelo branch patch-xxx. Selecione esta correção de branch. O botão agora vai dizer Branch: patch-xxxVá para Modify files abaixo.
Nota
The Edit on GitHub shortcut is also available in the drop-down
menu at the bottom of the left sidebar.
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 .
Clique em no canto superior esquerdo do seu repositório bifurcado do QGIS- Documentation e digite um nome exclusivo no campo de texto para criar um novo branch. O nome do novo branch deve estar relacionado ao problema que você pretende corrigir. O botão agora deve dizer Branch: branch_name
Dica
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. Modify files
Navegue pelos arquivos de origem do seu fork do QGIS-Documentation até o arquivo que precisa ser modificado
Faça suas modificações seguinte writing guidelines
Quando você terminar, navegue para o quadro Enviar Alterações na parte inferior da página, faça um comentário curto sobre suas mudanças e clique em Commit Changes para enviar suas alterações direto para o seu ramo. Assegure-se de que Commit directly to the branch_name branch. está selecionado.
Repita os passos anteriores para qualquer outro arquivo que necessita ser atualizado para corrigir o problema
1.1.4. Share your changes via Pull Request
Você precisa fazer um pull request para integrar suas mudanças na documentação oficial.
Nota
If you used an Edit on GitHub link
Após o envio de suas alterações, o GitHub irá abrir automaticamente uma nova página comparando as mudanças que você fez no seu ramo patch-xxx para o ramo principal qgis/QGIS-Documentation.
Salte para Step 2 abaixo.
Start a new pull request
Navegue para a página principal do repositório QGIS-Documentation e clique em New pull request.
Compare changes
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.1 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.2 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
If you see 
Isso significa que existem conflitos. Os arquivos que você está modificando não estão atualizados com a ramificação que você está direcionando porque outra pessoa fez um commit que entra em conflito com suas alterações. Você ainda pode criar a pull request mas você precisa resolver quaisquer conflicts para concluir a mescla.
Dica
Though being translated, the latest version
of QGIS documentation is still maintained and existing issues are fixed. If you are
fixing issues for a different release, change base from master
to the appropriate release_... branch in the steps above.
Describe your pull request
Uma caixa de texto irá abrir: complete com todos os comentários relevantes sobre o problema da qual você está tratando.
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.
Review and comment pull request
Como visto acima, qualquer pessoa pode enviar modificações à documentação através de pull requests. Da mesma forma, qualquer pessoa pode revisar pull requests com perguntas e comentários. Talvez o estilo de escrita não corresponda às diretrizes do projeto, a alteração esteja precisando de mais alguns detalhes ou capturas de tela importantes ou talvez tudo esteja ótimo e esteja em ordem. A revisão ajuda a melhorar a qualidade da contribuição, tanto na forma como na substância.
Para revisar uma pull request:
Vá para a página pull requests page e clique na pull request que você deseja comentar.
Na parte inferior da página, você encontrará uma caixa de texto onde pode deixar comentários gerais sobre a pull request.
Para adicionar comentários sobre linhas específicas,
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.Scroll to the line you want to comment on and click on the
.
That will open a text box allowing you to leave a comment.
Specific line comments can be published either:
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.3 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 é:
Switch to the
tabPress Add suggestion to batch for each rewording you’d like to include. You will see a counter increasing as you go.
Press any of the Commit suggestions button when you are ready to apply the suggestions to your pull request, and enter a message describing the changes.
This will add all the modifications to your branch as a single commit, resulting in a more legible history of changes and less notifications for the repository followers. Incidentally, proceeding as this will also save you many clicks.
Make corrections
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.
A pull request will also trigger automated build checks (eg, for rst formatting,
python code syntaxes), and reports are displayed at the bottom of the page.
If an error is found, a red cross will appear next to your commit.
Click on the red cross or on Details in the summary section at the bottom
of the pull request page to see the details of the error. You’ll have to fix
any reported errors or warnings before your changes are committed to the
qgis/QGIS-Documentation repository.
Você pode fazer modificações ao seu pull request até que ela seja mesclada com o repositório principal, seja para melhorar seu request, para trabalhar em modificações solicitadas, ou para consertar um erro de construção.
Para fazer alterações, clique no na página de pull request e clique no botão lápis 
ao lado do nome do arquivo que você deseja modificar.
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. Delete your merged branch
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.
Navigate to your fork of the QGIS-Documentation repository (
https://github.com/<YourName>/QGIS-Documentation).Click on the Branches tab. Below Your branches you’ll see a list of your branches.
Click on the
Delete this branch icon to delete any
unwanted branches.
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:
group your commits and clean your change history
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
The former command line is simply an example.
You should adapt both the path and the repository URL, replacing <YourName>
with your github user name.
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?
Se você receber um erro de permissão negada (chave pública) com o comando anterior, pode haver um problema com sua chave SSH. Consulte Ajuda do GitHub para mais detalhes.
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
You can start to work here but in the long term process you will get a lot of issues when you will push your contribution (called Pull Request in github process) as the master branch of the qgis/QGIS-Documentation repository will diverge from your local/remote repository. You then need to keep track of the main remote repository and work with branches.
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
Along with the testing documentation, we continue to fix issues in the
latest release, meaning
that you can also contribute to it. Follow the previous section sample code,
replacing master with the corresponding branch of the latest documentation.
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 comCorrigirse 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.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. Leituras adicionais
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:
se o conflito estiver relacionado a poucas linhas concorrentes, um botão :guilabel:`Resolv conflicts’ está disponível na página de pull request do Github. Pressione o botão e resolva o problema, conforme explicado em https://help.github.com/articles/resolving-a-merge-conflict-on-github/
se o conflito envolver substituição de nome ou remoção de arquivos, você precisará resolvê-lo usando as linhas de comando git. Normalmente, você deve primeiro refazer sua ramificação sobre a ramificação de destino usando a chamada
git rebase targetBranche corrigir os conflitos relatados. Leia mais em https://help.github.com/articles/resolving-a-merge-conflict-using-the-command-line/
Às vezes, no final do processo de revisão, você pode acabar com as alterações divididas em vários commits que não valem necessariamente a pena. As linhas de comando do Git ajudam a compactar essas confirmações para um número menor e mensagens de confirmação mais significativas. Alguns detalhes em https://help.github.com/articles/using-git-rebase-on-the-command-line/