Utilização do Mercurial

From ADempiere
Jump to: navigation, search
This Wiki is read-only for reference purposes to avoid broken links.


Esta página tem por objetivo ilustrar a utilização básica do Mercurial para o desenvolvimento do projeto de localização brasileira do Adempiere, em função disso, alguns detalhes destas instruções são exclusivas do repositório localization_br do projeto Adempiere

Começaremos com uma breve introdução sobre as diferenças do Mercurial para o SVN, e após isso, seguem exemplos de algumas operações básicas utilizando a interface de linha de comando, e a seguir algumas operações utilizando o plugin para o Eclipse.

Para um melhor entendimento de como o Mercurial funciona, é aconselhável a leitura do livro Mercurial: The Definitive Guide, em alguns momentos deste artigo serão feitas referências a este livro. Um outro artigo interessante sobre o uso do Mercurial pode ser encontrado em HgInit: a Mercurial tutorial

Introdução minimalista ao Mercurial

O Mercurial é uma ferramenta de controle de versões na qual o conteúdo armazenado localmente na estação de trabalho do desenvolvedor é uma cópia fiel do repositório, incluindo todo o seu histórico, branches, tags, etc. Inclusive o próprio desenvolvedor pode re-exportar este clone para outros desenvolvedores. Isto permite diversas formas de utilização, uma delas é o mantenimento de uma ou mais branches privadas, que nunca serão publicada no repositório de origem.

É aconselhável a clonagem fiel do repositório, e, a partir deste clone, gerar um outro clone "de trabalho", isto dificulta um pouco a utilização via plugin do Eclipse e por isso alguns desenvolvedores podem preferir trabalhar direto no clone que o plugin baixou, isto facilita o sincronismo com o repositório de origem (upstream).

Na parte deste guia em que abordamos a utilização da linha de comando será pressuposto que estamos trabalhando utilizando um clone perfeito do repositório remoto, e um outro clone deste repositório local para o trabalho. Já na parte em que aborda-se a utilização do plugin, será pressuposto que o clone de trabalho é originado diretamente do repositório remoto. Com habilidade é possível mixar as duas coisas de forma funcional, mas isto não faz parte do escopo deste guia.

Instalando o Mercurial

Linux

Para ter o mercurial instalado em seu linux basta utilizar o gerenciador de pacotes de sua distribuição e instalar o pacote mercurial. Para a utilização a partir do Eclipse pode ser necessária a instalação de um pacote que permita ao seu ambiente solicitar a senha. O pacote ssh-askpass-gnome, ou apenas ssh-askpass caso não utilize o gnome, podem ser utilizados.

Os nomes aqui utilizados estão presentes na última release do Debian, talvez ocorram pequenas alterações no nome para a sua distribuição.

Windows

O pacote para a instalação no windows está disponível na Página de Download do Mercurial.

O SourceForge.net utiliza o protocolo ssh para acesso de leitura e escreta, no Windows, por não ter suporte nativo ao ssh a situação fica um pouco complicada, por isto este guia segue os comandos no Linux. Para tornar o windows compatível com o ssh e com os comandos deste guia, é interessante a instalação do Ambiente Cygwin, lembrando-se de instalar o pacote OpenSSH no processo de instalação.

Existem outras alternativas para a combinação Windows+Mercurial+SSH, uma delas é o TortoiseHG que se integra ao desktop do Windows.

Linha de Comando

ATENÇÃO: Este guia ainda não tem uma sequência funcional de comandos, alguns são funcionais, mas boa parte deles são exemplos, preste atenção à referências para supostas branches, por exemplo.

Clonando um repositório

O seguinte comando irá clonar fielmente o repositório na máquina local, é aconselhável não utilizar este repositório para trabalhar.

$ hg clone http://hg.code.sf.net/p/adempiere/localization-br adempierelbr

Se visualizarmos o diretório adempierelbr, perceberemos que dentro dele tem apenas um subdiretório ".hg"... é neste subdiretório que está todo o conteúdo do repositório. Os arquivos de trabalho serão gravados no diretório adempierelbr... mas como utilizaremos este apenas como clone do original, aqui ele vai ficar intocado. Nas partes seguintes deste guia, para padronizar e deixar mais claro o entendimento, este repositório local será referenciado como repostório local de referência, e o repositório remoto do projeto, será sempre referenciado como repositório remoto.

Clonando o clone

Para trabalharmos utilizaremos um outro clone, como cada clone é um repositório completo, basta ir um nível antes do clone feito no item anterior, e cloná-lo novamente:

$ hg clone adempierelbr lbrwork

Pronto... agora a pasta lbrwork é um clone do clone, deve-se preferir trabalhar dentro desta pasta. Igualmente aos outros repositórios, todas as referências posteriores a este serão identificadas como repositório de trabalho.

Escolhendo a branch de origem

Ao trabalhar com o localization_br, todo o desenvolvimento deve ter por base a branch "development", portanto, precisamos "selecionar" esta branch como sendo a nossa origem, deve-se entrar no diretório de trabalho "lbrwork" e rodar o comando "hg update"

$ cd lbrwork
$ hg update development

Após este comando, os arquivos do repositório ".hg" serão copiados para o diretório lbrwork, e já podem ser editados livremente, porém, é aconselhável iniciar uma branch para este trabalho, isto permite isolar cada desenvolvimento um do outro.

Os arquivos e diretórios gravados diretamente dentro da pasta lbrwork, será sempre referenciado como diretório de trabalho. Atenção, não confundir com repositório de trabalho, já citado anteriormente, que é todo o repositório, contido dentro da pasta .hg.

Criando uma branch

Criar uma branch é simples... basta digitar o seguinte comando:

$ hg branch fulano

A partir deste ponto, seu repositório tem uma branch chamada fulano. É aconselhável nunca editar diretamente os branches stable e development do localization_br, estas branches devem apenas receber merge das branches dos desenvolvedores, de acordo com o Guia de desenvolvimento.

Colocando as mãos na massa

Este é o ponto onde você apenas precisa cuidar do código, programar mesmo, aquele que é o nosso objetivo! É só apontar o seu editor ou interface preferida para os arquivos do diretório de trabalho e fazer as coisas evoluírem.

Adicionando arquivos

Por default, qualquer arquivo novo criado no diretório de trabalho não será adicionado ao repositório de trabalho. Para avisar o Mercurial que um arquivo deve fazer parte dele, utiliza-se o comando "add":

$ hg add nomedoarquivo.ext

Caso o comando seja executado sem fornecer um nome de arquivo, todos os arquivos do diretório serão adicionados ao repositório de trabalho.

A hora do commit

Após editar o código, testar, debugar, corrigir, testar de novo e ver que deu certo, chegou a hora de dar o commit... o comando para isso é o seguinte:

$ hg commit

Mas, espere um pouco... este comando apenas pega os arquivos do diretório de trabalho e coloca no diretório ".hg", que é o repositório de trabalho. Para publicar de verdade este trabalho, é preciso fazer um "push". É isso mesmo, o push é o novo commit:

$ hg push --new-branch https://fulano@hg.code.sf.net/p/adempiere/localization-br

Lógico que "fulano" deve ser substituído pelo seu nome de usuário no sf.net, e a sua senha será solicitada.

O parâmetro --new-branch é necessário pois por padrão o Mercurial se recusa a publicar novas branches, é uma medida de segurança.

Caso o último parâmetro, que é o endereço de escrita do repositório não seja fornecido, ele irá atualizar o repositório de onde foi feito o clone. Como este é o repositório de trabalho, que foi "clonado do clone", executar o push sem parâmetro, apenas atualizaria o repositório local de referência na máquina local... o que também pode ser feito, para manter as coisas sincronizadas.

Atualizando o repositório

Com alguma frequência é necessário que atualizemos o nosso repositório de trabalho para receber as mais novas atualizações dos desenvolvedores, para isto existe o comando "pull":

$ hg pull 

Como já vimos antes, isto vai trazer as alterações a partir da origem do repositório atual, que, no caso do repositório de trabalho é o repositório local de referência. Portanto, neste exemplo, a melhor sequência de comandos é a seguinte:

$ cd ../adempierelbr
$ hg pull
$ cd ../lbrwork
$ hg pull

Alternando entre branches

Aqui aparece uma das maravilhas do Mercurial: É possível alternar entre uma branch e outra!

No momento em que executamos o comando "update" no tópico que escolheu a branch de origem, o nosso diretório de trabalho passou a ter os arquivos da branch "development". E, após a execução do comando que criou a branch "fulano", tais arquivos passaram a fazer parte desta branch.

O comando "update" faz exatamente isso, altera os arquivos do diretório de trabalho para que reflitam a branch referida. O comando update não vive só de branches, é possível alternar para qualquer ponto do repositório, uma revisão, changeset, tag ou branch.

Sempre antes de executar o comando "update", certifique-se de que todas as alterações efetuadas no diretório de trabalho foram salvas no repositório de trabalho através do comando "commit".

O seguinte exemplo alterna o diretório de trabalho para a branch "stable":

$ hg update stable

