Importante
A tradução é um esforço comunitário você pode contribuir. Esta página está atualmente traduzida em 89.60%.
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.
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.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
As páginas do site de documentação do QGIS podem ser editadas rápida e facilmente clicando no link Editar no GitHub
no canto superior direito de cada página.
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.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.Depois de clicar em Propor alterações, o github navegará para a página Comparando alterações.
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
O atalho Editar no GitHub
também está disponível no menu suspenso na parte inferior da barra lateral esquerda.
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 .
Primeiro, certifique-se de que seu ramo mestre
esteja atualizado com o ramo qgis:mestre(masculino)
. Para fazer isso:
Vá para a página principal do seu repositório, ou seja,
https://github.com//QGIS-Documentation
. O ramomestre
deve estar ativo com uma menção se está atualizado comqgis/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:
Expanda o menu suspenso Buscar a montante à direita. Você pode
Compare as ramificações e veja novas mudanças no repositório principal
Buscar e mesclar: leva as alterações do ramo a montante para o seu.
Vamos clicar em Buscar e mesclar: após o processo, seu ramo é mencionado como atualizado com
qgis/QGIS-Documentação:mestre
.
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 . The name of the new branch should relate to the problem you intend to fix. The button should now say Branch: branch_name
Você está pronto para iniciar novas mudanças em cima dele.
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
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.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.
Navegue até seu fork do repositório QGIS-Documentação (
https://github.com/<YourName>/QGIS-Documentation
).Clique na aba Ramos. Abaixo de Suas ramificações você verá uma lista de suas ramificações.
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 comCorrigir
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.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