projeto global moja

Esta página contém os detalhes de um projeto de redação técnica aceito para a temporada de documentos do Google.

Resumo do projeto

Organização de código aberto:

moja global

Redator técnico:

TLazypanda

Nome do projeto:

Documentação do guia de integração técnica da FLINT

(em inglês)

Duração do projeto:

Duração padrão (3 meses)

Project description

Documentação do Guia de integração técnica do FLINT para orientar os novos colaboradores durante a integração técnica, para que novos colaboradores possam começar facilmente com suporte mínimo dos mantenedores.

Problemas do projeto

Veja a seguir uma lista das questões mais importantes relacionadas à documentação atual: - Instruções desorganizadas do guia de configuração local, dificultando o início do processo para um novo colaborador. - Vários repositórios do FLINT não têm documentação de sua finalidade e não estão vinculados entre si, tornando difícil para o iniciante identificar qual repositório será instalado. - A instalação do Windows está bem documentada, mas a documentação de instalação baseada em Linux pode ser melhorada. - Atualmente, o fluxo de trabalho do Git não faz parte da documentação

Solução proposta

Esta proposta apresenta uma solução para orientar os novos colaboradores durante a integração técnica. Assim, eles podem começar facilmente com suporte mínimo dos mantenedores. Para isso, basta refatorar a documentação atual para torná-la fácil de usar para iniciantes, além de 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 e refatoração: o objetivo desta fase é revisar o guia atual e refatorá-lo de forma que torne-o conciso e facilmente compreensível para novos colaboradores. A documentação também precisa ser modificada para torná-la mais fácil de usar, adicionando selos, emojis e informações sobre problemas identificados somente para iniciantes ou boas tags de primeiro problema. - Criar um repositório de documentação autônomo central: 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 pedir as diretrizes de contribuição, instruções de configuração do projeto e guias passo a passo. - Adicionar o fluxo de trabalho do desenvolvedor e o 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 proposta será um aplicativo de página única que exibe o fluxo de trabalho, os problemas inéditos que podem ser reivindicados pelos novos colaboradores e uma lista de todos eles. Fase 1: analisar a documentação atual e fazer a refatoração:

Modifique 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 de pré-requisitos 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 maneira mais concisa. Além disso, os guias de instalação são adequados ao Windows, mas, para a instalação do Linux, redirecionar para o repositório FLINT.docker pode ser útil. - FLINT.docker: a documentação atual não fornece a finalidade por trás da configuração desse repositório, que é possibilitar a instalação do FLINT no Linux pelo Docker. O suporte pelo Docker é limitado apenas ao Ubuntu 18.04 (Bionic Beaver), mas pode ser estendido para outras distribuições baseadas em Linux. A documentação atual também precisa dar ênfase à maneira sequencial de configurar os dockerfiles e também informações suficientes sobre como criar a partir do makefile. - FLINT.example: a documentação atual não fornece a finalidade 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 esse repositório ao nosso principal repositório FLINT, oferecendo aos usuários uma maneira de navegar aqui para ver o exemplo em ação.

As seguintes informações precisam ser adicionadas à documentação atual: - Uso do Git e do GitHub: isso vai incluir instruções detalhadas sobre como bifurcar, clonar e definir o upstream remoto para o repositório. Também fornecerá informações sobre como realocar a instância mestre mais recente e lidar com conflitos de mesclagem. - Selos e emojis: a documentação atual não inclui selos e emojis, que ajudam os novos colaboradores a se sentirem acolhidos e considerarem os problemas menos assustadores. - Informações sobre os primeiros timers/problemas de nível iniciante: isso ajudará a redirecionar os novos colaboradores para os problemas de nível iniciante e para o site da comunidade. - Informações sobre o repositório Import-me: ele funciona como um modelo de referência para iniciar 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 é preciso que haja 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 autônomo :

Ferramenta usada para a plataforma de hospedagem:

A ferramenta proposta para essa plataforma de hospedagem é "Ler os documentos", pelos seguintes motivos:- Apresentando uma alta classificação entre as diferentes plataformas de hospedagem. - Atualização automática do commit

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

A ordem de conteúdo proposta é a seguinte:- Introdução à documentação do desenvolvedor: esta seção aborda uma introdução à Moja Global e à FLINT. - Contribuição: esta seção consistirá nas subseções “Formas de contribuir” (em termos de código/relatório de bugs/tradução/documentação/organizar eventos etc.) e “Código de conduta” - Junte-se a nós: esta seção apresenta os vários fóruns sociais, como os canais do Slack, para você se conectar e trabalhar com a Moja Global.

Fase 3: adicionar o fluxo de trabalho do desenvolvedor 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 consiste nas seguintes subseções:

• Arquitetura/conjunto de tecnologias usados e os vários módulos no código: documentação para familiarizar os novos colaboradores com o conjunto de tecnologias implementado, as várias bibliotecas e os módulos da base de código.
• Ferramentas integradas de teste e cobertura: apresentamos novos colaboradores para as ferramentas de pipeline de CI/CD usadas para testes, bots de cobertura e verificações de qualidade automatizadas são executados no código deles. Também fornecer orientações sobre quem proceder em caso de falha dos testes.
• Bots usados para facilitar o fluxo de trabalho.Por exemplo, Zulipbot: como desenvolver modelos de conteúdo para os bots serem exibidos e a documentação estar disponível para permitir que os usuários entendam os bots e até mesmo melhorem a configuração do bot contribuindo.
• Teste manual e envio de uma solicitação de envio: documentação a ser fornecida sobre como testar manualmente as solicitações de envio em relação a determinados padrões e fazer upload dos resultados em termos de capturas de tela/gifs ao enviar solicitações de envio.
• Diretrizes de revisão de solicitação de envio a serem seguidas pelos colaboradores: diretrizes sobre como marcar determinadas equipes para análise e adicionar rótulos, como "Precisa de revisão", à solicitação de envio para permitir que os mantenedores respondam.

Site da comunidade:

O site da comunidade terá os seguintes recursos:-

• Informações sobre nosso fluxo de trabalho: o fluxo de trabalho consistirá na série de ações com que um novo colaborador pode começar, por exemplo, reivindicar um problema de primeiros timers, depois criar um problema de primeiros timers para outra pessoa e ajudar outras pessoas com feedback e análise de solicitações de envio.
• Lista de problemas somente para o primeiro timer: a lista de problemas destinados especificamente a iniciantes ou novos colaboradores.
• Lista de problemas desatualizados: a lista de problemas que não são resolvidos há um longo período e, portanto, está disponível para ser escolhida 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 da Moja Global.
• Links para participar de fóruns de chat: informações e links para participar da comunidade do Slack em perguntas e discussões sobre os projetos.