Contribuindo com o PO UI
O PO UI é uma biblioteca de componentes baseada em Angular, open source e que nasceu dentro da TOTVS, empresa líder em softwares corporativos na América Latina.
Pensando em como podemos estar ainda mais próximos da comunidade e facilitar o processo de quem deseja contribuir com a biblioteca, teremos esse artigo e o vídeo “PO UI- Como contribuir” feito pelo Jhony Senem, Product Owner e Core Team do PO UI.
Quando eu posso contribuir?
O primeiro passo para que você possa contribuir com o PO UI é ter uma melhoria ou um problema para ser implementado. Este problema pode ser em um dos nossos componentes, serviços ou documentação.
Porém, se você não encontrou nenhum problema ou melhoria e deseja mesmo assim contribuir, é possível encontrar as issues com label “help wanted” no repositório do PO UI no Github.
1. Fazendo fork do projeto no GitHub
Já sabe com o que deseja contribuir no PO UI? O próximo passo é realizar o fork, que consiste em criar uma cópia do repositório com o estado atual. Para isso, você precisa clicar em “Fork” e, após, selecionar o usuário desejado. Seguem os passos nas imagens abaixo:
2. Clonando o repositório
Depois de realizar o fork do projeto é necessário clonar o projeto, para que você possa realizar as alterações que deseja na sua máquina. Para isso, basta você clicar no botão Code e selecionar como você deseja realizar o clone do projeto. No exemplo abaixo, irei utilizar o método por SSH.
Vale ressaltar que para poder realizar o clone por SSH é necessário configurar antes. Neste link possui o passo a passo para configurar sua chave SSH.
Para clonar, clique em Code e selecione a forma que deseja realizar o clone do projeto. Neste exemplo eu estou utilizando por SSH, sendo assim, copiei o texto git@github.com:po-ui/po-angular.git
Depois de copiar o password-protected SSH Key, basta abrir o seu prompt de comando na pasta onde deseja que o repositório seja clonado. No meu caso, utilizei o Windows PowerShell para clonar o projeto na pasta PO UI.
Passo a passo de como realizar clone de um repositório do GitHub
3. Instalando as dependências do projeto
Agora que você já possui o repositório na sua máquina, iremos instalar as dependências do projeto. Para isso, é importante você se atentar aos pré-requisitos para utilizar o PO UI, que são eles: ter instalado o Node.js, seu gerenciador de pacotes favorito e o @angular/cli.
Se você já possui todos os pré-requisitos, você precisa apenas instalar as dependências utilizando o npm install ou yarn install.
$ npm installou
$ yarn install
Nessa etapa também é importante realizar a configuração do git remote para quando você precisar realizar alterações solicitadas no seu pull request. Para isso, dentro da pasta do projeto, você precisa executar o comando abaixo:
$ git remote add upstream git@github.com:po-ui/po-angular.git4. Criando sua branch
Para criar sua branch para iniciar sua codificação é importante se atentar ao padrão que utilizamos no PO UI.
$ git checkout -b <componente>/<issue>Dentro da pasta do projeto po-angular você pode encontrar essas informações detalhadas e com exemplos no arquivo CONTRIBUTING.md. Neste arquivo está listado os padrões para criação de branchs, commits e pull request.
5. Testando o componente
Para que você possa ir testando em tempo de desenvolvimento as alterações que está realizando em um dos componentes da biblioteca, temos dentro da pasta /projects o /app. No app é onde inserimos o componente para ir acompanhando as mudanças que estamos realizando.
No arquivo app.module.ts você pode realizar a importação diretamente da pasta /ui, assim conseguirá acompanhar as alterações em tempo de desenvolvimento.
import { PoModule } from '../../../ui/src/lib';Para rodar o projeto app:
$ ng serve app
6. Fazendo as alterações
Depois de realizar os passos anteriores, é hora de colocar em práticas as alterações necessárias para corrigir ou implementar algo no PO UI. Vale ressaltar que é muito importante estar atento aos colaterais que alguma alteração pode gerar. Por isso, um dos passos mais importantes para nossa biblioteca de componentes são os testes!
Para que possamos evitar ao máximo possíveis bugs, nossa biblioteca trabalha com 100% de cobertura de testes. Então, para que você não tenha seu pull request recusado é importante estar atento aos comandos abaixo.
O npm run serve:dev, é o comando que irá rodar todos os testes unitários em tempo de desenvolvimento. Com isso, quando você fizer uma alteração, os testes serão executados e você poderá acompanhar o status dos testes.
$ npm run test:devO npm run serve:ui, também irá rodar todos os testes unitários, mas com este comando é possível acompanhar a cobertura de testes do projeto.
$ npm run test:ui
Além dos testes unitários, é muito importante revisar o que foi implementado, por isso é importante sempre revisar os seguintes pontos:
- Está seguindo as boas práticas, nomes das variáveis/métodos estão coerentes?
- Cobertura de testes está em 100%?
- Se necessário, foram testados e/ou alterados os exemplos do portal do PO UI?
- Se necessário, estão documentadas as alterações?
Alguns arquivos que temos no projeto para te auxiliar a responder essas perguntas são:
Para gerar o portal e verificar a documentação antes de criar o pull request utilizamos o seguinte comando:
$ npm run build:portal && ng serve portalou, rodar separadamente:
$ npm run build:portal$ ng serve portal
7. Enviando as alterações para o repositório
Finalizado o processo de desenvolvimento e testes, é hora de criar o commit e enviar as alterações para o git. Para isso temos o CONTRIBUTING.md que descreve detalhadamente como você deve criar o seu commit. Alguns dos pontos mais importantes para ficar atento são:
- Padrão de descrição do commit
<TIPO>(ESCOPO): <DESCRIÇÃO CURTA>
<LINHA EM BRANCO>
<CORPO>
<LINHA EM BRANCO>
<RODAPÉ>- O tipo do commit:
build (quando a alteração está relacionada ao build);
docs (quando a alteração for na documentação);
feat (quando for uma melhoria, for criada uma nova funcionalidade ou um novo componente);
fix (para correção de bugs);
perf (quando o item é gerado para melhoria de performance);
refactor (quando for feito uma refatoração ou aplicação de boas práticas);
test (quando forem adicionados ou refatorados os testes);
- Descrição curta e objetiva
adiciona a propriedade p-cleanAlém desses três tópicos, também é considerado o corpo do commit, o rodapé e os breaking changes.
Exemplo de um commit completo:
feat(lookup): adiciona a propriedade p-cleanO componente não permitia o uso da propriedade p-clean,
Este commit está implementando a propriedade para poder
ser utilizada, e limpar o campo a partir de um ícone
de ação.
Fixes #775
Depois de realizar o commit, falta apenas enviar as alterações para o repositório:
git push origin <nome da branch>Se você possui alguma dúvida sobre como fazer push das suas alterações, você pode tirar suas dúvidas na documentação do GitHub.
8. Criando o pull request
Chegou a hora de criar seu pull request! Se você não está familiarizado com esse processo, as informações detalhadas estão no passo a passo da documentação do GitHub para criação de pull request.
No PO UI, temos um template padrão para ser preenchido, que possui o checklist para o revisor, a descrição do comportamento atual, descrição do novo comportamento e como o revisor poderá simular os comportamentos. É importante que nesta etapa você descreva com atenção, pois são essas informações que o time do PO UI utiliza como parâmetro para revisar.
Agora é só aguardar que nós do Core Team do PO UI iremos revisar sua contribuição e se necessário solicitar os ajustes. Quando sua contribuição for aprovada, ela estará disponível na próxima release do PO UI!🙌
Se ainda assim, você possui alguma dúvida sobre o processo de contribuição, não hesite em entrar em contato conosco! Além deste artigo, temos vários artigos no Developers TOTVS utilizando nossa biblioteca de componentes e o vídeo “PO UI- Como contribuir” feito pelo Jhony Senem.
