projeto global moja

Esta página contém os detalhes de um projeto de redação técnica aceito para a Google Season of Docs.

Resumo do projeto

Organização de código aberto:

moja global

Redator técnico:

Tlazypanda

Nome do projeto:

Documentação do Guia técnico de integração do FLINT

Duração do projeto:

Duração padrão (3 meses)

Project description

Documentação do guia de integração técnica para o FLINT para orientar os novos colaboradores em uma integração técnica para que eles possam começar facilmente com o mínimo de suporte dos mantenedores.

Problemas com o projeto

Confira a seguir uma lista dos problemas mais importantes relacionados à documentação atual: - Peças desorganizadas das instruções do guia de configuração local, o que dificulta o início do trabalho de um novo colaborador. - Vários repositórios do FLINT não têm documentação sobre a finalidade e não estão vinculados entre si, o que dificulta a identificação do repositório a ser instalado por um novato. - A instalação do Windows está bem documentada, mas a documentação de instalação baseada em Linux precisa de melhorias. - O fluxo de trabalho do Git não faz parte da documentação no momento

Solução proposta

Esta proposta apresenta uma solução para orientar os novos colaboradores em uma integração técnica para que eles possam começar facilmente com o suporte mínimo dos mantenedores. Isso pode ser feito refatorando a documentação atual para torná-la simples para iniciantes e também manter um repositório central autônomo para toda a documentação disponível. O projeto é dividido em três fases:- - Revisão da documentação existente e refatoração: o objetivo desta fase é revisar o guia atual e refatorá-lo de uma maneira que o torne conciso e facilmente compreensível por novos colaboradores. A documentação também precisa ser modificada para ser mais amigável para iniciantes, adicionando selos, emojis e informações sobre problemas marcados com tags de "somente para iniciantes" ou "bom problema inicial". - Criar um repositório de documentação central autônomo: o objetivo desta fase é vincular toda a documentação disponível em uma ordem sequencial lógica em um repositório autônomo. Isso envolve ordenar as diretrizes de contribuição, instruções de configuração do projeto e guias detalhados. - Adicionar fluxo de trabalho do desenvolvedor e site da comunidade para novos desenvolvedores: o objetivo desta fase é adicionar o fluxo de trabalho do desenvolvedor, que contém as diretrizes de contribuição do Git e a arquitetura técnica do projeto, além das diretrizes de teste e controle de qualidade. O site da comunidade proposto será um aplicativo de página única que mostra o fluxo de trabalho, problemas para iniciantes que podem ser reivindicados pelos novos colaboradores e uma lista de todos os colaboradores. Fase 1: revisar a documentação atual e fazer refatoração:

Modificar a documentação atual dos seguintes repositórios: - FLINT: a documentação atual não é muito detalhada e não fornece uma ordem sequencial das bibliotecas necessárias. Os guias de instruções passo a passo estão divididos em diferentes PDFs, mas podem ser unificados em um único local de forma mais concisa. Além disso, os guias de instalação são voltados para Windows, mas, para a instalação do Linux, o redirecionamento para o repositório FLINT.docker pode ser benéfico. - FLINT.docker: a documentação atual não informa o objetivo de definir esse repositório, que é fornecer a instalação do FLINT no Linux pelo docker. O suporte pelo Docker é limitado ao Ubuntu 18.04 (Bionic Beaver), mas pode ser estendido para outras distribuições baseadas em Linux. A documentação atual também precisa enfatizar a maneira sequencial de configurar os dockerfiles, além de informações suficientes sobre como criar a partir do makefile. - FLINT.example: a documentação atual não fornece o propósito por trás da configuração desse repositório, que é fornecer um exemplo de como usar o FLINT. As diferentes execuções de amostra podem ser melhor segregadas com instruções específicas para execução. Também precisamos vincular este repositório ao nosso repositório principal do FLINT, fornecendo aos usuários uma maneira de navegar aqui para conferir o exemplo em ação.

As seguintes informações precisam ser adicionadas à documentação atual: - Uso do Git e do GitHub: isso inclui instruções detalhadas sobre como bifurcar, clonar e definir a upstream remota do repositório. Ele também vai fornecer informações sobre como fazer a rebase em relação ao mestre mais recente e lidar com conflitos de mesclagem. - Selos e emojis: a documentação atual não tem selos e emojis, o que pode ajudar os novos colaboradores a se sentirem bem-vindos e encontrar os problemas com mais facilidade. - Informações sobre os problemas para iniciantes: isso vai ajudar a redirecionar os novos colaboradores para problemas para iniciantes e o site da comunidade. - Informações sobre o repositório Import-me: ele funciona como um modelo de referência para dar início a qualquer repositório Moja Global. A documentação atual não menciona a importância disso. Ele precisa ser atualizado para mencionar o repositório Import-me, e as etapas para escolher esse repositório como modelo na criação de um novo repositório também precisam ser adicionadas. Também precisa haver um processo estabelecido para que os programadores sugiram outros recursos para o repositório Import-me.

Fase 2: criar um repositório de documentação central independente :

Ferramenta a ser usada para a plataforma de hospedagem:

A ferramenta proposta para essa plataforma de hospedagem é o Read The Docs devido aos seguintes motivos:- Ter uma boa classificação entre as diferentes plataformas de hospedagem. - Atualização automática ao enviar o commit - Fácil de configurar e suporte para solução de problemas disponível com facilidade devido à grande comunidade que o usa - A documentação é formatada usando reStructuredText e a saída é compilada pelo Sphinx.

Organize todo o conteúdo de maneira sequencial lógica:

A ordem proposta do conteúdo é a seguinte:- - Introdução à documentação para desenvolvedores: esta seção vai abordar a introdução ao Moja Global e ao FLINT. - Contribuições: esta seção consiste nas subseções "Formas de contribuir" (em termos de código/relatórios de bugs/tradução/documentação/organização de eventos etc.) e "Código de conduta". - Configuração de desenvolvimento: esta seção consiste nas subseções "Fluxo de trabalho do Git e GitHub", "Instalação do Windows", "Instalação do Linux". - Fluxo de trabalho do desenvolvedor: esta seção consiste na discussão da próxima fase de testes e de como fazer a integração na próxima fase para testes e como fazer a integração manual. - Junte-se a nós: esta seção vai apresentar os vários fóruns sociais, como os canais do Slack, para se conectar e trabalhar com a Moja Global.

Fase 3: adicionar o fluxo de trabalho de desenvolvedores e o site da comunidade para novos colaboradores:

Documentação do fluxo de trabalho do desenvolvedor:

A documentação do fluxo de trabalho do desenvolvedor vai consistir nas seguintes seções:

• Tech stack/arquitetura usada e os vários módulos no código: documentação para familiarizar os novos colaboradores com a tech stack implementada, as várias bibliotecas e módulos da base de código.
• As ferramentas de teste e cobertura integradas: apresentamos novos colaboradores para as ferramentas de pipeline de CI/CD usadas para testes, bots de cobertura e verificações de qualidade automatizadas executadas no código. Além disso, forneça diretrizes sobre a quem recorrer se os testes falharem.
• Bots usados para facilitar o fluxo de trabalho, por exemplo, o Zulipbot: criação de modelos de conteúdo para exibição dos bots e documentação disponível para que os usuários entendam os bots e até melhorem a configuração deles com contribuições.
• Teste manual e envio de uma solicitação de extração: documentação sobre como testar manualmente as solicitações de extração em relação a determinados padrões e fazer upload de resultados em termos de capturas de tela/gifs no envio de solicitações de extração.
• Diretrizes de análise de solicitações de envio que precisam ser seguidas pelos colaboradores: diretrizes sobre como marcar determinadas equipes para revisão e adicionar rótulos como "precisa de revisão" à solicitação de envio para que os administradores possam responder.

Site da comunidade:

O site da comunidade terá os seguintes recursos:

• Informações sobre nosso fluxo de trabalho: o fluxo de trabalho consiste em uma série de ações que um novo colaborador pode começar, como reivindicar um problema de iniciante, criar um problema de iniciante para outra pessoa e ajudar outras pessoas fornecendo feedback e analisando as solicitações de pull.
• Lista de problemas somente com o primeiro timer: a lista de problemas destinados especificamente para iniciantes ou novos colaboradores.
• Lista de problemas desatualizada: a lista de problemas em que não se trabalhou por um longo período e que, portanto, estão disponíveis para serem escolhidos pelos colaboradores.
• Lista de colaboradores: a lista de colaboradores que contribuíram até o momento para os repositórios da Moja Global.
• Colaboradores recentes: a lista de colaboradores que contribuíram recentemente para os repositórios do Moja Global.
• Links para participar dos fóruns de bate-papo: informações e links para participar da comunidade do Slack para tirar dúvidas e participar de mais discussões sobre os projetos.