Reverter PR #668: Breaking Change na função de CEP

[niltonpimentel02]

Contexto

Pessoal vamos ter que fazer o revert desse PR para o commit anterior f00812b pelos seguintes motivos que eu acabei não levando em conta no dia que fiz o review e merge:

1. Mudança de assinatura da função (breaking change)

O PR altera a assinatura da função de CEP já existente, o que caracteriza uma breaking change para a biblioteca:

• Projetos que já utilizam essa função na versão atual da lib podem:
  • deixar de compilar,
  • ou falhar em tempo de execução,
  • ou mudar de comportamento silenciosamente (o pior cenário).

Como o brazilian-utils é uma biblioteca utilizada por terceiros, mudanças de assinatura em funções públicas precisam seguir um fluxo mais cuidadoso (ex.: major version, comunicação prévia, deprecation, etc.), o que não aconteceu aqui (Niltinho está aprendendo ainda hehe).

2. Otimizações não deveriam quebrar a API existente

O objetivo do PR é otimizar a função de CEP, mas, para manter a estabilidade da API pública, seria mais adequado:

• Não alterar a função existente, mantendo:
  • mesma assinatura,
  • mesmo contrato,
  • mesmo comportamento esperado.
• Caso seja realmente necessário um novo comportamento ou interface, criar:
  • uma nova função (ex.: cep_optimized, fast_cep_validate, etc.), ou
  • uma nova camada interna de implementação, mantendo a interface pública intacta.

Dessa forma:

• mantemos a lib backward compatible;
• permitimos que consumidores migrem de forma gradual para a versão otimizada;
• reduzimos o risco de quebrar sistemas em produção que dependem do comportamento atual.

3. Manutenibilidade e histórico de código

Do ponto de vista de manutenibilidade, é importante:

• preservar o código já consolidado e amplamente utilizado;
• evitar refactors agressivos em funções públicas sem período de depreciação;
• manter um histórico claro, onde:
  • a função original continua existindo,
  • e uma nova implementação otimizada é adicionada de forma incremental.

Isso facilita:

• debugar problemas em produção;
• comparar comportamentos entre versões;
• avaliar o impacto da otimização com mais segurança.

Proposta

1. Reverter o PR #668, retornando o código para o commit:

   f00812b35233b2f9b688bcba3f89786143750526
   

2. Discutir uma abordagem alternativa para otimização que:

   • não altere a assinatura pública da função existente; ou
   • introduza uma nova função/documentação, mantendo a API atual intacta.