Termina correções no macanísmos de colaboração.

cap05.Rmd

@@ -808,10 +808,10 @@ git branch -vv
 # Macanísmos de colaboração #
 
 Os serviços web para Git, mesmo que você trabalhe sozinho, já são
-interessantes para que você tenha uma cópia (backup) do seu projeto e
-disponibilize seu trabalho. No entanto, um dos principais objetivos dos
+interessantes para ter uma cópia (*backup*) do seu projeto e
+disponibilizar seu trabalho. No entanto, um dos principais objetivos dos
 serviços web é permitir a colaboração entre pessoas. Já mencionamos o
-básico sobre isso quando falamos dos recursos de *issue*, *fork* e
+básico sobre recursos de colaboração quando falamos de *issue*, *fork* e
 *merge request*. Nas sessões a seguir, vamos nos aprofundar nesses três
 mecanísmos chaves para a colaboração via serviços web para Git.
 
@@ -828,15 +828,14 @@ falha a ser corrigida - ou sugerem que o projeto incorpore determinada
 característica desejável. O dono do projeto avalia a proposta e pode
 discutí-la logo em seguida, mantendo as mensagens reunidas e disponíveis
 para outros usuários que acompanham o projeto. Quando a proposta do
-*issue* for implementada, o *issue* pode ser fechado embora continua
-disponível e possa ser referenciado no, tanto para usuários que
-reportarem o problema já solucionado (usuários que não estão usando a
-versão mais recente) quanto para incluir no *change log* do projeto
-(essa versão corrige o bug descrito no *issue#43*, por exemplo).
-
-Quando um projeto é coletivo, como são a maioria dos projetos no PET
-Estatística (<https://gitlab.c3sl.ufpr.br/groups/pet-estatistica>), o
-recurso de *issue* pode ser usado de outra forma: como gerenciador de
+*issue* for implementada, o *issue* é fechado. Mesmo assim, o *issue*
+continua disponível e pode ser referenciado no futuro, tanto para novos
+usuários quanto para incluir no *change log* do projeto (essa versão
+corrige o bug descrito no *issue#43*, por exemplo).
+
+Quando um projeto é coletivo, como são alguns dos projetos no PET
+Estatística\footnote{\url{https://gitlab.c3sl.ufpr.br/groups/pet-estatistica}},
+o recurso de *issue* pode ser usado de outra forma: como gerenciador de
 tarefas. Combinado com as *milestones*, cada membro cria um *issue*
 correspondente ao que vai fazer no projeto no período de uma semana. Com
 isso, todos os demais membros são notificados de que alguém já vai
@@ -848,7 +847,7 @@ As *milestones* são uma espécie de coleção de *issues* que tenham algo
 em comum. Considere por exemplo o projeto de um livro. As *milestones*
 podem ser os capítulos a serem escritos e os *issues* podem ser as
 seções. Se for um projeto de software, as *milestones* podem separar os
-*issues* referentes ao aperfeiçoamento da documentação do software e ao
+*issues* referentes ao aperfeiçoamento da documentação e ao
 desenvolvimento do mesmo (escrita de código fonte).
 
 Criar um issue é muito simples. Tanto no GitHub quanto no GitLab, existe
@@ -857,54 +856,56 @@ criar um novo *issue*, comentar em um já existente e até reabrir um
 *issue* que já foi fechado (comum quando acredita-se ter resolvido um
 *bug* mas que ainda não foi). Os *issues* são numerados sequencialmente
 e isso faz com que cada *issue* seja único dentro do projeto. Os
-serviços web até tem formas de fazer *hiperlinks* facilmente para os
-*issues*. No GitLab, usa-se um hash seguido do número identificador
-(e.g. `#45`) para indicar um *issue*.
+serviços web até tem formas de fazer *hyperlinks* para os *issues*
+dentro das mensagens e *commits*. No GitLab, usa-se um hash seguido do
+número identificador (e.g. `#45`) para fazer um *hyperlink* para um
+*issue*.
 
 ## Fork ##
 
 A palavra *fork*, como substantivo, representa forquilha,
-bifurcação. Como verbo, representa bifurcar. Esse recurso está presente
-nas interfaces web para permitir que usuários façam cópias livres de
-projetos de outras pessoas. Como essa cópia é do projeto em determinado
-instante, há grande chance de divergência entre cópia e original a
-partir desse instante, por isso é apropriado a palavra bifurcamento.
+bifurcação. Esse recurso está presente nas interfaces web para permitir
+que usuários façam cópias livres de projetos de outras pessoas. Como
+essa cópia é do projeto em determinado instante, há grande chance de
+divergência entre cópia e original a partir desse instante, por isso é
+apropriado a palavra bifurcação.
 
 As finalidades de um *fork* são duas: 1) ter uma cópia na qual se possa
-acrescentar modificações e enviar para o dono e assim contribuir no
-projeto original ou 2) usar a cópia como ponto de partida para outro
+acrescentar modificações e enviar para o dono as contribuições no
+projeto original ou 2) usar a cópia como ponto de partida para um outro
 projeto, sem intenção de voltar ao projeto original.
 
-Com o *fork*, você pode colaborar como um terceiro em um projeto, ou
-seja, sem ser colaborador adicionado pelo dono ao projeto. Nessa cópia
-você tem permissões de *owner* pois na realidade, embora seja uma cópia,
-ela é toda sua. Você faz sua cópia livre, trabalha como quiser e no
-prazo que quiser, e submete ao projeto original o desenvido na sua
-cópia. O dono do projeto não tem como saber por que você fez o *fork*
-(mas você pode criar um *issue*) nem quando irá concluir o que
-almeja. No entanto, quando concluir, para que seu trabalho seja
-incorporado ao original, você terá que fazer um *merge request* (isso só
-é possível entre usuários de um mesmo serviço web).
-
-No GitHub, o acesso ao *fork* é por um botão que fica mais a direita na
+No GitHub, o acesso ao *fork* é por um botão que fica mais à direita na
 linha de título do projeto. No GitLab, o botão de *fork* fica na página
 inicial do projeto logo acima do endereço para clonar. Em qualquer um
 desses serviços, uma vez logado, ao pedir um *fork*, uma cópia do
 projeto é criada no seu perfil.
 
+Com o *fork* você pode colaborar como um terceiro em um projeto, ou
+seja, sem ser colaborador adicionado pelo dono. Nessa cópia você tem
+permissões de *owner* pois na realidade, embora seja uma cópia, ela é
+toda sua. Você faz sua cópia livre, trabalha como quiser e no prazo que
+quiser, e submete ao projeto original o desenvido na sua cópia. O dono
+do projeto não tem como saber por que você fez o *fork* (mas você pode
+criar um *issue*) nem quando irá concluir o que almeja. No entanto,
+quando concluir, para que seu trabalho seja incorporado ao original,
+você terá que fazer um *merge request* (isso só é possível entre
+usuários de um mesmo serviço web).
+
 Uma vez com a cópia, você pode fazer um clone e começar a desenvolver os
 projetos. Se a sua intenção é submeter modificações ao original, seja
 ainda mais cuidadoso com as mensagens de *issue*. Escreva sempre no
 idioma original do projeto. Muitas vezes, antecipando esse tipo de
 colaboração, os usuários disponibilizam guias de contribuição
-(*contribution guide*) com instruções de como proceder.
+(*contribution guide*) com instruções de como proceder para maior
+agilidade.
 
 Os *branchs* que criar serão na sua cópia os *pushs* que fizer irão para
-o seu perfil. Quando o seu trabalho tiver concluído, você pode fazer um
-*merge request* que descreveremos a seguir. Se a sua intenção foi usar o
-*fork* como semente para um projeto independente, não se esqueça de dar
-os devidos créditos ao dono da cópia, mesmo que lá no futuro, o seu
-projeto e o original sejam completamente diferentes.
+o seu perfil. Quando o seu trabalho estiver concluído, você pode fazer
+um *merge request* que descreveremos a seguir. Se a sua intenção foi
+usar o *fork* como ponto de partida para um projeto independente, não se
+esqueça de dar os devidos créditos ao dono da cópia, mesmo que lá no
+futuro, o seu projeto e o original sejam completamente diferentes.
 
 ## Merge Request ##
 
@@ -935,52 +936,58 @@ git push origin issue#33
 ```
 
 Na interface web, o membro faz um *merge request* desse ramo para um
-ramo permamente, no qual em projetos simples é o *master* mas em projetos
-maiores é usualmente o *devel*.
+ramo permamente, no qual em projetos simples é o *master* mas em
+projetos maiores é usualmente o *devel*. Ao fazer no *merge request*,
+uma caixa de diálogo abre para que você liste as colaborações que o
+*branch* leva.
 
 Em ambos os serviços, o *merge resquest* leva para um página na qual
 você escolhe que ramo de demanda (doador) será incorporado a um ramo
 permamente (receptor). Ao confirmar os ramos envolvidos, tem-se uma
-caixa de texto destinada as informações sobre quais as modificações devem
-ser incorporadas. Elas servem para justificar, esclarecer e informar o
-responsável pelo *merge* sobre a incorporação. Quando o projeto é
-coletivo e não individual, um membro pode ser indicado como responsável
-pelo *merge*.
-
-Na situação de um *fork*, o processo ocorre de forma semelhante. A
+caixa de texto destinada as informações sobre quais as modificações
+devem ser incorporadas. Elas servem para justificar, esclarecer e
+informar o responsável pelo *merge* sobre a incorporação. Quando o
+projeto é coletivo e não individual, um membro pode ser indicado como
+responsável pelo *merge*. O responsável pelo merge avalia as
+contribuições, se sentir necessidade vê os *diffs* nos arquivos, e pode
+colocar uma mensagem embaixo da sua com questionamentos e até adequações
+que precisarem ser feitas para aceitar o *merge request*.
+
+Quando trata-se de *fork*, o processo ocorre de forma semelhante. A
 sequência de etapas é: fazer o *fork* do projeto para a sua conta, 2)
 clonar o projeto para sua máquina, 3) criar um *branch* e fazer o
 desenvolvimento nele, 4) subir o *branch* (*push*) para a sua conta e 5)
-fazer um *merge request* para incorporar as modificações.
-
-Quando o projeto é um *fork*, na hora de escolher o ramo permanente
-(receptor) tem-se duas opções: 1) incorporar ao *master* da sua cópia
-ou 2) incorporar ao *master* do original. Outra opção é incorporar ao
-*master* da sua cópia e depois pedir um *merge request* do seu *master*
-para o *master* do original. Essa última é útil quando a quantidade de
-modificações é maior e portanto, o trabalho vai levar mais tempo.
-
-O próprio serviço Web tem recurso para a aplicação do *merge* sem
-precisar copiar os ramos envolvidos. Isso facilita bastante o
+fazer um *merge request* para incorporar as modificações. Na hora de
+escolher o ramo permanente (receptor) tem-se duas opções: 1) incorporar
+ao *master* (ou outro) da sua cópia ou 2) incorporar ao *master* (ou
+outro) do original. Outra opção é incorporar ao *master* da sua cópia e
+depois pedir um *merge request* do seu *master* para o *master* do
+original. Essa última é útil quando a quantidade de modificações é maior
+e portanto, o trabalho vai levar mais tempo.
+
+Os próprios serviços web fazem o *merge* diretamente quando não existe
+conflito (merge do tipo *fast forward*). Isso facilita bastante o
 trabalho. Porém, não haver conflito de *merge* não significa que as
 modificações incorparadas estão funcionais, ou seja, as modificações
 feitas precisam ser testadas localmente para verificar surgiram
 efeito. É possível habilitar o serviço Git para checar se o projeto é
-executável, em caso de softwares. Esse recurso se chama intergração
-contínua e veremos na próxima sessão.
-
-Em caso de confito de *merge*, tem-se baixar os ramos. Localmente
-pode-se comparar as diferenças entre eles para entender as fontes de
-conflito. Para isso são recomendáveis as interfaces para Git que serão
-discutidas no próximo Capítulo. Uma vez que o *merge* foi resolvido,
-deve-se fazer o *push* o ramo permanente (receptor) para o serviço web
-que já reconheçe que o *merge* foi feito e fecha a requisição.
-
-Recomenda-se que os ramos de demanda sejam removidos após a incorporação
-nos ramos permanentes. Isso torna o projeto mais claro e concentrado em
-ramos definitivos colhedores de desenvolvimento. Pode-se excluir o ramo
-de demanda incorporado direto pela interface. Por linha de comando
-também é possível.
+executável ou funcional. Esse recurso se chama intergração contínua e
+veremos na próxima sessão.
+
+Em caso de confito de *merge*, tem-se que baixar os ramos (`git
+fetch`). Localmente pode-se comparar as diferenças entre eles para
+entender as fontes de conflito. Para isso são recomendáveis as
+interfaces para Git que serão discutidas no próximo Capítulo. Uma vez
+que o *merge* foi resolvido, deve-se fazer o *push* o ramo permanente
+(receptor) para o serviço web que já reconhece que o *merge* foi feito e
+fecha a requisição automaticamente.
+
+Recomenda-se que os ramos de demanda sejam removidos após sua
+incorporação nos ramos permanentes. Isso torna o projeto mais claro e
+concentrado em ramos definitivos colhedores de desenvolvimento. Pode-se
+excluir o ramo de demanda incorporado direto pela interface marcando uma
+caixa de confirmação sobre remover o ramo apés o merge. Por linha de
+comando também é possível.
 
 ```{r, engine="bash", eval=FALSE}
 ## Deleta o branch issue#33 no servidor (origin).
@@ -993,15 +1000,15 @@ git branch -d issue#33
 git branch -dr origin/issue#33
 ```
 
-Ao concluir incorporar uma contribuição grande, é interessante marcar o
-*commit* vinculado à esse *merge* de uma forma destacável, como por
-exemplo, com uma *tag*.
+Ao incorporar uma contribuição grande, é interessante marcar o *commit*
+vinculado à esse *merge* de uma forma destacável, como por exemplo, com
+uma *tag*.
 
 ```{r, engine="bash", eval=FALSE}
 ## Lista as tags existentes.
 git tag
 
-## Adiciona uma tag ao último commit.
+## Adiciona uma tag anotada ao último commit.
 git tag -a v1.0 -m "Versão 1.0 do software"
 ```