diff --git a/cap05.Rmd b/cap05.Rmd index 930ea49f0400e444ad7234367bc71d14b4480200..fa3475dab078fdffd003bae1b67ee449f76bc89f 100644 --- a/cap05.Rmd +++ b/cap05.Rmd @@ -174,15 +174,18 @@ Mascot é raccoon: guaxinim ## Criar um perfil -Ilustrar o simples processo de criar um perfil. Explorar um pouco das -interfaces. Terminar com o campo das chaves públicas para então fazer -uso na seção seguinte. - -Criar uma conta no Github é muito simples. Basta entrar em -<https://github.com/join>, preencher os dados pessoais, escolher um -plano (free/público, pago/privado) e fazer um tour pela interface. Como -não existe segredo em preencher os dados pessoais, vamos fazer uma breve -descrição da interface do GitHub. +Criar uma conta no Github é tão simples como uma conta de email ou de +rede social. Acesse o endereço <https://github.com/join> para preencher +seus dados pessoais e escolher um plano. Nenhum dos planos tem limitação +quanto ao número de repositórios ou colaboradores. O que muda é a +quantidade de reposiórios privados. No plano *free*, só são criados +repositórios públicos enquanto que nos planos pagos, o menor deles +permite 5 repositórios privados por um custo de U$ 5 por mês. Acesse +<https://github.com/pricing> para mais detalhes. + +Ao preencher o formulário de criação de conta, você receberá um email +com uma ulr de ativação. Se optar por planos pagos, terá informar número +do cartão de crédito para que seja feito o pagamento mensalmente. ### Habilitar comunição ### @@ -191,29 +194,205 @@ http://www.vogella.com/tutorials/GitHosting/article.html Geração e configuração das chaves públicas. Incluir screenshots. -### Generciar repositórios ### - -No canto superior direito da página tem um ícone $+$ que permite criar -um novo repositório ou uma nova organização. Escolha um nome para -representar o seu repositório e adicione uma breve descrição à ele. Na -etapa seginte, defina o nível de visibilidade: publico ou -privado. Lembre-se que repositórios privados só podem ser criados para -planos não *free*. - -Ao criar o repositório você pode inicilizado criando um arquivo -`README.md`. Como já mencionamos, esse arquivo é a capa do seu -repositório e serve para documentar o objetivo. Você pode editar esse -arquivo, ou qualquer outro, de dentro do GitHub e, claro, *commitar* as -alterações que fizer. Depois de criado, é possível clonar o repositório -pelo endereço que é composto pelo seu nome de usuário e nome do -repositório. O repositório `ola-mundo` da conta do `fulano` pode ser -clonado com - -```sh +Uma vez criada uma conta, é necessário habilitar a comunicação entre sua +máquina e o (servidor do) GitHub. A comunicação se baseia no protocolo +ssh, o qual já usamos no capítulo anterior para hospedar o repositório +em um servidor remoto. + +Para relembrar, a maioria dos servidores suporta a autenticação por SSH +(*secure shell*). Para que seja automática, ou seja, sem precisar +fornecer login e senha a cada acesso, usamos o recurso de pares de +chaves. Este serve para fazer a máquina remota (servidor) reconhecer a +máquina local (sua máquina) por da autenticação do par de chaves. É como +se o servidor fosse um cadeado e a sua máquina local tem a chave que o +abre. + +Para gerar as chaves públicas, você precisa executar: +```{sh} +## Gera chaves públicas. +ssh-keygen -t rsa -C "seu_email@seu.provedor" +``` + +O endereço padrão para os arquivos criados e o diretório `~/.ssh/`. Os +arquivos serão reescritos caso já existam arquivos de chaves públicas +lá. Toda novo par de chaves é único. Então, se você reescreveu os +arquivos anteriores, terá atualizar as chaves públicas em todos os +serviços web que fazem uso desse recurso e com todos os servidores com o +qual você tem autenticação por chaves. + +Acesse <https://github.com/settings/ssh> para então adicionar chaves +públicas (Figura XXX) ao seu perfil. Você precisa estar logado. Clique +em `Add SSH key`, cole o conteúdo copiado do arquivo `*.pub` no campo +`key`. No campo `Title` identifique a máquina correspndente àquela +chave. Use, por exemplo, `laptop` ou `trabalho` para facilitar o +reconhecimento. É comum trabalhar-se com mais de um máquina, como uma em +casa e outra no trabalho. + + + +FIGURA XXX: *Printscreen* da página de configurações pessoais do +GitHub. No menu `SSH Keys` pode-se ver e adicionar chaves públicas. + +Para testar a comunição entre o GitHub e a sua máquina, execute: +```{sh} +## Testa comunição. Retorna um "Welcome!" em caso positivo. +ssh -T git@github.com + +## Se falhar, habilite o modo verbose para rastrear o erro. +ssh -vT git@github.com +``` + +### Gerenciar repositórios ### + +A comunicação com o GitHub acabou de ser estabelecida. Agora podemos +criar repositórios e começar a mostrar nosso trabalho para o mundo e +colaborar de forma eficiente. + +No canto superior direito das páginas do GitHub existe um ícone $+$ que +permite criar um novo repositório ou uma nova organização. Clique em +*New repository* ou acesse o endereço <https://github.com/new>. Na +janela que abrir, dê um nome para o seu projeto e adicione uma breve +descrição à ele (Figura XXX). Na etapa seguinte, defina o nível de +visibilidade: público ou privado. Lembre-se que os planos *free* só +permitem repositórios públicos. + + + +FIGURA XXX: Janela para a criação de um novo repositório no GitHub. + +Para criar o projeto dentro de uma Organização, selecione a Organização +na *drop list* que fica no no campo Owner, a esquerda do campo para o +nome do repositório. + +Você pode inicilizar o repositório com um arquivo `README.md`, o que é +altamente recomendado. Como já mencionamos, esse arquivo é a capa do seu +repositório e serve para documentar o seu objetivo, formas de +colaboração, colaboradores, formas de instalação do software, caso seja +um. + +Você pode editar o arquivo `README.md` (ou qualquer outro) no GitHub. As +moficações que fizer devem ser *commitadas* para serem salvas. O arquivo +de `README.md`, que é linguagem de marcação MarkDown, é automaticamente +renderizado pelo GitHub fazendo com que urls sejam clicáveis e códigos +estejam em ambientes de fonto monoespaço, além de ter títulos com +tamanho de fonte apropriado e as demais renderizações. + +Depois de criar o repositório, você já pode cloná-lo para trabalhar +localmente. O endereço do repositório é composto pelo seu nome de +usuário e nome do repositório. O repositório `ola-mundo` da conta do +`fulano` pode ser clonado com: + +```{sh} +## Clone pelo protocolo ssh. Requer chaves públicas. git clone git@github.com:fulano/ola-mundo.git ``` -Criar, renomear, deletar. Públicos e privados. Adicionar README. +Pode-se clonar repositórios pelo protocolo `http` (*Hypertext Transfer +Protocol*) também. Em geral, para clonar repositórios de outros usuários +e fazer testes, usa-se `http`. Embora você possa usar `http` nos seus +repositórios, prefira o *SSH*. Com `http`, o endereço para a ser: + +```{sh} +git clone https://github.com/fulano/ola-mundo.git +``` + +Por padrão, ao clonar o repositório, um diretório de mesmo nome é criado +com o projeto em seu interior. Em caso de preferir outro nome para esse +diretório, por exemplo, `OlaMundo`, use: + +```{sh} +git clone https://github.com/fulano/ola-mundo.git OlaMundo +``` + +Existe outra situação que é quando você já tem repositório Git no qual +já está trabalhando e quer tê-lo no GitHub. Nesse caso, você faz os +mesmos passos, exceto que não irá cloná-lo, apenas adicionar a url do +repositório GitHub ao repositório local e fazer um *push*. Vamos supor +que o repositório seja um artigo científico de nome `Artigo`. Ao criar o +repositório com esse nome no GitHub, o endereço fica +`git@github.com:fulano/Artigo.git`. Então é só adicionar esse endereço +como `origin` do projeto Git: + +```{sh} +## Adiciona endereço de "origin" ao repositório. +git remote add origin git@github.com:fulano/Artigo.git + +## Sobe o conteúdo do repositório. +git push -u origin master +``` + +O seu projeto é configurado em +<https://github.com/walmes/emacs/settings/>. Para renomear, deletar ou +trasferir o projeto para outro usuário ou organização, vá em +*Options*. Em *Collaborators* você administra os colaboradores do +projeto. Para genrenciar os ramos de trabalho, como proteger ou remover +ramos, vá em *Branches*. O uso de de serviços web é configurado no +*Webhooks & services*. O *Deploy keys* permite adicionar chaves +públicas. + + + +Vamos considerar um repositório de bastante atividade para conhecermos +um pouco mais dos recursos do GitHub. O repositório +<https://github.com/yihui/knitr> é o sítio de desenvolvimento do pacote +`knitr` do R, o principal pacote para a geração de relatórios +dinâmicos. Nesse repositório tem-se acesso aos fontes. + +Na figura XXX, logo abaixo do título, tem-se quatro quantificadores: + + * *commits*: ao clinar neste tem-se o histórico de *commits* com + autor, mensagem e sha1. É possível comparar estados dos arquivos + (*diff*) ao clinar no sha1. + * *branches*: este lista os *branches* do projeto, permite comparar + ramos. + * *releases*: documenta as modificações de uma versão para outra e + lista os *commits* que tem *tags*. Essa é uma fonte importate. + * *contributors*: dá um resumo das atividades dos colaboradores do + projeto. Na aba *members* tem-se uma lista de todos os usuários que + fizeram o *fork* do seu projeto. Falaremos de *fork* adiante. + +No menu da direita existem links para acessos a mais coisas: + + * code: estão visíveis os diretórios e arquivos do projeto. Pode-se + navegar entre eles. Ao visualizar um arquivo, ele é renderizado de + acordo com a linguagem de código que contém para facilitar a + compreensão. Ao abrir um arquivo, no topo aparecer um botões de + exibição/ação: *Raw* é para ver o arquivo cru. A url quando estiver + nessa exibição pode ser usada para carregar arquivos de dados ou + scripts direto da web. *Blame* mostra o arquivo com autor para cada + porção do código. O *History* mostra o histórico de *commits*. Os + dos ícones seguintes permitem editar o arquivo ou deletar. + * issues: permite criação e acesso aos *issues* do projeto. Dentro + dessa página tem-se acesso às *Milestones*. + * pull requests: é o termo que o GitHub usa para requisição de + mescla. Nesta página pode submeter uma requisição e navegar nas + existentes. + * wiki: na Wiki de um repositório normalmente é feita uma documentação + mais detalhada do projeto. Páginas Wiki de um repositório são também + repositórios Git, portanto, versionáveis. + * pulse: dá um resumo sobre s quantidade issues presentes, fechados e + abertos bem como para requisções de mescla. Mostra também um resumo + da atividade recente do repositório. + * graphics: tem-se gráficos sobre a atividade no reporitório, como + frequência de *commits*, total e por autor, instantes do dia de + maior colaboração, etc. + +Existem ainda mais coisas sobre o GitHub que não podemos deixar de +comentar que são os recursos disníveis para colaboração. Nas sessões à +frente, trataremos do recurso de *fork*, *issue* e requisições de +mescla. Antes, no entanto, vamos conhecer um pouco GitLab, um serviço +web para projetos Git que pode ser instalado no seu servidor. + +O GitLab é o serviço que nós do PET usamos para colaboração em nossos +projetos. Além disso, é o que os alunos usam para fazerem seus trabalhos +e desenvolverem o TCC. O uso do Git como ferramenta de trabalho passou +ser estimulado nesse semestre (2015/2). + +Basicamente, o GitLab tem os mesmos recursos ... + +Não usamos a conta no <https://gitlab.com/>, usamos a instalação em +servidor próprio disponibilizado pelo c3sl - Centro de Computação +Científica e Software Livre - da UFPR. ## Fluxo de trabalho ## diff --git a/images/github_repo_home.png b/images/github_repo_home.png index 5513e1bbba669be3479065590cbaa26ef8dddef2..b9c3266897b36149a7df64fca4ab6a8c2e200f8c 100644 Binary files a/images/github_repo_home.png and b/images/github_repo_home.png differ diff --git a/plano.md b/plano.md index 47bd1c7f07097c3ab92498357a2e1b1780d320ae..896774d47595167b5c07e8ebb588477b7e461ee9 100644 --- a/plano.md +++ b/plano.md @@ -98,6 +98,21 @@ + Alcides: concluir o dicionário de termos. + Daniel: concluir o conteúdo do *cheat sheet*. 3. 2015-11-10: + + Walmes: escrever para o GitLab o mesmo contúdo para presente para o + GitHub. Isso vai de uma breve descrição das funcionalidades, como + criar conta e gerenciar um repositório. + + Gabriel: **finalizar o trabalho da semana anterior**. Escrever + sobre o uso de *branches*, *checkout* e *merge*. + + Ângela: fazer revisão, acréscimos e acabamento. + + Jhenifer: escrever sobre configurações pessoais: aliases para o + Git, para o sistema operacional e como ignorar arquivos. + + Eduardo: **finalizar o trabalho da semana anterior**. Documentar o + uso da gitk, gitg e gitx para assim terminar a parte de interfaces + de execução e exibição com Git. + + Alcides: Concluir os exemplos de rotinas. Revisar o capítulo da + Jhenifer. + + Daniel: Definir o conteúdo previsto no *cheat sheet* e concluir o + capítulo sobre SCV. Revisar o capítulo da Ângela. 4. 2015-11-17: 5. 2015-11-24: 6. 2015-12-01: