Publicando seu primeiro projeto Pharo com Iceberg

Traduzido do capítulo Publishing your first Pharo project with Iceberg do livro Manage Your Code with Git and Iceberg - May 12, 2020. Leia depois o Configure corretamente seu projeto.

Neste capítulo, explicamos como você pode publicar seu projeto no Github usando o Iceberg. Não explicamos conceitos básicos como commit, push/pull, merging, ou cloning.

Uma forte pré-condição antes de ler este capítulo é que você deve ser capaz de publicar desde a linha de comando até o serviço de git hosting que você deseja utilizar. Se você não pode não espere que o Iceberg resolva isto magicamente para você. Agora, se você tiver alguns problemas com a configuração do SSH (que é o padrão com o Github), você pode usar HTTPS ou dar uma olhada no Capítulo 9 da seção que explica como gerar chaves SSH. Vamos começar.

5.1 Para os impacientes

Se você não quiser ler tudo, aqui está o resumo executivo.

• Crie um projeto em Github ou qualquer plataforma baseada em gitub.
• Configure o Iceberg para usar chaves ssh personalizadas.
• Adicionar um projeto no Iceberg.
  • Opcionalmente, mas fortemente recomendado, no repositório clonado, criar um diretório chamado src em seu sistema de arquivos. Esta é uma boa convenção.
• No Iceberg, abra seu projeto e adicione seus pacotes.
• Faça commit do seu projeto.
• [Opcional] Adicione uma linha de base para facilitar o carregamento de seu projeto.
• Empurre (push) sua alteração para seu repositório remoto.

Você está pronto. Agora podemos explicar com calma.

5.2 Arquitetura Básica

Como git é um sistema de versões distribuídas, você precisa de um clone local do repositório e uma cópia de trabalho (working copy). Sua cópia de trabalho e seu repositório local estão normalmente em sua máquina. Isto é, para este repositório local que suas alterações serão enviadas com um commit antes de serem empurradas (pushed) para repositórios remotos (Figura 5-1).Veremos no próximo capítulo que a situação é um pouco mais complexa e que Iceberg está escondendo a complexidade extra para nós.

5.3 Criar um novo projeto no Github

Enquanto você pode salvar primeiro localmente e depois criar um repositório remoto, neste capítulo criamos primeiro um novo projeto no Github. A Figura 5-2 mostra a criação de um projeto no Github. A ordem não importa realmente. O que é diferente é que você pode usar opções diferentes ao adicionar um repositório ao Iceberg, como mostraremos mais tarde.

5.4 [Opcional] configuração SSH: Diga ao Iceberg para usar suas chaves

Para poder se fazer um commit para o seu projeto no git, você deve usar HTTPS ou você precisará configurar credenciais válidas em seu sistema.Caso você use SSH (a forma padrão), você precisará certificar-se de que essas chaves estejam disponíveis para sua conta Github e também que a plataforma as acrescente para uma comunicação mais suave com o servidor. Consulte o Capítulo 9 Dicas e Truques para obter alguma ajuda na configuração de suas chaves ssh.

Vá até o navegador de configurações (settings browser), procure por “Use custom SSH keys” e digite seus dados lá como mostrado na Figura 5-3).

Alternativamente, você pode executar as seguintes expressões em seu Playground ou adicioná-las ao seu arquivo de preferências do sistema Pharo (Ver menu System item startup):

IceCredentialsProvider useCustomSsh: true. IceCredentialsProvider sshCredentials
    publicKey: 'path\to\ssh\id_rsa.pub'; 
    privateKey: 'path\to\ssh\id_rsa'

Dica Pro(fissional): isto também pode ser usado no caso de você ter um arquivo de chave não-default. Você só precisa substituir id_rsa pelo nome de seu arquivo.

5.5 Iceberg Repositories browser

A figura 5-4 mostra o painel de nível superior do Iceberg. Ele mostra que, por enquanto, você não definiu nem carregou nenhum projeto. Ele mostra o projeto Pharo e indica que não conseguiu encontrar seu repositório local ao exibir “Local repository missing” (falta um repositório local).

Primeiro você não precisa se preocupar com o projeto ou repositório Pharo se não quiser contribuir com o Pharo. Portanto, vá em frente. Agora, se você quiser entender o que está acontecendo aqui, eis a explicação. O sistema Pharo não tem nenhuma idéia de onde deve procurar o repositório git correspondente à fonte das classes que ele contém. De fato, a imagem que você está executando pode ter sido construída em algum lugar, remendada ou não muitas vezes. Entretanto, o Pharo está totalmente operacional sem ter um repositório local. Você pode navegar pelas classes e métodos do sistema porque o Pharo tem seu próprio gerenciamento interno de fontes. Este aviso apenas indica que, se você quiser fazer uma versão do sistema Pharo, você deve indicar para o sistema onde o clone e a cópia de trabalho estão localizados em sua máquina local. Portanto, se você não planeja modificar e versionar o código do sistema Pharo, você não precisa se preocupar.

5.6 Adicionar um novo projeto ao Iceberg

O primeiro passo é então adicionar um projeto ao Iceberg:

• Pressione o botão ‘+’ à direita da janela principal do Iceberg.
• Selecione a fonte do seu projeto. Em nosso exemplo, como você ainda não clonou seu projeto, escolha a opção Github.

Observe que você pode usar SSH (Figura 5-5) ou HTTPS (Figura 5-6).

(Figuras 5-5 e 5-6) instruem o Iceberg a clonar o repositório que acabamos de criar no Github. Especificamos o proprietário, projeto e localização física onde o clone local e a cópia de trabalho do Gitub estarão em seu disco.

