Skip to content

Conflitos Frequentes de Edição nos Arquivos de README #470

@camilamaia

Description

@camilamaia

Descrição

Atualmente, estamos enfrentando muitos conflitos ao editar os arquivos de documentação, especialmente os README.md e README_EN.md. Isso ocorre porque múltiplas pessoas frequentemente estão editando os mesmos arquivos ao mesmo tempo, o que gera conflitos de mesclagem. Como cada novo utilitário ou atualização requer que os documentos sejam modificados, a sobrecarga de resolver esses conflitos tem sido um obstáculo para manter a documentação atualizada de forma eficiente.

Problema

  • Conflitos de mesclagem frequentes, pois vários colaboradores editam os mesmos arquivos simultaneamente.
  • Dificuldade em gerenciar os conflitos e garantir que a documentação seja atualizada sem perdas de informações ou erros.

Soluções Propostas

Algumas ideias que vieram a cabeça:

  1. Dividir a Documentação em Arquivos Menores e Modulares:

    • Separar a documentação em arquivos menores e mais específicos para cada utilitário (ex: cpf.md, cnpj.md, etc.), e incluir esses arquivos nos README.md e README_EN.md com um mecanismo de inclusão dinâmica (como include no Markdown ou utilizando scripts de automação).
    • Isso evitaria a sobrecarga de edição em arquivos grandes e facilitaria a colaboração, pois as mudanças em um utilitário específico ficariam restritas ao seu próprio arquivo.
  2. Usar Arquivos de Configuração YAML para Gerar a Documentação:

    • Criar arquivos de configuração YAML para cada utilitário, onde cada arquivo contém as informações sobre as funções e exemplos do utilitário. Esses arquivos serão lidos por um script automatizado que gerará a documentação de forma estruturada.
    • A estrutura proposta seria um diretório por utilitário, com arquivos YAML para cada função ou característica do utilitário (ex: cpf/is_valid.yml, cpf/format.yml, etc.).
    • O script de geração de documentação processaria esses arquivos YAML e geraria automaticamente as entradas para o README.md, evitando a edição manual simultânea e garantindo que a documentação esteja sempre atualizada.

    Exemplo de Estrutura:

    docs/utils/
    └── cpf/
        └── is_valid.yml
        └── format.yml
    └── cnpj/
        └── is_valid.yml
        └── format.yml
    

    Exemplo de arquivo:

        cpf:
       is_valid_cpf:
         pt-br:
           title: "is_valid_cpf"
           description: "Retorna se os dígitos de verificação do CPF fornecido correspondem ao seu número base. Esta função não verifica a existência do CPF; ela apenas valida o formato da string."
           arguments:
             cpf:
               type: "str"
               description: "O CPF a ser validado, uma string de 11 dígitos"
           returns:
             type: "bool"
             description: "Verdadeiro se os dígitos de verificação corresponderem ao número base, Falso caso contrário."
           example: |
             >>> from brutils import is_valid_cpf
             >>> is_valid_cpf("82178537464")
             True
             >>> is_valid_cpf('00011122233')
             False
         en:
           title: "is_valid_cpf"
           description: "Returns whether the verification digits of the provided CPF match its base number. This function does not verify the existence of the CPF; it only validates the string's format."
           arguments:
             cpf:
               type: "str"
               description: "The CPF to be validated, a string of 11 digits."
           returns:
             type: "bool"
             description: "True if the verification digits match the base number, False otherwise."
           example: |
             >>> from brutils import is_valid_cpf
             >>> is_valid_cpf("82178537464")
             True
             >>> is_valid_cpf('00011122233')
             False

Passos

Impacto Esperado

  • Redução de conflitos de mesclagem na documentação.
  • Melhor organização da documentação com maior modularidade.
  • Processo de contribuição mais eficiente e sem sobrecarga para os colaboradores.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions