From 57d020ea055ff4c3d6309860e0eded11f9c3f064 Mon Sep 17 00:00:00 2001
From: Walmes Zeviani <walmes@ufpr.br>
Date: Sun, 6 Dec 2015 12:59:40 -0200
Subject: [PATCH] =?UTF-8?q?Finaliza=20corre=C3=A7=C3=A3o=20da=20Integra?=
 =?UTF-8?q?=C3=A7=C3=A3o=20Cont=C3=ADnua.?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 cap05.Rmd | 239 ++++++++++++++++++++++++------------------------------
 1 file changed, 107 insertions(+), 132 deletions(-)

diff --git a/cap05.Rmd b/cap05.Rmd
index fdab02e..626b799 100644
--- a/cap05.Rmd
+++ b/cap05.Rmd
@@ -126,8 +126,8 @@ têm-se:
     modo que esta possa submeter as contribuições para a origem (por MR)
     ou até mesmo usar como ponto de partida para um novo projeto.
 
-De acordo com
-Klint~Finley\footnote{\url{http://techcrunch.com/2012/07/14/what-exactly-is-github-anyway/}},
+De acordo com Klint
+Finley\footnote{\url{http://techcrunch.com/2012/07/14/what-exactly-is-github-anyway/}},
 *fork* e MR são os recursos que tornam o GitHub tão poderoso. Quando o
 mantenedor recebe um MR ele pode ver o perfil do contribuidor onde estão
 listados todos os projetos no qual este contribuiu. Ao aceitar o MR, é
@@ -817,9 +817,11 @@ mecanísmos chaves para a colaboração via serviços web para Git.
 
 ## Issues ##
 
-De acordo com o dicionário [Macmillan], *issue* significa um problema
-que precisa ser considerado. Também significa um assunto que as pessoas
-debatem ou o volume de uma revista. Cabe aqui a primeira definição.
+De acordo com o dicionário
+Macmillan\footnote{\url{http://www.macmillandictionary.com}}, *issue*
+significa um problema que precisa ser considerado. Também significa um
+assunto que as pessoas debatem ou o volume de uma revista. Cabe aqui a
+primeira definição.
 
 Nos serviços web para Git, *issue* é um recurso da interface que permite
 que as pessoas abram um assunto/tópico referente ao projeto. Em geral,
@@ -1016,7 +1018,7 @@ git tag -a v1.0 -m "Versão 1.0 do software"
 
 Quando você está trabalhando em um projeto Git, cada *commit*, cada
 *branch*, contém algum desenvolvimento. Solucionar conflitos de *merge*
-não é um atarefa complicada, principalmente se forem consideradas as
+não é uma tarefa complicada, principalmente se forem consideradas as
 ferramentas certas para isso, como será visto no próximo capítulo. No
 entanto, para cada *commit* tem-se a preocupação: será que o projeto
 está funcional?
@@ -1035,7 +1037,7 @@ o projeto corre sem erros (código executa, software instala) em uma
 máquina cliente (com os requisitos mínimos exigidos), toda vez que um
 *commit* fosse feito, já que o *commit* indica que modificações foram
 feitas. Então, se correu sem erros, avisar à todos que podem prosseguir,
-mas se falhou, informar a equipe, encontrar e resolver a falha.
+mas se falhou, informar a equipe, encontrar e corrigir a falha.
 
 Não é raro algo ser bem sucedido no ambiente em que foi desenvolvido e
 apresentar falhas na ambiente de outra pessoa. O melhor jeito de
@@ -1048,51 +1050,46 @@ verificações no projeto a cada novo *push*.
 
 Fazer integração contínua no GitHub e GitLab, embora o conceito seja o
 mesmo, tem algumas diferenças. Paro o GitHub existem diversos serviços
-de IC, é algo terceirizado. Já o GitLab CE têm o serviço próprio de
-IC desde a versão 8.0. Apresentaremos cada um deles na sessão seguinte.
+de IC, é algo terceirizado. Já o GitLab CE têm o serviço próprio de IC
+a partir da versão 8.0. Apresentaremos cada um deles na sessão seguinte.
 
-Independe do serviço web, as principais vantagens da IC são:
+Independe do serviço web, as principais vantagens da
+IC\footnote{\url{https://about.gitlab.com/gitlab-ci/}} são:
 
-  1) Economia de tempo com supervisão de código e procura de falhas;
+  1) Economia de tempo com supervisão de código e procura de falhas. Com
+     a verificação mais frequente, a cada *commit*/*push*, menos tempo é
+     gasto na correção de bug, que devem ser também menores, assim
+     deixando mais tempo para desenvolver o que interessa.
   2) Verificação em um ambiente virgem sem efeito de variáveis de
-     ambiente locais;
+     ambiente locais.
   3) Verificação em vários ambientes (sistemas operacionais,
      arquiteturas, dependências e versões);
   4) Informação coletiva e imediata à equipe da causa de falha na hora
-     que ela ocorre;
-  5) Indicação de sucesso ou não na home do projeto;
+     que ela ocorre, o que aumenta a visilibidade, facilita a
+     comunicação e direcionamento de esforços.
+  5) Indicação de sucesso ou não na home do projeto e nos *branches*
+     disponível antes do merge;
   6) Entrega de versões estáveis, documentação e arquivos acessórios com
-     *continuous deployment*.
+     *continuous deployment*, o que facilita o empacotamento e
+     disponibizaçaõ do projeto.
   7) Custo computacional reduzido já que é feito em um servidor
      dedicado.
-  8) Verificação a cada *push* feito.
-  9) Status exibido para cada branch e requisição de merge.
-  10) Aumenta a visilibidade facilitanto a comunicação e reunião de
-      esforços.
-  12) Menos tempo na correção de bug, que devem ser menores, assim
-      deixando mais tempo para desenvolver o que interessa.
-  13) É barato, até mesmo quando custa algo, porque parar o projeto por
-      erro pode custar inclusive mais caro.
-  14) Reduz os problemas com usuários fora dos colaboradores pois testa
-      em máquinas virgens.
-  15) Facilita para os usuários saberem se a última versão é executável.
-  16) Pode automatizar a disponibilização do projeto aos usuários.
-
-A integração contínua não elinima erros, mas faz com que eles sejam mais
-fáceis de identificar e remover.
-
-Sem a automação, os espaços entre verificações podem ficar longos,
-encontrar um bug em tantos commits é mais difícil, encontrar no código é
-mais ainda. Pode atrasar a entrega do projeto e comprometer a receita e
-popularidade. Integrações periodicas são mais fáceis e leves.
-
-O build é automático, faz um self-testing a cada commit.
+  8) É barato, até mesmo quando custa algo, porque parar o projeto por
+     para corrigir um erro pode custar inclusive mais caro.
+
+O que deve ficar claro é que a integração contínua não elinima erros,
+mas faz com que eles sejam mais fáceis de identificar e corrigir.
+
+Sem a automação, os espaços entre verificações podem ficar longos.
+Encontrar um *bug* em tantos *commits* é mais difícil, encontrar no
+código é mais ainda. Pode atrasar a entrega do projeto e comprometer a
+receita e popularidade. Integrações periodicas são mais fáceis e leves.
 
 O fluxo de trabalho de um repositório com IC é basicamente assim:
 
-  1) Os desenvolvedores trabalham no projeto em seu workspace
+  1) Os desenvolvedores trabalham no projeto em seu *workspace*
      privado/local;
-  2) Periodicamente fazem *commits* e *push* para o repositório remoto;
+  2) Periodicamente fazem *commits* e *pushs* para o repositório remoto;
   3) O serviço de IC monitora o repositório toda vez que modificações
      ocorrem;
   4) O serviço de IC corre todos os testes de inspeção que foram
@@ -1101,23 +1098,21 @@ O fluxo de trabalho de um repositório com IC é basicamente assim:
   5) O serviço de IC disponibiliza produtos da verificação, como
      binários de instalação e documentação (no caso de sucesso) ou log
      de execussão (no caso de falha);
-  6) O serviço de IC assinalá no repositório Git o *status* da
+  6) O serviço de IC assinala no repositório Git o *status* da
      verificação: sucesso/fracasso;
   7) O serviço de IC informa a equipe dos resultados por mensagem de
-     email ou webhooks, como o Slack;
-  8) A equipe toma das providências cabiveis na primeira oportunidade,
+     email ou *web hooks*, como o Slack;
+  8) A equipe toma das providências cabíveis na primeira oportunidade,
      como corrigir a falha ou anunciar o sucesso;
   9) O serviço aguarda por mais modificações;
   
 ## GitHub ##
 
-http://www.codeaffine.com/2014/09/01/travis-continuous-integration-for-github-projects/
-
 Embora exista uma lista grande de serviços de integração contínua
 disponíveis para repositórios GitHub, um dos mais usados é o
-[Travis CI].  Travis CI (*continuous integration*) é um serviço free e
-open source destinado à integração contínua para projeto **públicos** no
-GitHub.
+Travis CI\footnote{\url{https://travis-ci.org/}}.  Travis CI
+(*continuous integration*) é um serviço *free* e *open source* destinado
+à integração contínua para projetos **públicos** no GitHub.
 
 Para vincular um projeto no GitHub com IC no Travis CI, você precisa
 logar no <https://travis-ci.org/> com a sua conta do GitHub. Assim que
@@ -1132,12 +1127,12 @@ Cada projeto, cada linguagem, têm uma forma particular de ser
 testada. Para pacotes R, o Travis CI tem uma documentação de orientação:
 <https://docs.travis-ci.com/user/languages/r/>. Além disso, uma boa
 prática em ver exemplos em uso, como o `.travis.yml` dos pacotes R
-`knitr` (<https://github.com/yihui/knitr>) e `devtools`
-(<https://github.com/hadley/devtools>) que estão na lista dos mais
-utilizados.
+`knitr`\footnote{\url{https://github.com/yihui/knitr}} e
+`devtools`\footnote{\url{https://github.com/hadley/devtools}} que estão
+na lista dos mais utilizados.
 
 Para todas as liguagens e objetivos têm-se exemplos de arquivos
-`.trevis.yml`. Para o Emacs e biblitecas visite
+`.trevis.yml`. Para o Emacs e biblitecas lisp visite
 <https://github.com/rolandwalker/emacs-travis>,
 <https://github.com/Malabarba/elisp-bug-hunter> e
 <https://github.com/abo-abo/tiny>. Para projetos em `C++` e `phyton`,
@@ -1149,63 +1144,48 @@ Além do linguagens de programação, é possível testar inclusive a
 compilação de um documento Latex:
 <http://harshjv.github.io/blog/setup-latex-pdf-build-using-travis-ci/>.
 
-*branch build flow*
-*pull request build flow*
-
-`after_failure` (information, error report)
-`after_success` (deployment, uploads de documentação e versões estáveis)
-
-exibir build status no README
-fazer *webhook* com Slack
-
 ## GitLab ##
 
-https://about.gitlab.com/gitlab-ci/
-https://about.gitlab.com/2015/02/03/7-reasons-why-you-should-be-using-ci/
-
-A Integração Contínua passou fazer parte do GitLab CE na [versão 8.0],
+A Integração Contínua passou fazer parte do GitLab CE na versão
+8.0\footnote{\url{https://about.gitlab.com/2015/09/22/gitlab-8-0-released/}},
 lançada em setembro de 2015. Diferente do GitHub, essa versão do GitLab
 tem o IC de forma nativa. Você pode configurar servidores externos para
 executarem as verificações ou pode fazê-las no mesmo servidor que roda o
 GitLab.
 
-[Alan Monger] descreve como configurar um servidor Ubuntu no
-[Digital Ocean] parar verificar repositórios hospedados no
-<https://gitlab.com/>.
-
-TODO Definir *runner*, *build*, *YAML*.
+Alan
+Monger\footnote{\url{http://alanmonger.co.uk/php/continuous/integration/gitlab/ci/docker/2015/08/13/continuous-integration-with-gitlab-ci.html}}
+descreve como configurar um servidor Ubuntu no Digital
+Ocean\footnote{\url{https://www.digitalocean.com/}} parar verificar
+repositórios hospedados no <https://gitlab.com/>.
 
 Segundo ele, o primeiro passo é acessar <https://gitlab.com/ci/> para
-adicionar o projeto à integração contínua. Isso vai gerar um *token* de
-registro que será passado para o *runner* que deve estar em uma
-máquina. Na sua matéria, Alan Monger descreve como instalar um *Virtual
-Private Server* com Ubuntu 14.04 no Digital Ocean. Em seguida instala o
-*runner* (`gitlab-ci-multi-runner`), configura e passa o *token*, cria
-uma imagem - algo que executa coisas no sistema mas que propositalmente
-perdidas no final, o sistema é sempre restaturado ao estado virgem. O
-*runner* é então habilitado e por fim o arquivo `.gitlab-ci.yml` é
-criado na home do *repositório*.
-
-As especificação são feitas em um arquivo `.gitlab-ci.yml` na home do
-projeto.
-
-O [GitLab do LEG] tem o CI embutido pois é a versão mais recente do
-serviço. Essa servidora é na realidade um *desktop* com Ubuntu Server. É
-patrimônio da UFPR de responsabilidade do LEG mas tem uso compartilhado
-com o PET Estatística e colaboradores do Laboratório. Desde a
-disponibilização do GitLab, em julho de 2015, mantemos artigos,
-materiais de ensino (aulas, provas, scripts), tutoriais e materias de
-blog em devolvimento colaborativo, além de pacotes R.
+adicionar o projeto à integração contínua. Na sua matéria, Alan descreve
+como instalar um *Virtual Private Server* com Ubuntu 14.04 no Digital
+Ocean. Em seguida instala o *runner* (`gitlab-ci-multi-runner`) o
+configura e habilita. Por fim, o arquivo `.gitlab-ci.yml`, que
+especifica o que deve ser executado, é criado na home do *repositório*.
+
+O GitLab do LEG\footnote{\url{http://git.leg.ufpr.br/}} tem o CI
+embutido pois é a versão mais recente do serviço. Essa servidora é na
+realidade um *desktop* com Ubuntu Server 14.04. É patrimônio da UFPR de
+responsabilidade do LEG mas tem uso compartilhado com o PET Estatística
+e colaboradores do Laboratório. Desde a disponibilização do GitLab, em
+julho de 2015, mantemos artigos, materiais de ensino (aulas, provas,
+scripts), tutoriais e materias de blog em devolvimento colaborativo,
+além de pacotes R.
 
 Nessa servidora, criamos um usuário chamado `gitlab-runner` com o qual
 fazemos as integrações contínuas. Toda vez que um projeto com o arquivo
 `.gitlab-ci.yml` recebe um *push*, as instruções nesse arquivo executam
 a IC com o usuário `gitlab-runner`. Tecnicamente podemos correr todo
-tipo de comando ou programa disponível no servidor em questão, um Ubuntu
-Server 14.04. Até então, os repositórios com IC são só dois: [legTools]
-e [mcglm], dois pacotes R.
+tipo de comando ou programa disponível no servidor em questão. Até
+então, os repositórios com IC são só dois:
+`legTools`\footnote{\url{http://git.leg.ufpr.br/leg/legTools}} e
+`mcglm`\footnote{\url{http://git.leg.ufpr.br/wbonat/mcglm}}, dois
+pacotes R.
 
-### O arquivo `.gitlab-ci.yml` ###
+### O arquivo de configuração `.gitlab-ci.yml` ###
 
 A documentação oficial sobre como usar o arquivo `.gitlab-ci.yml`
 encontra-se em <http://doc.gitlab.com/ce/ci/yaml/README.html>.
@@ -1231,19 +1211,20 @@ um *script* shell e o segundo comandos *shell* em uma lista. Porém, tais
 arquivos podem ser bem mais complexos, com campos além do `script:`. Os
 campos a seguir são todos opcionais:
 
-  * `image`: para especificar uma imagem [*docker*]. O tutorial de
-    [Alan Monger] considera esse campo.
+  * `image`: para especificar uma imagem
+    *docker*\footnote{\url{https://www.docker.com/}}. O tutorial de Alan
+    Monger considera esse campo.
   * `services`: também refere ao *docker*. Tais campos são de uso menos
     frequênte, porém existe uma séria de vantagens neles. A documentação
     oficial sobre isso encontra-se em
     <http://doc.gitlab.com/ce/ci/docker/README.html>.
   * `before_script`: define comandos/scripts a serem executados antes
-    dos principais. São instruções de preparação das quais não se espera
-    falhas pois não deve depender do projeto.
-  * `stages`: define a ordem de excecução dos *jobs* que estabalecer uma
-    cadeia de execução condicional. Jobs de mesma ordem ou do mesmo
-    estágio são executados paralelamente mas àqueles à frente só são
-    executados se houver sucesso dos predecessores.
+    dos comandos verificadores. São normalmente instruções de preparação
+    das quais não se espera falhas pois não devem depender do projeto.
+  * `stages`: define a ordem de excecução dos *jobs* para uma cadeia de
+    execução condicional. *Jobs* de mesma ordem ou do mesmo estágio são
+    executados paralelamente mas àqueles à frente só são executados se
+    houver sucesso dos predecessores.
     ```
     stages:
       - construcao
@@ -1264,7 +1245,9 @@ campos a seguir são todos opcionais:
       stage: entrega
     ```  
   * `variables`: serve para criar variaveis de ambiente que podem ser
-    usados por todos os comandos e scripts.
+    usados por todos os comandos e scripts. Tais variáveis podem
+    aramazenas senhas de acesso, necessárias por exemplo para instalação
+    de componentes e acesso à bancos de dados.
   * `cache`: indica os diretórios e arquivos que serão mantidos entre os
     *jobs* (builds), possivelmente porque são aproveitados futuramente.
 
@@ -1288,13 +1271,14 @@ campos disponíveis para configurá-lo:
       script: "teste_documentacao.sh"
       stage: teste
       only:
-        - /^issue.*$/ ## Os que começam com issue 
+        - /^issue.*$/ ## Filtra os que começam com issue.
     ```
   * `tags`: são usadas para indicar o *runner* da lista de
     disponíveis. Na configuração dos *runners* pode-se atribuir *tags*
     que servem justamente para esse tipo de pareamento.
-  * `allow_failure`: indica jobs que mesmo que falhem, não serão
-    considerados para dar estampa de sucesso ou falha.
+  * `allow_failure`: indica *jobs* que, mesmo que falhem, não serão
+    considerados para dar estampa de sucesso ou falha, ou seja, é um
+    teste mas não crucial.
   * `when`: é um comando que dispara excussões condicionais ao sucesso
     do *job* anterior
     * `on_failure`: são instruções executadas quando algum o *job* do
@@ -1302,10 +1286,10 @@ campos disponíveis para configurá-lo:
     * `on_success`: são instruções executadas quando todos os *jobs* do
       estágio anterior foram bem sucedidos.
     * `always`: excutados sempre.
-  * `cache`: especifica arquivos e diretório mantidos entre um *build* e
+  * `cache`: especifica arquivos e diretórios mantidos entre um *job* e
     outro.
 
-No caso do pacote LegTools, o arquivo `.gitlab-ci.yml` do repositório
+No caso do pacote legTools, o arquivo `.gitlab-ci.yml` do repositório
 tem o seguinte conteúdo:
 
 ```{r, eval=FALSE, engine="sh"}
@@ -1315,18 +1299,18 @@ job_R:
     - Rscript -e 'getwd(); .libPaths(); sessionInfo()'
     - Rscript -e 'library(devtools); check()'
     - Rscript -e 'library(devtools);\
-                  .libPaths(new = path.expand("~/R-tests/legTools"));\
-                  install(local = FALSE)'
+        .libPaths(path.expand("~/R-tests/legTools"));\
+        install(local = FALSE)'
 ```
 
 Estas são instruções em *shell* que chamam o R com expressões passadas
-para `Rscript -e` que executam a instalação do pacote. Na ocorrência da
+para `Rscript -e` para fazer a instalação do pacote. Na ocorrência da
 primeira falha, o processo é logicamente interrompido e os
 colaboradoradores podem ver a causa em
 <http://git.leg.ufpr.br/leg/legTools/builds>. No caso do *build* correr
 sem falhas, tem-se uma estampa de *success*. Essa estampa também vai
-aparecer no README.md na página de rosto do projeto, basta para isso
-colocar
+aparecer no `README.md` na página de rosto do projeto, basta para isso
+colocar o seguinte conteúdo no arquivo.
 
 ```
 ![](http://git.leg.ufpr.br/ci/projects/1/status.png?ref=master)
@@ -1336,7 +1320,7 @@ Caso queira a estampa para outros ramos, é só acrescentá-los.
 
 ### Runners ###
 
-Em poucas palavras, um *runner* é uma máquina que executa o build por
+Em poucas palavras, um *runner* é uma máquina que executa o *build* por
 meio do GitLab CI. Um *runner* pode ser específico de um projeto ou pode
 ser um *runner* compartilhado, disponível à todos os projetos. Estes
 últimos são úteis à projetos que tem necessidades similares, como todos
@@ -1344,25 +1328,26 @@ ser um *runner* compartilhado, disponível à todos os projetos. Estes
 administação e atualização. Os específicos, por outro lado, atendem
 projetos com demandas particulares.
 
-Apenas usuários com permissões de *admin* podem criar runners
+Apenas usuários com permissões de *admin* podem criar *runners*
 compartilhados.
 
-Ir em Settings > Services e marcar *active*. Isso vai criar 6 novas
-entradas no menu da esquerda
+Em \menu{Settings > Services} marque o campo *active*. Isso vai criar 6
+novas entradas no menu da esquerda:
 
-  * *Runners*: contém instruções de como usar um *runner* específicos e
+  * *Runners*: contém instruções de como usar os *runners* específicos e
     compartilhados. 
   * *Variables*: define variáveis que são omitidas no *log* do *build*,
      útil para passar senhas.
-  * *Triggers*: servem para ??
+  * *Triggers*: servem para TODO
   * *CI Web Hooks*: esse *web hook* pode ser usado para criar eventos
-    quando o build é concluido.
-  * *CI Settings*: configurações gerais
+    quando o *build* é concluido.
+  * *CI Settings*: configurações gerais.
   * *CI Services*: permite integrar o CI com outros serviços, como email
     e Slack.
 
 Para habilitar um *runner*, é necessário instalar o
-`gitlab-ci-multi-runner`. O [repositório oficial do *GitLab Runner*]
+`gitlab-ci-multi-runner`. O repositório oficial do *GitLab
+Runner*\footnote{\url{https://gitlab.com/gitlab-org/gitlab-ci-multi-runner}}
 contém as instruções de instalação e configuração e a documentação
 oficial sobre
 *runners*\footnote{\url{http://doc.gitlab.com/ce/ci/runners/README.html}}
@@ -1370,14 +1355,4 @@ indica como tirar melhor proveito do recurso.
 
 <!---------------------------------------------------------------------- -->
 
-[GitLab]: https://about.gitlab.com/
-[Macmillan]: http://www.macmillandictionary.com
-[TRavis CI]: https://travis-ci.org/
-[versão 8.0]: https://about.gitlab.com/2015/09/22/gitlab-8-0-released/
-[Digital Ocean]: https://www.digitalocean.com/
-[Alan Monger]: http://alanmonger.co.uk/php/continuous/integration/gitlab/ci/docker/2015/08/13/continuous-integration-with-gitlab-ci.html
-[GitLab do LEG]: http://git.leg.ufpr.br/
-[legTools]: http://git.leg.ufpr.br/leg/legTools
-[mcglm]: http://git.leg.ufpr.br/wbonat/mcglm
-[*docker*]: https://www.docker.com/
-[repositório oficial do *GitLab Runner*]: https://gitlab.com/gitlab-org/gitlab-ci-multi-runner
+[*docker*]:
-- 
GitLab