Iceberg agora adicionou seu projeto a sua lista de projetos gerenciados e clonou um repositório vazio em seu disco. Você verá o status de seu projeto, como na Figura 5-7. Aqui está uma descrição do que você está vendo:

• MyCoolProjectWithPharo tem uma estrela e é verde. Isto geralmente significa que você tem mudanças que ainda não foram enviadas via commit, mas também podem acontecer em situações de limite não relacionadas, como esta. Não se preocupe com isso por enquanto.
• O status do projeto é “No Project Found” e isto é mais importante. Isto é normal, uma vez que o projeto está vazio. O Iceberg não consegue encontrar seus metadados. Resolveremos isso em breve.

Mais tarde, quando você tiver feito commit de alterações em seu projeto e quiser carregá-lo em outra imagem, quando você clonar novamente, você verá que o Iceberg irá apenas informar que o projeto não está carregado, como mostrado na Figura 5-8.

5.7 Conte com o reparo para socorrê-lo

Iceberg é uma ferramenta inteligente que tenta ajudá-lo a resolver os problemas que você pode enfrentar enquanto trabalha com o git. Como princípio geral, cada vez que você obtém um status com texto vermelho (como “No Project Found” ou “Detached Working Copy”), você deve pedir ao Iceberg para corrigi-lo usando o comando Repair.

O Iceberg não pode resolver todas as situações automaticamente, mas ele irá propor e explicar possíveis ações de reparo. As ações são classificadas da mais para a menos provável que estejam corretas. Cada ação tem uma explicação exibida sobre a situação e as conseqüências da sua utilização. É sempre uma boa idéia lê-las. Ajustar o seu repositório da maneira correta torna extremamente difícil perder qualquer pedaço de código com Iceberg e Pharo é geral, uma vez que Pharo contém sua própria cópia do código.

5.8 Criar metadados do projeto

Iceberg informou que não conseguiu encontrar o projeto porque faltavam alguns metadados, como o formato das codificações de código e a localização do exemplo dentro do repositório. Quando ativamos o comando de reparo, obtemos a Figura 5-9. Ela mostra a ação ” Create project metadata” (Criar metadados do projeto) e sua explanação.

Quando você escolhe criar os metadados do projeto, Iceberg mostra o sistema de arquivos de seu projeto assim como o formato do repositório como mostrado na Figura 5-10. Tonel é o formato preferido para os projetos Pharo. Ele foi projetado para ser amigável ao Windows e ao sistema de arquivos. Mude-o somente se você souber o que está fazendo!

Antes de aceitar as mudanças, é uma boa idéia adicionar uma pasta fonte (src) ao seu repositório. Faça isso pressionando o ícone +. Você será solicitado a especificar a pasta de código como mostrado na Figura 5-11. Iceberg mostrará a estrutura exata de seu projeto, como mostrado na Figura 5-12.

Depois de aceitar os detalhes do projeto, Iceberg mostra os arquivos que você estará submetendo via commit, como mostrado na Figura 5-13

Uma vez que você tenha enviado o commit com os metadados, Iceberg mostra que seu projeto foi reparado, mas não está carregado, como mostrado na Figura 5-8. Isto é normal, pois ainda não adicionamos nenhum pacote ao nosso projeto. Opcionalmente, você pode empurrar (push) suas alterações para seu repositório remoto.

Seu repositório local está pronto, vamos passar para a próxima parte.

5.9 Adicione e envie um commit o seu pacote usando o Working copy browser

Uma vez que seu projeto contenha metadados no Iceberg, Iceberg será capaz de gerenciá-lo facilmente. Clique duas vezes em seu projeto para abrir um Working copy browser para seu projeto. Ele lista todos os pacotes que compõem seu projeto. Neste momento, você não tem nenhum. Adicione um pacote pressionando o botão icônico + (Add Package), como mostrado na Figura 5-14.

Novamente, o Iceberg mostra que seu pacote contém mudanças que não foram enviadas por commit usando a cor verde e a estrela na frente do nome do pacote, como mostrado na Figura 5-15.

Faça o commit das mudanças

Faça o commit das alterações em seu repositório local usando o botão Commit, como mostrado na Figura 5-16. O Iceberg permite que você escolha as entidades alteradas que você deseja enviar por commit. Aqui isto não é necessário, mas é uma característica importante. Iceberg mostrará o resultado da ação de commit removendo a estrela e mudando a cor. Ele agora mostra que o código na imagem está em sincronia com seu repositório local, como mostrado na Figura 5-17. Você pode fazer commit várias vezes, se necessário.

Publique suas mudanças em seu repositório remoto

Agora você está quase terminando. Publique suas mudanças de seu diretório local para seu repositório remoto usando o botão Push. Você poderá ser solicitado a fornecer suas credenciais se você usou HTTPS.

Quando você empurrar (push) suas alterações, Iceberg lhe mostrará todos os commits que aguardam publicação e os empurrará (push) para seu repositório remoto, como mostrado na Figura 5-18. A figura mostra os commits que estamos prestes a fazer para adicionar uma baseline, o que permitirá a você carregar facilmente seu projeto em outras imagens.

Agora você está basicamente terminado.

5.10 Conclusão

Agora você conhece os aspectos essenciais do gerenciamento de seu código com o Github. Iceberg foi projetado para guiá-lo, portanto, por favor, escute-o, a menos que você realmente saiba o que está fazendo. Agora você está pronto para usar os serviços oferecidos em torno do Github para melhorar seu controle e qualidade de código!