wiki:codebase
Last modified 10 years ago Last modified on 08/01/16 17:47:03

Política de Uso do Repositório de Código Fonte do TerraMA²

Autor: Gilberto Ribeiro de Queiroz
Data: 19/08/2015

Resumo: Este documento explica como os desenvolvedores devem criar forks do repositório original do TerraMA² e configurar seus repositórios locais para mantê-los em sincronia com o original, bem como submeter pedidos para incorporação de modificações no repositório original.

O repositório oficial do TerraMA² encontra-se disponível no seguinte endereço: ​https://github.com/TerraMA2/terrama2.

Este repositório não deve ser utilizado diretamente, ou seja, deve-se criar forks a partir dele e submeter pull requests.

Em todo caso, se você quiser clonar este repositório oficial, poderá utilizar o git em linha de comando da seguinte forma: 

git clone https://github.com/TerraMA2/terrama2.git .

GitHub? e a Organização TerraMA²

Atualmente a organização ​TerraMA² criada no ​GitHub possui três times:

  • Owners: os coordenadores técnicos do projeto possuem acesso irrestrito à organização, criação de repositórios e administração de integrantes dos times.
  • Managers: o gerente de desenvolvimento e líder de equipe possuem acesso de administração do ​repositório principal do TerraMA².
  • Developers: o time de desenvolvedores do TerraMA² possui acesso de escrita ao ​repositório principal do TerraMA².

Os desenvolvedores são encorajados a utilizar o recurso de criação de forks do repositório oficial do TerraMA². Desta forma, é possível que um desenvolvedor seja capaz de realizar modificações, correções e experimentos sem causar inconsistências no repositório oficial. Assim, modificações devem ser submetidas como pull requests.

Observação: No TerraMA² será empregado um sistema de peer-review do código fonte, cuja dinâmica será estabelecida com a equipe de desenvolvimento.

Fazendo o Fork do Repositório Principal

Na janela do ​GitHub, navegue até o ​repositório do TerraMA².

O botão de Fork se encontra no canto superior direito da página. Basta clicar nesta opção e você terá feito um fork do repositório original.

Configurando seu Fork para Mantê-lo Sincronizado com o Repositório Original

Crie uma cópia local do seu fork: 

$ git clone https://github.com/seu-nome-usuário/terrama2

Em seguida, entre na pasta terrama2 e ajuste o nome de usuário e e-mail: 

git config user.name your-github-login
git config user.email your-github-email-contact

Para configurar o git para sincronizar a sua cópia local com o repositório original:

1) Vá ao seu navegador e acesse o repositório ​original do TerraMA².

2) Na barra à direita, copie o endereço do repositório original: ​https://github.com/TerraMA2/terrama2.git.

3) Na linha de comando, vá para a pasta em que você criou a cópia local do seu fork.

4) Digite: 

$ git remote -v

para ver o repositório remoto que se encontra configurado atualmente para seu fork. A saída será algo como: 

origin	https://github.com/seu-nome-usuário/terrama2 (fetch)
origin	https://github.com/seu-nome-usuário/terrama2 (push)

5) Digite: 

$ git remote add upstream https://github.com/TerraMA2/terrama2.git

6) Verifique se o novo upstream repository especificado encontra corretamente apontado: 

$ git remote -v

Você deverá ver a URL do seu fork como origin e a URL do repositório original como upstream, conforme a saída abaixo: 

origin	https://github.com/seu-nome-usuário/terrama2 (fetch)
origin	https://github.com/seu-nome-usuário/terrama2 (push)
upstream	https://github.com/TerraMA2/terrama2.git (fetch)
upstream	https://github.com/TerraMA2/terrama2.git (push)

Sincronizando Sua Cópia Local e Seu Fork com o Repositório Original

1) Faça o fetch dos branches e seus respectivos commits do repositório upstream: 

$ git fetch upstream

A saída será algo como: 

remote: Counting objects: 6, done.
remote: Compressing objects: 100% (3/3), done.
remote: Total 6 (delta 1), reused 6 (delta 1), pack-reused 0
Unpacking objects: 100% (6/6), done.
From https://github.com/TerraMA2/terrama2
 * [new branch]      master     -> upstream/master

2) Se você estiver fazendo modificações no branch master, assegure-se de estar nele: 

$ git checkout master

Se você já estiver neste branch receberá uma mensagem como a abaixo: 

Already on 'master'
Your branch is up-to-date with 'origin/master'.

3) Faça o merge do upstream/master (ou do ramo desejado) com o seu ramo local para sincronizar seu repositório local com o original: 

$ git merge upstream/master

A saída será uma mensagem parecida com a seguinte: 

Updating 439f129..ff3b0da
Fast-forward
 share/sql/terrama2/terrama2-data-model-pg.sql | 3 +++
 1 file changed, 3 insertions(+)
 create mode 100644 share/sql/terrama2/terrama2-data-model-pg.sql

Fazendo Requisições de Pull (Pull Requests)

Agora que você já possui um repositório local para realizar modificações, e que está sendo sincronizado com o repositório original, você poderá fazer pedidos de push de suas modificações.

Faça o commit e push das suas modificações. Elas serão aplicadas no repositório do seu fork.

Na janela do navegador, no site do GitHub? do seu fork, selecione o ramo correto, onde você fez as modificações e em seguida selecione a opção "Compare & review".

TODO: melhorar esta seção.

Submetendo uma task list

Uma boa prática de submissão de pull requests é adicionar o que foi feito utilizando o recurso de task list do GitHub?. A ideia é auxiliar o revisor(a) sobre o que foi modificado e realizado. 

[x] - Completed Task [TICKET_NUMBER](TRAC_TICKET_URL)
[ ] - Uncompleted task

Repositório Oficial

O repositório oficial do TerraMA² encontra-se disponível no seguinte endereço: ​https://github.com/TerraMA2/terrama2.

Este repositório não deve ser utilizado diretamente, ou seja, deve-se criar forks a partir dele e submeter pull requests.

Se você quiser clonar este repositório oficial, poderá utilizar o git em linha de comando da seguinte forma: 

git clone https://github.com/TerraMA2/terrama2.git .

Se precisar de mais dicas sobre o git, veja as notas de uso básico do git que preparamos.

Referências