projeto global moja

Esta página contém os detalhes de um projeto de escrita 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

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 uma integração técnica, para que os novos colaboradores possam começar facilmente com o suporte mínimo dos mantenedores.

Problemas do projeto

Veja a seguir uma lista dos problemas mais importantes relacionados à documentação atual: - Peças desorganizadas das instruções do guia de configuração local, dificultando o início do processo para novos colaboradores. - Vários repositórios do FLINT não têm documentação da finalidade e não estão vinculados entre si, o que dificulta para o iniciante identificar qual deles vai ser instalado. - A instalação do Windows está bem documentada, mas a documentação de instalação baseada em Linux pode ser melhorada. - No momento, o fluxo de trabalho do Git não está incluído na documentação

Solução proposta

Esta proposta apresenta uma solução para orientar os novos colaboradores durante uma integração técnica, para que os novos colaboradores possam começar facilmente com o suporte mínimo dos mantenedores. Isso pode ser feito refatorando a documentação atual para torná-la acessível 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:- Revisar a documentação existente e a refatoração: o objetivo desta fase é revisar o guia atual e refatorá-lo de forma a torná-lo conciso e facilmente compreensível por novos colaboradores. A documentação também precisa ser modificada para torná-la mais acessível para iniciantes, adicionando selos, emojis e informações sobre problemas identificados somente para iniciantes ou boas tags de primeiros problemas. - 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 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 iniciantes que podem ser reivindicados pelos novos colaboradores e uma lista de todos. Fase 1: revisar a documentação e refatoração atuais:

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 específicos para Windows, mas, para a instalação do Linux, redirecionar ao 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 é permitir 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 enfatizar a maneira sequencial de configurar os dockerfiles e também informações suficientes sobre como compilar 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 é mostrar um exemplo de como usar o FLINT. As diferentes execuções de amostra podem ser melhor separadas com instruções específicas de execução. Também precisamos vincular esse repositório ao nosso principal repositório do FLINT, oferecendo 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 vai incluir instruções passo a passo sobre como bifurcar, clonar e definir o upstream remoto para o repositório. Ele também fornecerá informações sobre como realizar o rebase no mestre mais recente e lidar com conflitos de mesclagem. - Selos e emojis: a documentação atual não tem selos e emojis, que podem ajudar os novos colaboradores a se sentirem acolhidos e considerarem os problemas menos assustadores. - Informações sobre os primeiros tempos/problemas para iniciantes: ajudarão a redirecionar os novos colaboradores para problemas para iniciantes e para o site da comunidade. - Informações sobre o repositório Import-me: esse repositório atua como um modelo de base 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 escolhê-lo como modelo na criação de um novo repositório também precisam ser adicionadas. Também deve haver um processo estabelecido para que os codificadores sugiram recursos adicionais para o repositório Import-me.

Fase 2: criar um repositório de documentação central autônomo :

Ferramenta a ser usada para a plataforma de hospedagem:

A ferramenta proposta para essa plataforma de hospedagem é "Ler os documentos", por estes motivos:- Estar bem posicionado entre as diferentes plataformas de hospedagem. - Atualização automática no envio de confirmação - Fácil de configurar e solucionar problemas de suporte disponível facilmente, já que a grande comunidade a usa - A documentação é formatada usando reStructuredText e a saída é compilada pelo Sphinx.

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

A ordem do conteúdo proposta é a seguinte:- Introdução à documentação do desenvolvedor: esta seção aborda uma introdução à Moja Global e ao 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/organização de eventos etc.) e "Código de conduta". - Configuração do desenvolvimento: esta seção consistirá 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 vai consistir na discussão sobre as ferramentas de extração integradas para testes e sobre como realizar testes manuais e mais integrados. - Junte-se a nós: esta seção fornecerá os vários fóruns sociais, como os canais do Slack, para se conectar e trabalhar com a Moja Global.

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

Documentação do fluxo de trabalho do desenvolvedor:

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

• Tech Stack/Architecture usado e os diversos módulos do código: documentação para familiarizar os novos colaboradores com o conjunto de tecnologias implementado, as várias bibliotecas e módulos da base de código.
• Ferramentas integradas de teste e cobertura: conheça novos colaboradores para as ferramentas de pipeline de CI/CD usadas em testes, bots de cobertura e verificações de qualidade automatizadas que são executadas no código. Também fornecer orientações sobre quem deve proceder se os testes falharem.
• Bots eram usados para facilitar o fluxo de trabalho.Por exemplo, Zulipbot: desenvolvimento de modelos de conteúdo para os bots que serão exibidos e a documentação está disponível para permitir que os usuários entendam os bots e até mesmo melhorem a configuração do bot com uma contribuição.
• Teste e envio manuais 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 no envio de 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 revisão e adicionar rótulos, como "Precisa de revisão", à solicitação de envio para permitir que os administradores respondam.

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 para um novo colaborador, como reivindicar um problema de primeiros passos, criar um problema para uma pessoa que está começando e ajudar outras pessoas com feedback e revisão das solicitações de envio.
• Lista de problemas somente para o primeiro timer: a lista de problemas destinadas 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 se juntar à comunidade do Slack para resolver dúvidas e ter mais discussões sobre os projetos.