Convensão de nomenclatura no BitBucket / GitHub

Marco Vidoca
Nov 1 · 4 min read

“There are only two hard things in Computer Science: cache invalidation and naming things” ~ Phil Karlton

Um dos principais propósitos do BitBucket / GitHub é compartilhar as diferentes versões de uma base de código (repositório) entre múltiplos desenvolvedores que nela trabalham.

Ao compartilhar um código, precisamos pensar em como outros desenvolvedores irão entender cada ponto do nosso código e tudo começa no nome do repositório e nas mensagens dos commits. E é esse o foco desse post: compartilhar a nomenclatura que a Enext utiliza (desconsiderando repositórios legados) nos nomes dos repositórios e também nas mensagens de commits para que sejam claros, precisos e concisos.

PADRÃO DE NOMENCLATURA PARA OS REPOSITÓRIOS

A priori, dividimos nossos repositórios em 4 tipos:

  • Códigos de frontend;
  • Códigos backend de serviços web: Atendem requisições e fazem alto uso de operações IO geralmente;
  • Códigos backend de serviços worker: Alto uso de cpu e/ou operação demorada. Dentro do repositório de um serviço worker, poderá haver o código de um serviço web que servirá apenas como um trigger dos principais processos e serviços definidos no worker;
  • Códigos devops: Descrevem o propósito, a arquitetura e a infra de um projeto, bem como dos suprojetos se for o caso. É nesse repositório que descrevemos e colocamos os arquivos pertinentes a cada um dos diferentes ambientes que tal projeto/aplicação será submetido (dev, staging, test, prod etc). Além disso, tal repositório irá conter alguns scripts e arquivos pertinentes ao processo de CI/CD. Nem todos os scripts de CI/CD estarão nesse repositório, pois para alguns desses scripts, como é o caso do bitbucket-pipelines.yml, faz mais sentido ele estar em cada um dos repositórios do backend ou frontend).

Nome de repositório com códigos de frontend

{{organization}}-{{projectName}}-front-{{majorVersion}}

Ex. 1: apple-itunes-sac-front-v1
Ex. 2: enext-runrun-task-evaluation-front-v2

  • organization: Nome da organização a qual aquele repositório está associado;
  • projectName: Nome do projeto;
  • majorVersion: Letra ‘v’ seguida do “major” daquele repositório. Para saber mais sobre um bom padrão de versionamento e também o que o “major” representa, consulte https://semver.org/

Observações

  • Utilizamos hífen para separar as letras ao invés de espaço pois o nome que damos aos repositórios é utilizado em urls;
  • Para evitar incompatibilidade de encoding nos diferentes sistemas que armazenam nossos nomes de repositórios, utilizamos apenas as 26 letras do alfabeto latino em minúsculo, digitos de 0 a 9 e o hífen;
  • Caso hajam projetos com múltiplos subprojetos, recomendamos utilizar um acrônimo ou abreviação do nome do projeto seguido pelo nome do suprojeto. Como exemplo para o suprojeto de construção do frontend para um portal voltado para um lojista que está dentro do projeto Enext Market Ads temos o seguinte nome de repositório: enext-xma-seller-portal-front-v1;
  • Caso o frontend seja desenvolvido para uma plataforma de ecommerce específica, recomendamos utilizar um acrônimo ou abreviação de tal plataforma. Para o frontend de uma loja feita na plataforma Oracle Commerce Cloud poderiamos utilizar a seguinte nomenclatura: apple-occ-itunes-store-front-v1.

Nome de repositório com códigos backend de serviços web

{{organization}}-{{projectName}}-web-service-{{majorVersion}}

Ex. 1: apple-itunes-sac-web-service-v1
Ex. 2: enext-runrun-task-evaluation-web-service-v2

Nome de repositório com códigos backend de serviços worker

{{organization}}-{{projectName}}-worker-service-{{majorVersion}}

Ex. 1: apple-itunes-worker-service-v1
Ex. 2: enext-runrun-task-evaluation-worker-service-v2

Nome de repositório com códigos devops

{{organization}}-{{projectName}}-devops-{{majorVersion}}

Ex. 1: apple-itunes-devops-v1
Ex. 2: enext-runrun-task-evaluation-devops-v2

PADRÃO DE NOMENCLATURA PARA AS MENSAGENS DE COMMITS

Para as mensagens de commit seguimos um padrão baseado no Conventional Commits em conjunto com o id da tarefa no runrun.it, sistema de gerenciamento de projetos e tarefas utilizados pela Enext, que está atrelada àquele commit. Recomendamos utilizar sempre a mesma língua nas mensagens de commits e fazer preferencialmente em inglês.

Exemplos:

feat: Allow provided config object to extend other configs (#125386)

No padrão Conventional Commits iniciamos cada commit com um tipo: https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#type

  • build: Mudanças que afetam o sistema de build ou dependências externas (example scopes: gulp, broccoli, npm);
  • ci: Mudanças nos arquivos/scripts de continuos integration (example scopes: Travis, Circle, BrowserStack, SauceLabs);
  • docs: Mudanças na documentação;
  • feat: Nova “feature”;
  • fix: Correção de um bug;
  • perf: Mudança que melhora performance;
  • refactor: Mudança no código que não adiciona novas “features” ou corrige bugs;
  • style: Mudanças que não afetam o significado do código (white-space, formatting, missing semi-colons, etc);
  • test: Adicionando testes faltantes ou corrigindo testes existentes.

Um bom exemplo desse padrão de commits pode ser visto no repositório do Angular: https://github.com/angular/angular/commits/master

Espero que o padrão de nomenclatura adotado pela Enext ajude você na difícil tarefa de determinar bons nomes de repositórios e também bons nomes para as mensagens de commits. Se quiser aprender mais sobre esse padrão na prática estamos sempre com vagas abertas: https://enext.gupy.io/

REFERÊNCIAS

enext ideas

Medium da Enext, consultoria focada no mercado de e-commerce e martech. Aqui você encontra postagens sobre as principais tecnologias e desafios deste complexo ecossistema.

Marco Vidoca

Written by

enext ideas

Medium da Enext, consultoria focada no mercado de e-commerce e martech. Aqui você encontra postagens sobre as principais tecnologias e desafios deste complexo ecossistema.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade