colabs_github.Rmd

---
title: 'Trabalho em colaboração'
author: "Gabriel Nakamura"
date: "`r Sys.Date()`"
output: html_document
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE, fig.align = "center")
```

```{r klippy, echo=FALSE, include=TRUE}
klippy::klippy()
```

# Apresentação

Outra potencialidade do git e GitHub é a possibilidade de utilizar estas ferramentas para trabalhos colaborativos eficientes. Quem nunca perdeu aquela versão que o colaborador/colaboradora enviou por email? ou aquele arquivo importante enviado por Whats? Ou mesmo numa pasta compartilhada com ferramentas específicas de armazenamento em nuvem, quem nunca se deparou com "você tem OneDrive? e Google Drive?".

Pois essa seção visa mostrar o básico sobre trabalho em colaboração utilizando o GitHub. Nada melhor que começar com essas palavras da Jenny Brian

```{r echo=FALSE, eval=TRUE,out.width="60%"}
knitr::include_graphics(here::here("figs", "colab-horst-brian.png"))
```

# Branches

Os branches são versões alternativas do trabalho que fazemos no `main` ou `master`. Em outras palavras, são desvios de rotas que podem ser usados para testar, por exemplo, análises diferentes, ou um local seguro para os colaboradores fazerem modificações que acha pertinente, sem comprometer o trabalho que está sendo realizado no `main`, que, vale lembrar, também é um branch.

## Criando um branch

Podemos criar branches de duas formas distintas: 

1 - usando o próprio GitHub no browser - nesta opção devemos ir até a página do repositório e criar um novo branch como demonstrado na imagem a seguir. Basta clicar em master, digitar um novo nome para o branch e pedir para criar um novo branch com o nome digitado.

```{r echo=FALSE, eval=TRUE,out.width="60%"}
knitr::include_graphics(here::here("figs", "colab-branch.png"))
```

**Obs** Quando esta opção for utilizada, ao retornar para o RStudio não se esqueça de fazer um `pull` no seu diretório. Lembre-se, as modificações foram feitas apenas no repositório remoto, então precisamos "puxar" essas modificações para o nosso diretório local. Após o pull uma mensagem irá aparecer no seu console (se estiver mexendo na linha de comando), ou num pop-up (se estiver mexendo no RStudio)

```{r echo=FALSE, eval=TRUE,out.width="60%"}
knitr::include_graphics(here::here("figs", "new-branch-pull.png"))
```


2 - Podemos usar a linha de comando no terminal e criar o branch

```{r echo=TRUE,eval=FALSE}
git branch nome-para-novo-branch
```

Na linha de comando usamos a função `branch` do git e nomeamos o novo branch com o nome desejado.

## Navegando entre branches

Para navegar entre branches podemos utilizar duas abordagens

1 - usando o RStudio, basta clicar na seta onde está escrito o nome do branch (master geralmente), e você vai ver as opções de branches existentes

```{r echo=FALSE, eval=TRUE,out.width="60%"}
knitr::include_graphics(here::here("figs", "colab-branch-change.png"))
```

2 - usando a linha de comando, como demosntrado abaixo

```{r echo=TRUE,eval=FALSE}
git checkout nome-do-branch
```

Usamos a função `checkout` do git para acessar um branch. Você vai notar que ao modificar o branch, os arquivos no seu diretório vão mudar (caso os arquivos de um branch e de outro sejam diferentes).

## Fusionando os branches (merge)

Vamos supor que estamos trabalhando em conjunto com outros colaboradores. O seu colaborador teve uma ideia que pode melhor o trabalho que está fazendo, por exemplo, adicionando um novo modelo para análise de dados. O colaborador/colaboradora resolve implementar esta modificação em um novo branch. Essa implementação funciona melhor que a anterior e então resolvemos adotar ela como a nova estratégia de análise de dados. Mas ela vive em um branch diferente do `main`, sendo que o ideal é que ela seja incorporada no main. Ou seja, queremos fusionar o branch do colaborador/colaboradora, ao passo que mantemos as modificações no branch main. Fazemos isso com um a função `merge` do git.

De novo, existem duas formas de se fazer isso

1 - utilizando o GitHub online. Navegue até a página do seu repositório. Acesse o branch que quer fazer o merge no branch main. Note que, em caso de diferenças entre os branches, uma mensagem aparecerá perguntando se você quer comparar os branches e abrir um pull-request, como na imagem abaixo

```{r echo=FALSE, eval=TRUE,out.width="60%"}
knitr::include_graphics(here::here("figs", "merge-pull-request.png"))
```

Neste momento, o github está te dizendo: "Existe uma diferença entre o branch main e o branch novo criado, você quer revisar essas modificações e abrir um pull-request para o proprietário deste repositório?, e depois quer fusionar esses branches?" Com isso você pode mergir os branches. **OBS** lembre-se de que quando voltar para o RStudio você precisa dar um `pull`

2 - podemos utilizar a linha de comando. Nela vá até o branch que deseja incorporar as mudanças do outro branch, e use a função `merge`do git 

```{r echo=TRUE,eval=FALSE}
git checkout main
git merge nome-do-branch
```

Pronto, agora o branch `main` incorporou as modificações do branch `nome-do-branch`


# Prática

Como prática sugerimos que os estudantes se juntem em duplas e simulem um trabalho colaborativo. O roteiro seria mais ou menos esse:

1 - Uma pessoa convida um colaborador para o seu repositório no Github. A pessoa convidada deve aceitar o convite. 

2 - O colaborador deve criar um novo branch seguindo uma das formas ilustradas acima (ou outra que ache mais conveniente)

3 - Faça algumas modificações no branch novo criado e faça um pull-request

4 - A pessoa responsável pelo repositório deve revisar o pull-request e incorporar as sugestões no `branch main`


# Referências

Como sempre, o livro da Jenny Brian - Happy Git and GitHub for the UseR