O Merge

Um dos princípios básicos do Mercurial é que ele memoriza a base de cada alteração, portanto, é possível que dentro de um mesmo branch existam duas ou mais "heads". Enquanto cada desenvolvedor trabalhar dentro de sua própria branch, isto não ocorrerá. Mas, um determinado grupo de desenvolvedores pode mexer em uma branch "comunitária", e então esta situação pode ocorrer.

Neste pequeno tutorial não abordarei além disso sobre merges dentro de uma mesma branch, para mais detalhes disso é aconselhável uma leitura mas completa do livro citado no início deste artigo. O capítulo 3 do livro aborda bem este assunto.

Agora, o merge de uma branch para outra, que é o ideal de organização de um projeto.

Digamos que a branch "fulano/resposta" implemente o método que faz o Adempiere responder à pergunta essencial sobre a vida, o universo e tudo mais... chegou a hora de agregar esta feature ao branch "development" para mais testes:

$ hg update development
$ hg pull -u
$ hg merge fulano/resposta

O primeiro comando marca o diretório de trabalho para utilizar o branch "development"

O segundo comando se certifica de que estamos atualizados com relação ao repositório de origem. Atenção: Como o nosso reositório de trabalho foi clonado de um outro repositório local, é necessário antes desta sequência atualizar também o repositório local de referência.

Por último, o comando merge copia as alterações do branch "fulano/resposta" para o branch "development", o retorno para este comando pode ser algo similar ao seguinte:

1 files updated, 0 files merged, 0 files removed, 0 files unresolved
(branch merge, don't forget to commit)

Notem a última linha da saída... ela indica que precisamos dar o commit para que a mudança seja efetivada. Por enquanto ela está apenas no diretório de trabalho. O seguinte comando colocará ela no repositório de trabalho:

$ hg commit -u "agregando funcionalidades"

Lembre-se de fazer também o "push" para distribuir a contribuição aos outros desenvolvedores, pois o "commit" apenas atualiza o repositório de trabalho local.

O merge ao contrário

Para fazer testes antes de agregar o seu trabalho à outra branch, pode ser necessário trazer as últimas alterações da branch "development" para a sua branch de trabalho. Por exemplo se estivéssemos implementando um novo recurso na branch "fulano/FR42" e queremos testá-la com todas as alterações que foram feitas na branch "development" desde que iniciamos a branch "fulano/FR42", devemos fazer um merge da "development" para a "fulano/FR42":

$ hg update fulano/FR42
$ hg merge development

Se não houverem conflitos, tudo o que foi implementado na "development" desde a criação da branch "fulano/FR42" foi agregado à ela. Caso alguma alteração que ocorreu na branch "development" conflite com uma alteração da "fulano/FR42" o Mercurial tentará resolver, e se não conseguir executará alguma ferramenta para a resolução manual. Esta ferramenta pode ser configurada pela variável de ambiente "HGMERGE". Existem diversas ferramentas, por exemplo o kdiff3 (qt/KDE), o meld (Gnome) e o winmerge (Windows). Como sempre, o nosso livro de referência dá bastante detalhes sobre isso

Plugin para o Eclipse

ATENÇÃO: Esta parte do guia não dispensa a leitura da parte anterior, ela depende de muitos conceitos explicados nela. Se você pulou pra cá, volte e leia as informações sobre a linha de comando para que possa entender como o plugin funciona.

Um plugin muito bom para utilizar o Mercurial no Eclipse é o MercurialEclipse, no site dele você encontra instruções para a instalação.

Chave SSH

A autenticação SSH para o servidor do SourceForge.net pode ser um pouco chata ao utilizar o Eclipse, para isso pode ser interessante seguir este guia do sf.net para configurar as chaves SSH

A partir da alteração para o ambiente Allura do SourceForge.net, está sendo suportado o acesso leitura e escrita através do protocolo HTTPS, com autenticação de usuário e senha, não é mais necessário utilizar chaves SSH!

Operações Básicas

Nas seções a seguir, algumas galerias com screenshots de operações básicas. Todas as opções estão disponíveis através do submenu "Team", acessado pelo botão direito no Package Explorer. Se preferir, o menu Team abre diretamente se for selecionada a perspectiva Team Syncronize.

Clonar e Importar Projeto

No campo URL da primeira janela, utilizar o endereço: https://fulano@hg.code.sf.net/p/adempiere/localization-br ... lembrando de trocar 'fulano' pelo seu nome no SF.net, é também necessário preencher os campos Username e Password com os valores adequados.

Criar Branch

Publicar Modificações

Alterar diretório de trabalho

Merge