A melhor forma de colaborar directamente connosco e partilhar os seus conteúdos com a comunidade de utilizadores QGIS-PT é através da utilização do Git e da plataforma Github. O Git é um sistema distribuído de controlo de versões de código aberto desenhado para lidar com diferentes tipos de ficheiros e podendo ser utilizado em projectos de pequena a grande dimensão. O Github é um serviço de alojamento web para projectos que recorrem ao Git como ferramenta de controlo de versões. Este tutorial pertende demonstrar os passos que deverá seguir para colaborar connosco utilizando estas ferramentas de uma forma simples e eficaz.
Deverá começar por instalar o software Git. Para isso consulte a informação disponível em http://git-scm.com/book/en/Getting-Started-Installing-Git. Aqui encontrará toda a informação de que necessita para instalar o Git no seu sistema operativo (seja este Linux, MacOS ou Windows).
Para poder começar a utilizar o Github deverá efectuar o seu registo em https://github.com, introduzindo um nome de utilizador, o seu email e a sua password.
Terminados estes passos, está agora em condições de colaborar nos nossos repositórios sem grande esforço. Se consultar o Github do grupo de utilizadores QGIS-PT deverá encontrar vários repositórios. Neste tutorial iremos utilizar o repositório chamado blog e demonstrar como submeter as suas contribuições upstream. Faça login no seu Github recentemente criado (se é que ainda não fez). A primeira coisa que deverá fazer é efectuar um fork do repositório blog para o seu Github. Para isso, escreva @qgispt na caixa de pesquisa que se encontra no topo do site.
De seguida carregue no botão Fork e aguarde enquanto o repositório é replicado no seu Github.
Deverá agora visualizar uma réplica do repositório blog no seu Github. Tome nota do endereço https que é mostrado no lado direito da página (nota: se estiver à vontade com a utilização de ssh poderá usar o endereço apropriado e configurar o seu Github com a sua chave pública).
Neste tutorial iremos utilizar a linha de comandos do sistema operativo para fazermos uma cópia do nosso fork para o computador onde estamos a trabalhar. Os utilizadores com Windows têm também uma interface gráfica disponível que é instalada conjuntamente com o Git e poderão, se assim o desejarem, replicar os próximos passos com essa interface. Abra o o seu terminal/consola DOS e navegue até à directoria onde deseja criar a cópia local do seu fork (neste tutorial essa directoria será ~/Documents/QGISPT). De seguida efectue os seguintes passos substituindo a entrada o_seu_nome_de_utilizador pelo valor apropriado:
cd ~/Documents/QGISPT git clone https://github.com/o_seu_nome_de_utilizador/blog.git cd blog git remote add upstream https://github.com/o_seu_nome_de_utilizador/blog.git
Neste momento tem tudo configurado e pronto para começar a produzir conteúdos no seu computador e mais tarde submetê-los para o Github. Repare que existe agora uma nova directoria chamada blog dentro da directoria que especificou anteriormente (neste caso ~/Documents/QGISPT) com todos os conteúdos existentes no repositório. Suponha agora que desejaria criar uma nova pasta dentro do repositório e colocar lá um ficheiro de sua autoria. Usando as ferramentas do seu sistema operativo iria criar uma nova directoria (neste caso iremos chamá-la de exemplos).
Dentro desta pasta, iria em seguida colocar o seu novo ficheiro. Neste exemplo foi colocado um novo ficheiro chamado traducao.html. Depois de ter terminado a edição do seu ficheiro (ou vários ficheiros) poderá verificar o estado do seu repositório da seguinte forma:
git status
Este comando deverá devolver um output semelhante ao seguinte:
# On branch master # Untracked files: # (use "git add <file>..." to include in what will be committed) # # exemplos/traducao.html # nothing added to commit but untracked files present (use "git add" to track)
Ao analisar este output rapidamente se apercebe que existe um ficheiro que ainda não foi adicionado ao seu Git (repare na secção Untracked files). Para adicionar este ficheiro ao seu Git deverá então efectuar o seguinte:
git add exemplos/traducao.html
Volte a emitir o comando git status e irá reparar, que desta vez, o Git já sabe que existe um novo ficheiro para ser adicionado.
# On branch master # Changes to be committed: # (use "git reset HEAD <file>..." to unstage) # # new file: exemplos/traducao.html #
Na terminologia própria do Git diz-se que o ficheiro foi adicionado à staging area. No entanto este ficheiro ainda não foi realmente submetido e gravado no Git para se começar gravar todas as alterações nele efectuadas. Para o fazer deverá executar o seguinte comando:
git commit -m 'Ficheiro traducao adicionado à lista de exemplos'
Depois de emitir este comando deverá visualizar uma mensagem semelhante à seguinte:
# 1 file changed, 109 insertions(+) # create mode 100644 exemplos/traducao.html
Repare que o Git sabe que ocorreram alterações num único ficheiro e que foram adicionadas 109 novas linhas. Neste momento, todas as suas alterações foram gravadas no seu Git local. Quer isto dizer que se visitar o seu Github estas alterações ainda não estarão lá presentes. Para que possa carregar as suas alterações para o seu fork na web deverá então emitir o seguinte comando e introduzir o seu nome de utilizador e palavra-passe quando solicitado:
git push origin master
Se tudo correr bem, não verá qualquer mensagem de erro e as suas alterações deverão ter sido propagadas para o seu Github. Confirme que tal aconteceu visitando-o online.
Neste momento as suas alterações já estão na web mas apenas no seu fork. O passo em falta é colocar essas alterações no repositório do grupo de utilizadores. Para o fazer deverá efectuar um Pull request através do Github. No seu Github navegue até ao fork e carregue no botão Pull Request que se encontra no topo direito da secção que mostra a lista dos ficheiros e pastas disponíveis.
Deverá então surgir uma nova página mostrando todas as suas alterações. Confirme que tudo está correcto e carregue no botão Create Pull Request.
Finalmente, introduza um título para o seu Pull Request e, se desejar, introduza também algum comentário adicional. Carregue no botão Send Pull Request.
Neste momento um email será enviado automaticamente para os gestores do Github do grupo de utilizadores a informar que existe uma nova contribuição. Assim que possível, estes irão incluir as suas alterações no repositório central para que fiquem disponíveis para todos.
Como nota final, uma vez que já efectuou a configuração do fork no seu Github e já ficou com uma cópia local deste repositório no seu computador, da próxima vez que quiser efectuar uma alteração a um ficheiro já existente ou criar uma nova pasta/ficheiro não tem que repetir todos os passos previamente mencionados. Apenas terá que seguir as instruções anteriores a partir do primeiro comando git status. Não se esqueça que, da mesma forma que fez as suas alterações, poderão existir outros utilizadores a criar novos conteúdos e a alterar conteúdos já existentes. Para que o seu repositório local (isto é, o repositório Git que está na sua máquina) esteja sempre actualizado é boa prática que sempre que decida começar uma nova contribuição efectue primeiramente o seguinte comando:
git fetch upstream
Desta forma irá garantir que está em total sincronia com o repositório oficial do grupo de utilizadores.
Esperamos que este tutorial vos ajude e clarifique os procedimentos que deverão adoptar para contribuirem para a nossa comunidade. Qualquer dúvida que tenham não hesitem em contactar-nos na mailing list, ou através da interface de comentários disponibilizada em baixo.