|
|
|
(Em construção) |
|
|
\ No newline at end of file |
|
|
|
Esta página descreve o método GitLabES Flow e faz parte do [Catálogo do LabES](../home).
|
|
|
|
|
|
|
|
|
|
|
|
## O que é?
|
|
|
|
|
|
|
|
O GitLabES Flow é um método para organizar o fluxo de trabalho de um time de desenvolvedores(as) em torno de um repositório de código [Git](ferramentas/git). Tais métodos são conhecidos como _git flows_ (fluxos git) e existem [vários _git flows_ possíveis](https://dev.to/scottshipp/war-of-the-git-flows-3ec2). O GitLabES Flow é baseado nas ideias de outros _git flows_, adaptadas ao contexto do LabES e à ferramenta que nos provê os repositórios [Git](ferramentas/git), ou seja, o [GitLab](ferramentas/gitlab).
|
|
|
|
|
|
|
|
|
|
|
|
## Quando se aplica?
|
|
|
|
|
|
|
|
Quando se deseja desenvolver software em times, utilizando repositórios [Git](ferramentas/git) no [GitLab](ferramentas/gitlab) e, em especial, permitindo que os(as) desenvolvedores(as) façam revisão de código uns dos outros.
|
|
|
|
|
|
|
|
|
|
|
|
## Como usar/aplicar?
|
|
|
|
|
|
|
|
O GitLabES Flow pode ser aplicado separadamente ou em conjunto com o [Scrum](procedimentos/scrum), possivelmente como parte do [Processo Padrão de Gerência de Projetos no LabES](procedimentos/processo-padrão-de-gerência-de-projetos-no-labes). Nas seções a seguir, explicamos os requisitos para começar a utilizar o fluxo e, em seguida, cada passo do fluxo, explicando a integração com os outros processos do LabES quando houver.
|
|
|
|
|
|
|
|
Ao longo das explicações, nos referimos aos papeis "Coordenador(a) do projeto", "Gerente" e "Pessoas desenvolvedoras (ou Desenvolvedores(as))", definidos no [Processo Padrão de Gerência de Projetos no LabES](procedimentos/processo-padrão-de-gerência-de-projetos-no-labes).
|
|
|
|
|
|
|
|
### Requisitos para uso:
|
|
|
|
|
|
|
|
Para usar o GitLabES Flow, é preciso que o(a) coordenador(a) do projeto ou o(a) gerente delegado(a) por ele(a) façam, inicialmente, o seguinte:
|
|
|
|
|
|
|
|
1. Ter o [GitLab](ferramentas/gitlab) instalado e configurado para uso do time;
|
|
|
|
|
|
|
|
2. [Criar um usuário](https://docs.gitlab.com/ee/user/profile/account/create_accounts.html#create-users-in-admin-area) para cada desenvolvedor(a) do time;
|
|
|
|
|
|
|
|
3. [Criar um projeto](https://docs.gitlab.com/ee/user/project/working_with_projects.html#create-a-project) para o software que será desenvolvido por este time;
|
|
|
|
|
|
|
|
4. Entrar no projeto, acessar **Settings > General > Merge Request Approvals**, na tabela **Approval Rules**, linha **Eligible users**, mudar o valor de **Approvals required** para `1`;
|
|
|
|
|
|
|
|
5. Se estiver usando o [Slack](ferramentas/slack), acessar **Settings > Integrations**, na lista **Add an integration** clicar em **Slack notifications**, preencher o campo **Webhook** com a URL fornecida pelo Slack (mais informações sobre como consegui-la na [página do Slack neste catálogo](ferramentas/slack)) e, no caso do LabES, preencher o campo **Username** com `GitLabES`;
|
|
|
|
|
|
|
|
6. Dar aos(às) desenvolvedores(as) do time [acesso com papel _Developer_](https://docs.gitlab.com/ee/user/permissions.html#project-members-permissions) ao projeto, seja diretamente ou seja por meio de um [grupo](https://docs.gitlab.com/ee/user/group/#groups) (i.e., o(a) desenvolvedor(a) é _Developer_ no grupo e o projeto pertence àquele grupo);
|
|
|
|
|
|
|
|
7. Iniciar o repositório do projeto com a base de código necessária aos(às) desenvolvedores(as) para que possam começar a implementar funcionalidades (entregar estórias de usuário no [Scrum](procedimentos/scrum));
|
|
|
|
|
|
|
|
8. Criar as seguintes [etiquetas (_labels_)](https://docs.gitlab.com/ee/user/project/labels.html#labels): `Ongoing` (sugere-se cor azul `#6699cc`) e `Review` (sugere-se cor verde `#8fbc8f`). Se estiver usando [Scrum](procedimentos/scrum), crie também a etiqueta `Backlog` (cinza `#808080`). Etiquetas podem ser criadas para [cada projeto separadamente](https://docs.gitlab.com/ee/user/project/labels.html#view-project-labels) ou, se estiver usando [grupos](https://docs.gitlab.com/ee/user/group/#groups), [criar para todo o grupo](https://docs.gitlab.com/ee/user/project/labels.html#view-group-labels) e todos os projetos do grupo já herdam as mesmas etiquetas;
|
|
|
|
|
|
|
|
9. Popular o quadro de tarefas do projeto conforme descrição a seguir.
|
|
|
|
|
|
|
|
### Criação de tarefas (_issues_) e marcos (_milestones_):
|
|
|
|
|
|
|
|
Se o time estiver usando o [Scrum](procedimentos/scrum), as tarefas (_issues_) e marcos (_milestones_) podem ser criados pelo(a) gerente(a) a partir do [_template_ de _backlog_](https://docs.google.com/spreadsheets/d/1BxJa9hfIV8BW28IiuifeqtlxU7FvBqlSJdLNIEuqmMU/edit?usp=sharing), com os seguintes passos:
|
|
|
|
|
|
|
|
1. Na página do projeto no [GitLab](ferramentas/gitlab), clique no menu **Issues > Milestones** e no botão **New Milestone** (acima, à direita), preencha o campo **Title** com `Sprint 001` para o primeiro _sprint_, incrementando o número nos _sprints_ seguintes;
|
|
|
|
|
|
|
|
2. Obtendo os dados da aba **_Sprints_** do [_template_ de _backlog_](https://docs.google.com/spreadsheets/d/1BxJa9hfIV8BW28IiuifeqtlxU7FvBqlSJdLNIEuqmMU/edit?usp=sharing), preencha **Start Date** com a data de início do _sprint_, **Due Date** com a data de fim do _sprint_ e **Description** com o objetivo do _sprint_;
|
|
|
|
|
|
|
|
3. Ainda na aba **_Sprints_**, preencha o ID do _sprint_ com o mesmo número do _milestone_ e adicione um _link_ (menu **Inserir > Link** no Google Sheets) para facilitar o acesso dos(as) desenvolvedores(as) à _milestone_ que representa este _sprint_ no [GitLab](ferramentas/gitlab) a partir do _backlog_;
|
|
|
|
|
|
|
|
4. Passando para a aba **_Backlog_** do [_template_](https://docs.google.com/spreadsheets/d/1BxJa9hfIV8BW28IiuifeqtlxU7FvBqlSJdLNIEuqmMU/edit?usp=sharing), use as informações agora para criar, dentro do _milestone_ que representa o _sprint_, uma tarefa (_issue_) para cada estória dentro da seção **Backlog do _Sprint_ (atual)**, conforme os passos a seguir;
|
|
|
|
|
|
|
|
5. Na página do _milestone_ criado (se não estiver aberta, clique no menu **Issues > Milestones** e em seguida no nome do _milestone_ desejado), clique no link _New issue_ que se encontra na barra lateral direita, na seção **Issues**;
|
|
|
|
|
|
|
|
6. Preencha **Title** com o nome/descrição da estória, **Description** com o "como demonstrar" da estória, **Labels** com a etiqueta `Backlog` e **Weight** com a estimativa de esforço da estória;
|
|
|
|
|
|
|
|
7. Caso se queira quebrar a estória em passos menores, sugere-se o uso de [listas de tarefas em MarkDown](https://docs.gitlab.com/ee/user/markdown.html#task-lists) na descrição da estória. O(A) desenvolvedor(a) pode ir marcando os passos já concluídos à medida que avança;
|
|
|
|
|
|
|
|
8. Para cada estória criada como _issue_ no [GitLab](ferramentas/gitlab), preencha o seu ID com o número da _issue_ criada e adicione um _link_ (menu **Inserir > Link** no Google Sheets) para facilitar o acesso dos(as) desenvolvedores(as) à _issue_ que representa esta estória no [GitLab](ferramentas/gitlab) a partir do _backlog_.
|
|
|
|
|
|
|
|
Caso não se esteja utilizando o [Scrum](procedimentos/scrum), o(a) gerente e/ou o(a) coordenador(a) do projeto devem de alguma forma criar as _issues_ no projeto.
|
|
|
|
|
|
|
|
Os demais passos descritos no GitLabES Flow, a seguir, devem ser conduzidos pelos(as) desenvolvedores(as), com supervisão do(a) gerente. Os exemplos citados fazem referência a um projeto criado inicialmente no LabES exatamente para construir e exercitar um fluxo Git para os projetos do laboratório, chamado [Exercício GitLab](https://gitlab.labes.inf.ufes.br/labes/exercicio-gitlab).
|
|
|
|
|
|
|
|
### Obter uma cópia do repositório na sua máquina:
|
|
|
|
|
|
|
|
Assumindo que você [configurou chaves SSH](https://docs.gitlab.com/ee/user/ssh.html#use-ssh-keys-to-communicate-with-gitlab) para não precisar ficar entrando com login e senha toda hora ao acessar o repositório remoto (_origin_), basta escolher um diretório para abrigar o projeto (ex.: `~/Workspaces/LabES`), acessar este diretório usando um terminal e clonar o repositório usando a URL que se encontra na página do repositório (clicando no botão **Clone** (acima, à direita), é a URL abaixo de **Clone with SSH**).
|
|
|
|
|
|
|
|
**Exemplo:** no [Exercício GitLab](https://gitlab.labes.inf.ufes.br/labes/exercicio-gitlab), o comando é:
|
|
|
|
|
|
|
|
```
|
|
|
|
git clone git@gitlab.labes.inf.ufes.br:labes/exercicio-gitlab.git
|
|
|
|
```
|
|
|
|
|
|
|
|
### Escolha uma tarefa e a atribua a si próprio:
|
|
|
|
|
|
|
|
Se o time estiver usando o [Scrum](procedimentos/scrum) é possível acessar a tarefa (_issue_) diretamente a partir do [_template_ de _backlog_](https://docs.google.com/spreadsheets/d/1BxJa9hfIV8BW28IiuifeqtlxU7FvBqlSJdLNIEuqmMU/edit?usp=sharing) (assumindo que o(a) gerente colocou links para as _issues_ na coluna ID de cada estória). Do contrário, pode-se acessá-las clicando no menu **Issues > Milestones** e em seguida no nome do _milestone_ que representa o _sprint_ atual (as _issues_ ficam listadas ao final da página do _milestone_). Neste caso, lembre-se de colocar o seu usuário GitLab (ex.: @vitorsouza) na coluna "Desenvolvedor(a)" na aba **_Backlog_** do [_template_](https://docs.google.com/spreadsheets/d/1BxJa9hfIV8BW28IiuifeqtlxU7FvBqlSJdLNIEuqmMU/edit?usp=sharing).
|
|
|
|
|
|
|
|
Caso não se esteja utilizando o [Scrum](procedimentos/scrum), pode-se ver as tarefas clicando no menu **Issues > List** ou **Issues > Board**, este último simula um [quadro Kanban](https://engsoftmoderna.info/cap2.html#kanban). O quadro tem a vantagem de permitir que você carregue a _issue_ de **Open** para **Ongoing** e clique no seu cartão para modificar outras informações na barra lateral direita como, por exemplo, atribui-la a si próprio (link **assign yourself**).
|
|
|
|
|
|
|
|
Se você, no entanto, abriu a página da _issue_, pode também usar a barra lateral direita para atribuir a _issue_ a si próprio (link **assign yourself** na seção **Assignees**) e atribuir-lhe a etiqueta `Ongoing` na seção **Labels**.
|
|
|
|
|
|
|
|
**Exemplo:** no [quadro de tarefas](https://gitlab.labes.inf.ufes.br/labes/exercicio-gitlab/-/boards) do projeto [Exercício GitLab](https://gitlab.labes.inf.ufes.br/labes/exercicio-gitlab), escolhi uma [tarefa #2](https://gitlab.labes.inf.ufes.br/labes/exercicio-gitlab/-/issues/2): **Implementar o cadastro de UBSs**, colocando-a em meu nome e atribuindo-lhe a etiqueta `Ongoing`.
|
|
|
|
|
|
|
|
### Crie um _merge request_:
|
|
|
|
|
|
|
|
Ainda na página da tarefa _issue_ no [GitLab](ferramentas/gitlab), clique no botão **Create merge request** para começar a trabalhar na tarefa. Isso vai criar um _merge request_ em rascunho (inicia com `Draft:`) e também um ramo (_branch_) do Git a partir do número e nome da _issue_.
|
|
|
|
|
|
|
|
Um _merge request_ (pedido de fusão) é uma solicitação feita por um(a) desenvolvedor(a) que implementou uma estória, funcionalidade, correção, etc. (no caso, ainda vai implementar, pois está em rascunho) num ramo separado da `main`, para que este ramo seja incorporado (feita a fusão) ao ramo principal. Permite que o(a) desenvolvedor(a) trabalhe com liberdade neste ramo (i.e., nenhuma outra pessoa deve mexer neste ramo) e se preocupe com o impacto das mudanças na base de código do projeto apenas no momento da fusão.
|
|
|
|
|
|
|
|
Para começar a trabalhar no novo ramo criado pelo _merge request_, atualize seu repositório local (`git pull origin`) e mude seu diretório de trabalho para o novo ramo (`git checkout -b <nome do ramo>`).
|
|
|
|
|
|
|
|
**Exemplo:** na página da [tarefa #2](https://gitlab.labes.inf.ufes.br/labes/exercicio-gitlab/-/issues/2) do projeto [Exercício GitLab](https://gitlab.labes.inf.ufes.br/labes/exercicio-gitlab), cliquei no botão **Create merge request** e foram criados o [_merge request_ !3](https://gitlab.labes.inf.ufes.br/labes/exercicio-gitlab/-/merge_requests/3) e o ramo (_branch_) `2-implementar-o-cadastro-de-ubss`. Para começar a trabalhar na tarefa, executei os seguintes comandos no terminal, estando no diretório do projeto:
|
|
|
|
|
|
|
|
```
|
|
|
|
git pull origin
|
|
|
|
git checkout -b 2-implementar-o-cadastro-de-ubss
|
|
|
|
```
|
|
|
|
|
|
|
|
### Implemente sua tarefa e faça _commits_
|
|
|
|
|
|
|
|
Já no ramo da tarefa, você pode implementar o código que resolve a tarefa em sua máquina local. Ao fazer isso, você pode fazer um ou mais _commits_ no ramo da tarefa, de acordo com a necessidade. Ao fazer _commits_, sugere-se seguir a especificação [Conventional Commits em português](https://www.conventionalcommits.org/pt-br/v1.0.0/). Pode-se também enviar os _commits_ ao repositório remoto para que já apareçam no GitLab (serve também como _backup_ na nuvem).
|
|
|
|
|
|
|
|
**Exemplo:** após implementar a [tarefa #2](https://gitlab.labes.inf.ufes.br/labes/exercicio-gitlab/-/issues/2) do projeto [Exercício GitLab](https://gitlab.labes.inf.ufes.br/labes/exercicio-gitlab), foram executados os seguintes comandos para adicionar todos os arquivos novos criados, um único _commit_ retratando toda a implementação da _issue_ e o envio de tudo para o repositório remoto:
|
|
|
|
|
|
|
|
```
|
|
|
|
git add --all
|
|
|
|
git commit -m "feat: implementa cadastro de UBSs"
|
|
|
|
git push -u origin 2-implementar-o-cadastro-de-ubss
|
|
|
|
```
|
|
|
|
|
|
|
|
### Mande seu _merge request_ pra revisão
|
|
|
|
|
|
|
|
Após verificar se a tarefa está de fato concluída, tendo efetuado testes pra assegurar que está funcionando, feito(s) o(s) _commit(s)_ e enviado(s) para o repositório remoto (_origin_), faça o seguinte:
|
|
|
|
|
|
|
|
> Dica: quando você faz o envio do _commit_ o repositório remoto indica a URL do _merge request_, facilitando o acesso, pois na página do _merge request_ há um link para a página da _issue_ (logo no início, procure pela frase `Closes #<número da issue>`).
|
|
|
|
|
|
|
|
1. Volte à página da tarefa (_issue_) no [GitLab](ferramentas/gitlab) e atribua-lhe a etiqueta `Review`;
|
|
|
|
|
|
|
|
2. No quadro _Related merge requests_, procure o link para a página do _merge request_ associado à tarefa e clique no link para abrir o _merge request_;
|
|
|
|
|
|
|
|
3. Marque o _merge request_ como pronto clicando em _Mark as ready_, retirando-o do estado de rascunho (_Draft_);
|
|
|
|
|
|
|
|
4. Na barra lateral direita, abaixo de **Reviewers**, especifique quem deverá revisar seu código. O(A) gerente ou o(a) coordenador(a) do projeto podem estabelecer uma regra de quem deve revisar o código de quem (pode ser uma regra simples, ex.: um rodízio por ordem alfabética), procure saber se existe uma para poder segui-la;
|
|
|
|
|
|
|
|
5. Se quiser, adicione outras informações conforme o necessário na descrição do _merge request_, porém mantenha o `Closes #<número da issue>`, pois isso fará com que ela seja fechada automaticamente quando o _merge request_ for aceito. Outra opção é fazer comentários ao final da página do _merge request_;
|
|
|
|
|
|
|
|
6. Aguarde a revisão do seu código, a ser feita pelo(a) seu(ua) colega (ver descrição dos procedimentos de revisão na próxima subseção). Vale a pena avisar ao(à) colega que você lhe atribuiu um _merge request_ para revisão via [Slack](ferramentas/slack) ou qualquer outro canal de comunicação do time.
|
|
|
|
|
|
|
|
Solicitada a revisão de um _merge request_, passe para a próxima tarefa ou verifique se há _merge requests_ dos(as0) seus(uas) colegas para revisar. Lembre-se de sair do ramo da tarefa, voltar para o `main` e atualizar:
|
|
|
|
|
|
|
|
```
|
|
|
|
git checkout main
|
|
|
|
git pull origin
|
|
|
|
```
|
|
|
|
|
|
|
|
### Revise o _merge request_ dos(as) colegas
|
|
|
|
|
|
|
|
Na barra que fica no topo da janela do GitLab, há um botão que te notifica quando há _merge requests_ para você revisar (selecione a opção **Review requests for you**).
|
|
|
|
|
|
|
|
Ao abrir o _merge request_, você pode avaliar o código clicando em **Changes**. Nesta tela é possível adicionar comentários a partes específicas do código. Outra forma de avaliar o código é clicar em **Open in Web IDE** ou ainda seguindo os passos em **Check out branch** para copiar para o seu repositório local.
|
|
|
|
|
|
|
|
Caso você encontre algo que precisa ser discutido ou corrigido, faça comentários para trocar mensagens com o(a) desenvolvedor(a). Quando satisfeito(a), clique no botão **Approve**.
|
|
|
|
|
|
|
|
### Faça a junção (_merge_) do seu código após aprovação
|
|
|
|
|
|
|
|
Uma vez que o(a) revisor(a) do seu código tenha ficado satisfeito(a) e o tenha aprovado, você pode enfim fazer a fusão (_merge_) do seu código (por meio do _merge request_) na base de código principal do sistema. Para isso, abra a página do seu _merge request_ aprovado e clique no botão **Merge**.
|
|
|
|
|
|
|
|
Caso existam conflitos com o código do ramo principal (`main`), será necessário resolvê-los (o que está fora do escopo desta explicação).
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## Lições aprendidas a partir do uso no LabES
|
|
|
|
|
|
|
|
A partir do uso do GitLab Flow no contexto do LabES, temos as seguintes dicas para compartilhar:
|
|
|
|
|
|
|
|
### Atribua ao(à) próprio(a) desenvolvedor(a) a junção de seu _merge request_:
|
|
|
|
|
|
|
|
Nas primeiras versões do GitLab Flow (vide [descrição do Exercício GitLab](https://gitlab.labes.inf.ufes.br/labes/exercicio-gitlab/-/blob/main/README.md)) a fusão (_merge_) do código após aprovação era feita pelo revisor do código e não por quem o havia escrito, como descrito anteriormente. Em maio/2022, no entanto, @atiliodadalto, um dos membros do projeto [Hub Criativo Virtual](https://gitlab.labes.inf.ufes.br/hub-criativo-virtual), fez a seguinte proposta e argumentação, que acabaram sendo motivação para mudança do GitLab Flow, neste ponto, para como ele é hoje:
|
|
|
|
|
|
|
|
> Atualmente, quem faz a _review_ e aprova, também realiza o _merge_. Discutindo com outros colegas, acredito que faça mais sentido deixar o criador do _merge request_ (MR) realizar o _merge_, desde que tenha recebido aprovação pelo revisor. Em geral, quem abre o MR é quem tem uma visão mais consolidada do que pode estar faltando, seja para futuros MRs ou em resposta a pedidos feitos na revisão, etc.
|
|
|
|
>
|
|
|
|
> Em casos ideais, um MR é aberto quando tudo já está feito. Muitas vezes não há mudanças a se fazer mesmo com a revisão, e a aprovação pode ser seguido do _merge_, pelo revisor, sem problemas. No entanto, nem sempre é assim, pois podem haver conflitos de _merge_, etc., e o autor original é, análogo ao meu ponto anterior, geralmente aquele que está melhor equipado para resolver conflitos de _merge_.
|
|
|
|
>
|
|
|
|
> No mais, dar _merge_ no seu próprio MR cria uma sensação de posse, o que acredito que seja benéfico para a motivação, e também para solidificar a sensação de responsabilidade para com aquele código. Por mais que o revisor possa analisar e realizar o _merge_, há uma alienação tanto por parte de quem criou o MR (por não efetivar a mudança), tanto pelo revisor que faz o _merge_ (por não ter confeccionado o código). Também poderíamos ligar a opção de não permitir merge sem ao menos uma aprovação (creio que esteja desligada, demonstro em anexo); acho que os outros _defaults_ são sensatos.
|
|
|
|
|
|
|
|
A obrigatoriedade de uma aprovação para se poder fazer o _merge_ foi incorporada também ao GitLab Flow, tendo sido descrita no início na página, na seção de Requisitos.
|
|
|
|
|
|
|
|
|
|
|
|
## Referências
|
|
|
|
|
|
|
|
- [War of the Git Flows](https://dev.to/scottshipp/war-of-the-git-flows-3ec2);
|
|
|
|
- [How to use GitLab for Agile software development](https://about.gitlab.com/blog/2018/03/05/gitlab-for-agile-software-development/);
|
|
|
|
- [Introduction to GitLab Flow](https://docs.gitlab.com/ee/topics/gitlab_flow.html#introduction-to-gitlab-flow).
|
|
|
|
|
|
|
|
|
|
|
|
## Autores(as)
|
|
|
|
|
|
|
|
- @vitorsouza. |
|
|
\ No newline at end of file |
