Araponga Logo

Wiki Araponga

Documentação Completa

📘 Cartilha Completa - Arah

Guia Detalhado para Todos os Papéis na Construção do Arah

Versão: 1.0
Data: 2025-01-20

Esta cartilha é um guia completo para todas as pessoas que querem contribuir com o Arah, independente do papel ou nível de experiência.

Objetivo: Facilitar organização orgânica de um time livre em torno de um objetivo comum e territorial, construindo com consciência elevada.

Princípio: Cada pessoa contribui conforme capacidade, interesse e disponibilidade, sempre respeitando valores de autonomia territorial, decolonização digital e reconhecimento da inteligência como valor.

Consciência: Esta cartilha é escrita e deve ser lida com respeito profundo à diversidade de saberes, à autonomia das pessoas e à importância do território como base de tudo.

Estrutura do Time

Organização Orgânica

O time do Arah é orgânico e livre:

  • ✅ Sem hierarquias rígidas
  • ✅ Organização natural em torno de objetivos
  • ✅ Contribuições conforme capacidade
  • ✅ Respeito a diferentes tipos de expertise

Comunicação Horizontal

  • Discord para conversas e discussões
  • GitHub para código e propostas
  • Documentação para conhecimento compartilhado
  • Reuniões quando necessário (opcional)

Papéis e Responsabilidades

Quem são: Pessoas que escrevem código e constroem a plataforma

Responsabilidades:

  • Implementar funcionalidades
  • Manter código e infraestrutura
  • Adicionar testes
  • Documentar código
  • Revisar Pull Requests

Como começar: 👉 Onboarding para Desenvolvedores

Salas Discord: #desenvolvedores, #desenvolvimento-geral

Quem são: Pessoas que observam territórios e propõem funcionalidades

Responsabilidades:

  • Observar necessidades territoriais
  • Documentar propostas funcionais
  • Validar funcionalidades com comunidades
  • Testar do ponto de vista do usuário
  • Propor melhorias baseadas em uso real

Como começar: 👉 Onboarding para Analistas Funcionais

Salas Discord: #analistas-funcionais, #propostas-funcionais

Quem são: Pessoas que usam a plataforma e identificam necessidades

Responsabilidades:

  • Usar a plataforma no território
  • Reportar bugs e problemas
  • Propor melhorias baseadas em uso
  • Compartilhar necessidades territoriais
  • Participar de validações

Como começar: 👉 Onboarding Público

Salas Discord: #geral, #feedback-comunidade

Quem são: Pessoas que facilitam organização quando necessário

Responsabilidades:

  • Facilitar discussões
  • Organizar prioridades (quando necessário)
  • Coordenar esforços maiores
  • Manter visão geral do projeto

Nota: Não há hierarquia - coordenadores facilitam, não comandam.

Salas Discord: #coordenação (se necessário)

Fluxos de Trabalho

1. Identifica necessidade ou funcionalidade
   ↓
2. Discute no Discord (opcional, mas recomendado)
   ↓
3. Cria Issue no GitHub descrevendo necessidade
   ↓
4. Desenvolvedor implementa seguindo padrões
   ↓
5. Cria Pull Request com testes e documentação
   ↓
6. Code Review (qualquer pessoa pode revisar)
   ↓
7. Merge após aprovação
   ↓
8. Deploy e validação com comunidade

1. Observa necessidade no território
   ↓
2. Documenta observação e necessidade
   ↓
3. Propor funcionalidade (Issue no GitHub)
   ↓
4. Discute no Discord (#propostas-funcionais)
   ↓
5. Valida com comunidade (se necessário)
   ↓
6. Ajusta proposta baseado em feedback
   ↓
7. Desenvolvedor implementa (se aprovado)
   ↓
8. Analista testa e valida se atende necessidade

1. Usa plataforma no território
   ↓
2. Identifica bug ou melhoria
   ↓
3. Reporta no GitHub (Issue) ou Discord (#feedback-comunidade)
   ↓
4. Comunidade valida se é problema comum
   ↓
5. Prioriza (se necessário)
   ↓
6. Desenvolvedor ou Analista trabalha na solução
   ↓
7. Comunidade testa solução

Ferramentas e Recursos

Para quê: Comunicação, discussões, organização do time

Principais salas:

  • #geral - Discussões gerais sobre o projeto
  • #sala-pública - Entrada para novos membros, apresentações
  • #desenvolvedores - Espaço para desenvolvedores
  • #analistas-funcionais - Espaço para analistas
  • #propostas-funcionais - Discussão de propostas
  • #feedback-comunidade - Feedback de uso
  • #desenvolvimento-geral - Discussões técnicas gerais

Como usar:

  1. Entre na Sala Pública primeiro
  2. Apresente-se brevemente
  3. Explore outras salas conforme interesse
  4. Participe de discussões relevantes

👉 Guia Completo do Discord

Para quê: Código, Issues, Pull Requests, Discussions

Principais áreas:

  • Issues: Propostas de funcionalidades, bugs, melhorias
  • Pull Requests: Contribuições de código
  • Discussions: Debates sobre funcionalidades e direção
  • Code: Código fonte do projeto
  • Wiki: Documentação complementar (se habilitada)

Como usar:

  1. Explore Issues abertas
  2. Escolha algo para trabalhar
  3. Crie Pull Request seguindo template
  4. Participe de code reviews

👉 Guia Completo do GitHub

Cursor (Para Desenvolvedores)

Para quê: Desenvolvimento de código com IA

Como usar:

  • Cursor lê automaticamente .cursorrules
  • Segue padrões do projeto automaticamente
  • Ajuda a escrever código consistente
  • Valida antes de PR

👉 Onboarding para Desenvolvedores

Para quê: Conhecimento compartilhado, referência, onboarding

Principais documentos:

  • docs/ONBOARDING_PUBLICO.md - Entrada para o projeto
  • docs/ONBOARDING_DEVELOPERS.md - Guia para desenvolvedores
  • docs/ONBOARDING_ANALISTAS_FUNCIONAIS.md - Guia para analistas
  • docs/01_PRODUCT_VISION.md - Visão e propósito
  • docs/00_INDEX.md - Índice completo

Comunicação e Colaboração

Princípios de Comunicação

Clareza

  • Seja claro e direto
  • Use linguagem simples (evite jargão quando não necessário)
  • Dê exemplos concretos do território
  • Explique contexto quando relevante

Respeito

  • Seja respeitoso com todas as pessoas
  • Valorize diferentes perspectivas
  • Acolha iniciantes e suas perguntas
  • Reconheça contribuições diversas

Transparência

  • Compartilhe conhecimento
  • Documente decisões importantes
  • Comunique dificuldades e bloqueios
  • Seja aberto a feedback

Canais de Comunicação

Discord - Conversas Rápidas

Quando usar:

  • Perguntas rápidas
  • Discussões sobre funcionalidades
  • Coordenação informal
  • Conversas em tempo real

Quando NÃO usar:

  • Decisões que precisam ser documentadas (use GitHub)
  • Discussões técnicas longas (use GitHub Discussions)
  • Anúncios formais (use GitHub ou ambos)

GitHub - Documentação e Código

Quando usar:

  • Issues e propostas de funcionalidades
  • Pull Requests e code reviews
  • Discussions técnicas
  • Documentação de decisões

Quando NÃO usar:

  • Conversas casuais
  • Perguntas muito rápidas
  • Coordenação imediata

Email - Casos Especiais

Quando usar:

  • Questões sensíveis
  • Contato direto necessário
  • Assuntos que não cabem em Discord/GitHub

Discord - Organização do Time

Estrutura de Salas

#sala-pública

Propósito: Entrada principal para novos membros

Quando usar:

  • Apresentar-se quando entrar no projeto
  • Fazer perguntas gerais sobre o projeto
  • Conhecer outras pessoas do time
  • Entender como tudo funciona

Regras:

  • Seja acolhedor com novos membros
  • Responda perguntas de forma clara
  • Direcione pessoas para salas específicas quando apropriado

💬 Discussões Gerais

#geral

Propósito: Discussões gerais sobre o projeto

Quando usar:

  • Conversas sobre o projeto
  • Anúncios gerais
  • Discussões que não cabem em outras salas

👨‍💻 Desenvolvedores

#desenvolvedores

Propósito: Espaço para desenvolvedores discutirem código

Quando usar:

  • Discussões técnicas
  • Dúvidas sobre implementação
  • Coordenação de desenvolvimento
  • Compartilhar aprendizados

Quem pode usar: Desenvolvedores e pessoas interessadas em desenvolvimento

#analistas-funcionais

Propósito: Espaço para analistas discutirem necessidades e propostas

Quando usar:

  • Discussões sobre necessidades territoriais
  • Debates sobre propostas funcionais
  • Validação de funcionalidades
  • Compartilhar observações

Quem pode usar: Analistas funcionais e pessoas interessadas em análise

#propostas-funcionais

Propósito: Discussão de propostas de funcionalidades

Quando usar:

  • Apresentar nova proposta de funcionalidade
  • Debater proposta antes de criar Issue
  • Validar necessidade de funcionalidade
  • Refinar proposta baseado em feedback

Quem pode usar: Todos (analistas, desenvolvedores, comunidade)

💭 Feedback da Comunidade

#feedback-comunidade

Propósito: Feedback de uso da plataforma

Quando usar:

  • Compartilhar experiência de uso
  • Reportar problemas encontrados
  • Sugerir melhorias baseadas em uso
  • Validar funcionalidades implementadas

Quem pode usar: Todos, especialmente comunidade

🔧 Desenvolvimento Geral

#desenvolvimento-geral

Propósito: Discussões técnicas gerais

Quando usar:

  • Questões técnicas que não são específicas de código
  • Discussões sobre arquitetura
  • Planejamento técnico
  • Compartilhar recursos técnicos

Quem pode usar: Desenvolvedores e pessoas interessadas

Boas Práticas no Discord

Quando entrar, apresente-se na Sala Pública:

  • Nome (como quer ser chamado)
  • Interesse no projeto
  • Como quer contribuir (se já sabe)
  • Qualquer expertise relevante

Exemplo:

"Oi! Sou João, matemático que trabalha com construção. Interessado em contribuir como desenvolvedor ou analista funcional. Conheço Python e lógica, mas não muito sobre .NET. Quero aprender!"

Participação

  • Seja ativo mas não invasivo
  • Responda perguntas quando souber
  • Pergunte quando não souber (ninguém sabe tudo)
  • Compartilhe conhecimento e aprendizados

Organização

  • Use threads para discussões que se estendem
  • Marque pessoas (@username) quando relevante, mas não abuse
  • Respeite propósito de cada sala
  • Mova conversas para sala apropriada se necessário

Linguagem

  • Seja claro e direto
  • Use linguagem simples quando possível
  • Dê exemplos do território quando relevante
  • Traduza jargão técnico quando falando com não-técnicos

Canais de Texto Adicionais (Opcionais)

Se necessário, podem ser criados:

  • #off-topic - Conversas casuais
  • #recursos - Compartilhar recursos úteis
  • #celebracoes - Celebrar conquistas e marcos
  • #ajuda - Pedir ajuda específica

GitHub - Controle de Código

Estrutura do Repositório

Arah/
├── backend/          # Código do backend (.NET)
├── frontend/         # Código do frontend (se houver)
├── docs/             # Documentação
├── .cursorrules      # Regras para Cursor (desenvolvedores)
└── README.md         # Visão geral do projeto

Para quê: Propostas, bugs, melhorias, tarefas

Tipos:

  • Feature - Nova funcionalidade
  • Bug - Correção de problema
  • Enhancement - Melhoria em funcionalidade existente
  • Documentation - Melhorias em documentação
  • Question - Perguntas sobre o projeto

Como criar:

  1. Vá para "Issues" > "New Issue"
  2. Escolha template apropriado (se houver)
  3. Preencha descrição clara
  4. Use labels apropriados
  5. Marque pessoas se necessário

Boas práticas:

  • Descreva necessidade claramente
  • Dê exemplos do território
  • Explique benefícios reais
  • Considere regras de negócio

Para quê: Contribuições de código

Como criar:

  1. Faça fork ou branch do repositório
  2. Implemente mudanças
  3. Adicione testes (se código)
  4. Atualize documentação
  5. Crie Pull Request seguindo template

Boas práticas:

  • Descreva o que mudou e por quê
  • Referencie Issues relacionadas
  • Valide que build e testes passam
  • Pequeno é melhor (PRs focados são mais fáceis de revisar)

Para quê: Debates sobre funcionalidades, direção, arquitetura

Tipos:

  • Ideas - Ideias e propostas
  • Q&A - Perguntas e respostas
  • General - Discussões gerais

Quando usar:

  • Debater funcionalidade antes de implementar
  • Discutir direção do projeto
  • Perguntas que geram discussão útil
  • Ideias que precisam de validação

Princípios:

  • Todos podem revisar - não apenas mantenedores
  • Seja construtivo - critique código, não pessoas
  • Pergunte antes de exigir - esclareça intenções
  • Aprove para aprender - code review é oportunidade de aprendizado

Checklist de Revisão:

  • Código segue padrões do projeto?
  • Testes foram adicionados/atualizados?
  • Documentação foi atualizada?
  • Build e testes passam?
  • Mudanças são consistentes com arquitetura?
  • Valida necessidades territoriais (se funcionalidade)?

Processo de Contribuição

Checklist Geral

Antes de contribuir:

  • Li documentação relevante (onboarding do meu papel)
  • Entendi valores e princípios do projeto
  • Entrei no Discord (Sala Pública)
  • Explorei GitHub (Issues, Discussions)
  • Identifiquei algo para contribuir

Checklist específico:

  • Configurei Cursor e ambiente de desenvolvimento
  • Li .cursorrules e entendi padrões
  • Escolhi Issue ou tarefa para trabalhar
  • Criei branch seguindo convenções
  • Implementei seguindo padrões
  • Adicionei testes
  • Atualizei documentação
  • Validei build e testes localmente
  • Criei Pull Request com descrição clara

Checklist específico:

  • Observei necessidade no território
  • Documentei observação e necessidade
  • Validei necessidade com comunidade (se possível)
  • Propor funcionalidade (Issue no GitHub)
  • Discuti proposta no Discord (#propostas-funcionais)
  • Ajustei proposta baseado em feedback
  • Validei implementação quando pronta

Para Comunidade

Checklist específico:

  • Usei plataforma no território
  • Identifiquei bug, melhoria ou necessidade
  • Documentei clara e objetivamente
  • Criei Issue no GitHub ou postei no Discord
  • Participei de validação quando necessário
  • Testei soluções quando implementadas

Valores na Prática

No código:

  • Território é entidade base
  • Não contém lógica social
  • É geográfico e neutro

Na análise funcional:

  • Observação vem do território
  • Necessidades são territoriais
  • Soluções servem ao território

Na comunidade:

  • Uso é territorial
  • Feedback é do território
  • Melhorias servem territórios

No desenvolvimento:

  • Comunidades controlam sua presença digital
  • Não criamos dependências tecnológicas
  • Respeitamos decisões comunitárias

Na análise:

  • Propostas fortalecem autonomia
  • Não impomos soluções
  • Valorizamos controle local

Na comunidade:

  • Participação é voluntária
  • Decisões são comunitárias
  • Tecnologia serve, não controla

No desenvolvimento:

  • Código que serve, não extrai
  • Funcionalidades que facilitam, não substituem
  • Tecnologia que fortalece vínculos

Na análise:

  • Observamos impacto real
  • Propostas consideram vida no território
  • Avaliamos necessidade verdadeira

Na comunidade:

  • Uso que melhora vida local
  • Feedback sobre impacto real
  • Participação que transforma

No desenvolvimento:

  • Não replicamos padrões coloniais
  • Valorizamos saberes locais
  • Reconhecemos diferentes tipos de inteligência

Na análise:

  • Observação local, não externa
  • Propostas baseadas em contexto real
  • Validação com comunidades

Na comunidade:

  • Uso que valoriza saberes locais
  • Feedback que reconhece inteligência territorial
  • Participação que descoloniza

🎯 Resumo Rápido

Como Começar Agora

  1. Leia docs/ONBOARDING_PUBLICO.md
  2. Escolha seu caminho (Desenvolvedor ou Analista)
  3. Leia onboarding do seu caminho
  4. Entre no Discord (Sala Pública)
  5. Explore GitHub (Issues, Discussions)
  6. Escolha algo pequeno para começar
  7. Contribua e aprenda no processo

Princípios para Lembrar

  • ✅ Território como referência
  • ✅ Autonomia territorial
  • ✅ Tecnologia a serviço da vida
  • ✅ Decolonização digital
  • ✅ Respeito e transparência
  • ✅ Organização orgânica

Recursos Principais

Esta cartilha é um guia vivo - ela evolui conforme o projeto e o time evoluem.

O importante:

  • Começar - não precisa saber tudo
  • Contribuir - no seu ritmo e capacidade
  • Aprender - fazendo e colaborando
  • Respeitar - valores e outras pessoas

Bem-vindo ao Arah. Vamos construir juntos.

Última Atualização: 2025-01-20
Versão: 1.0

Perguntas? Entre no Discord ou abra uma Issue no GitHub!

← Voltar às Boas-VindasVer Todos os Docs →