# Projetos open source e contribuição externa Torne um projeto público para que qualquer pessoa leia os boards, os cards e a wiki, mesmo sem conta. Pessoas de fora podem comentar, propor cards e pedir para trabalhar em cards abertos para contribuição. A equipe decide o que entra pela triagem e modera a conversa. Este guia é para quem mantém um projeto aberto e para quem quer contribuir com um. > Versão em Markdown puro deste guia: [https://app.krakendock.com/docs/open-source.md?lang=pt-BR](https://app.krakendock.com/docs/open-source.md?lang=pt-BR). Use-a para colar num assistente de IA ou na documentação interna do seu time. ## Visão geral | Peça | Para quem | Onde | | --------------------------- | ------------------------- | ------------------------------------------- | | Visibilidade e contribuição | quem administra o projeto | Configurações do projeto → **Visibilidade** | | Visão geral e README | todo mundo | `https://app.krakendock.com/HANDLE/KEY` | | Página Contribuir | quem quer ajudar | `https://app.krakendock.com/HANDLE/KEY/contribute` | | Triagem | mantenedores | `https://app.krakendock.com/HANDLE/KEY/triage` | | Moderação | quem administra o projeto | Configurações do projeto → **Moderação** | | Explorar | todo mundo | [https://app.krakendock.com/explore](https://app.krakendock.com/explore) | | Perfil público | cada pessoa e organização | `https://app.krakendock.com/HANDLE` | O caminho de uma contribuição: 1. Alguém encontra o projeto no Explorar ou por um link e lê a visão geral. 2. Na página **Contribuir**, lê o guia de contribuição e escolhe um card aberto para contribuição, ou propõe um card novo. 3. A proposta ou o pedido cai na **Triagem**. Um mantenedor aceita, pede mais informações ou recusa. 4. Aprovado o pedido, o card passa a ser da pessoa, que pode editá-lo e movê-lo no board. ## Tornar um projeto público 1. Abra o projeto e vá em **Configurações → Visibilidade**. 2. Em **Quem pode ver este projeto**, escolha **Público**. 3. Ligue o que o projeto aceita de quem não é membro (veja a tabela abaixo). 4. Clique em **Salvar alterações** e confirme em **Tornar público**. Só o dono de um projeto pessoal muda a visibilidade. Num projeto de organização, é preciso a permissão de gerenciar projetos da organização. As outras opções da página pedem a permissão de gerenciar o projeto. | Opção | O que faz | | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | **Permitir comentários de não-membros** | quem tem conta com e-mail verificado comenta nos cards | | **Permitir sugestões de cards de não-membros** | quem tem conta com e-mail verificado propõe cards (tipo, título e descrição) | | **Propostas externas vão para a triagem** | ligada por padrão: as propostas esperam um mantenedor na [Triagem](#triagem). Desligada, entram direto na board | | **Guia de contribuição** | uma página da wiki mostrada na página Contribuir e no formulário de proposta. Veja [Guia de contribuição](#guia-de-contribuicao) | Essas opções só valem enquanto o projeto é público. Os pedidos para trabalhar num card não dependem delas: valem em todo projeto público, para os cards marcados como abertos para contribuição. Preencha também, em **Configurações → Geral**, a **Descrição**, o **Site** e os **Tópicos** (até 10). Eles aparecem na visão geral e ajudam a encontrar o projeto no Explorar. ### O que um visitante vê Sem login, um visitante lê: - a visão geral do projeto, com README, números e atividade; - os boards, o backlog, as sprints e os cards, inclusive os arquivados; - os comentários e os anexos; - a wiki, com o histórico de versões; - a lista de membros, sem e-mails. As mudanças aparecem em tempo real para o visitante também. Um projeto privado responde "não encontrado" para quem não é membro: o link não revela que ele existe. ### O que continua privado - reuniões e transcrições; - a IA do projeto (gerações e créditos); - **Colaboradores e times**, que mostra e-mails; - a atividade de pull requests do GitHub na visão geral; - o board **Helpdesk** e os seus chamados (veja o [guia do Helpdesk](https://app.krakendock.com/docs/helpdesk)); - as propostas pendentes e recusadas, que só o autor e os mantenedores veem; - as denúncias e a lista de usuários bloqueados. ### Voltar a ser privado Escolha **Privado** e confirme em **Tornar privado**. - As estrelas de quem não é membro são removidas. - As pessoas do projeto passam a contar no limite do plano (veja a próxima seção). Se o plano não comportar, a mudança é recusada. - Os comentários, as propostas e os pedidos de quem é de fora param de ser aceitos. ## Projetos públicos e planos Projetos públicos são gratuitos em qualquer plano: - O número de projetos não tem limite, públicos ou privados. - Quem participa só de projetos públicos de uma conta pessoal não conta no limite de pessoas em projetos privados. - Uma organização só com projetos públicos tem membros ilimitados. Os membros passam a contar assim que a organização tiver um projeto privado. Os limites que não dependem da visibilidade continuam valendo, como o número de campos customizados por projeto, os formulários e chamados do Helpdesk e o armazenamento de anexos da conta. Veja os planos em [https://app.krakendock.com/pricing](https://app.krakendock.com/pricing). ## Visão geral e README O endereço do projeto (`https://app.krakendock.com/HANDLE/KEY`) abre a visão geral, para membros e visitantes: - o cabeçalho, com o selo **Público** ou **Privado**, o botão **Favoritar**, **Abrir board** e, para quem é de fora, **Propor card**; - o README; - o bloco **Sobre**: descrição, site, tópicos, cards abertos e concluídos, membros, páginas da wiki, tipos de card, boards com progresso e a sprint ativa; - o gráfico de **Atividade** do último ano e o de **Concluídos por semana** nas últimas 12 semanas; - a **Atividade recente**: cards criados e concluídos, comentários, páginas da wiki e sprints. Um visitante vê também o aviso **Você está visitando este projeto**, que diz o que ele pode fazer ali e pede login ou a confirmação do e-mail quando falta. ### README O README é uma página da wiki do projeto. Escolha qual em **Configurações → README**, no campo **Página do README**. Ele tem o mesmo editor, histórico e permissões da wiki. Sem README, quem administra o projeto vê na visão geral o atalho **Escolher página**. ### Estrelas Qualquer pessoa logada pode dar estrela (**Favoritar**) num projeto que consegue ver. Os projetos com estrela aparecem na seção **Favoritos** da barra lateral, no painel inicial e na aba **Estrelas** do perfil. O Explorar ordena projetos e organizações por estrelas. ## Explorar O [Explorar](https://app.krakendock.com/explore) mostra o que é público no KrakenDock, sem precisar de conta. Ele tem as abas **Visão geral**, **Projetos**, **Pessoas**, **Ranking** e **Organizações**. ### Projetos A aba **Visão geral** reúne **Projetos em alta** (os de atividade mais recente), **Projetos novos**, **Pessoas em destaque**, **Tópicos populares** e **Aceitam contribuições**. A aba **Projetos** lista os projetos públicos com filtros: - busca por nome, chave ou descrição; - até 5 tópicos, todos exigidos; - **Metodologia**: Scrum ou Kanban; - **Aceita contribuições**: **Aceita cards**, **Aceita comentários** ou **Procurando contribuidores** (com cards abertos para contribuição); - **Ordenar por**: **Relevância**, **Atividade recente**, **Mais novos**, **Mais estrelas** ou **Nome**. Os números de cada projeto (cards abertos e concluídos, membros e última atividade) são atualizados a cada 5 minutos. ### Pessoas e organizações - **Pessoas** lista os perfis verificados que escolheram aparecer na busca. Ordene por **Mais contribuições**, **Atividade recente**, **Mais novos** ou **Mais projetos públicos**. - **Organizações** lista as organizações com pelo menos um projeto público. Ordene por **Mais estrelas**, **Mais projetos** ou **Atividade recente**. ### Ranking O [Ranking](https://app.krakendock.com/explore/ranking) mostra quem mais contribui em projetos públicos. Escolha o **Período** (**7 dias**, **30 dias** ou **365 dias**) e filtre por **Tópico**, **Organização** ou **Tipo de contribuição**. Logado, você vê **Sua posição**. A pontuação, em linhas gerais: | Tipo | Peso | | ---------------- | ---- | | Cards concluídos | 5 | | PRs mergeados | 5 | | Cards criados | 2 | | Commits | 1 | | Edições na wiki | 1 | | Comentários | 1 | - Os pontos contam por pessoa, projeto, dia (UTC) e tipo. Cada tipo tem um teto por dia e projeto: até o teto vale o peso cheio, do teto ao dobro vale metade, e acima disso não pontua. Alguns tipos têm também um teto diário somando todos os projetos. - Um projeto só pontua para você se outra pessoa com e-mail verificado também contribuiu nele no mesmo período. - Só contam projetos públicos, e só aparecem perfis verificados que estão no diretório de pessoas. - O ranking é atualizado a cada 15 minutos. A tabela completa, com os tetos, está em **Como funciona a pontuação**, na própria página. ## Perfis públicos Cada conta tem um perfil em `https://app.krakendock.com/HANDLE`, aberto a qualquer pessoa pelo link. O perfil tem as abas **Visão geral**, **Projetos** e **Estrelas** e mostra: - nome, foto, bio, site, localização e empresa; - o README do perfil, em Markdown; - os projetos **Fixados** (até 6 projetos públicos); - o calendário de contribuições do último ano e a sequência de dias seguidos; - a **Atividade de contribuição** do mês e a lista **Contribui em**; - as **Conquistas**; - as **Organizações** que você escolheu mostrar. Configure tudo em [Configurações → Perfil](https://app.krakendock.com/settings/profile): - **Aparecer na busca de pessoas e em rankings**: desligado, o perfil continua acessível pelo link, mas sai da aba Pessoas, do ranking e dos buscadores. - **Incluir contribuições privadas no meu perfil**: mostra só a quantidade, sem o nome dos projetos. - **Projetos fixados** e **Organizações no perfil**: só aparecem organizações com pelo menos um projeto público. ### Conquistas As conquistas são permanentes e chegam como notificação: - **Top 10 da semana** e **Top 10 do mês**, pela posição no ranking de uma semana ou de um mês já encerrados; - **7 dias seguidos**, **30 dias seguidos** e **100 dias seguidos** de contribuição; - **Primeira contribuição externa**, no projeto de outra pessoa; - **10 cards concluídos**, **100 cards concluídos** e **1.000 cards concluídos**. Fora do diretório de pessoas, você não ganha as conquistas de ranking. ## Receber contribuições ### Comentários de quem não é membro Com **Permitir comentários de não-membros** ligado, quem tem conta com e-mail verificado comenta nos cards. Um visitante sem login vê o convite para entrar. Quem não confirmou o e-mail vê o aviso para verificar. ### Propostas de card Com **Permitir sugestões de cards de não-membros** ligado, quem é de fora vê o botão **Propor card** na visão geral e na página Contribuir, e **Sugerir card** no board e na lista de cards. - A proposta tem só **Tipo**, **Título** e **Descrição**. Para bug e história, a descrição já vem com um modelo. - Antes do formulário aparece o guia de contribuição (**Antes de propor**). Enquanto o título é digitado, o bloco **Pode já existir** sugere cards parecidos. - O autor pode editar o tipo, o título e a descrição depois. - O card leva o selo **Contribuição pública**. Com a triagem ligada, a proposta fica fora da board até alguém aceitar. Enquanto isso, ela não aparece no feed de atividade, não dispara webhooks e só é vista pelo autor e pelos mantenedores. Com a triagem desligada, entra direto na board. ### Guia de contribuição Escreva numa página da wiki as regras do projeto: como propor, como trabalhar num card e o que esperar da revisão. Depois escolha a página em **Configurações → Visibilidade → Guia de contribuição**. O guia aparece no topo da página **Contribuir** e antes do formulário de proposta. Sem guia, quem administra o projeto vê na página Contribuir o atalho **Escolher guia**. ### Página Contribuir Todo projeto público tem a seção **Contribuir** na barra lateral, em `https://app.krakendock.com/HANDLE/KEY/contribute`, aberta também a visitantes. Ela mostra: - o guia de contribuição; - os **Cards abertos para contribuição**, dos mais novos para os mais antigos, com o filtro **Dificuldade**; - o botão **Propor card**, se o projeto aceita propostas. Um card só aparece ali enquanto está aberto para contribuição, sem responsável, fora das colunas de concluídos e sem estar arquivado. ### Cards abertos para contribuição Para abrir um card a quem é de fora, edite o card e preencha: - **Contribuição**: **Ajuda desejada** ou **Boa primeira issue**. **Nenhuma** fecha o card de novo. - **Dificuldade**: **Fácil**, **Média** ou **Difícil** (opcional). Quem tem permissão de editar cards ou de fazer triagem marca esses campos. ### Pedidos para trabalhar em um card Num card aberto para contribuição, quem é de fora vê **Aberto para contribuição** e o botão **Quero trabalhar nisso**. 1. A pessoa envia o pedido, com uma **Mensagem (opcional)** de até 500 caracteres. 2. Os mantenedores recebem uma notificação, e o pedido entra na aba **Pedidos** da [Triagem](#triagem). 3. Se aprovarem, o card é atribuído à pessoa. Quem ainda não tinha acesso ao projeto entra como colaborador com o papel Contribuidor (`Contributor` na lista de acesso), que edita e move só os próprios cards. 4. Se recusarem, o motivo vai na notificação. Regras: - Cada pessoa tem no máximo 3 pedidos abertos, somando todos os projetos. - Um card aprovado que fica 14 dias sem atividade volta a ficar livre, e o pedido passa a **Expirados**. - Num projeto de organização, só membros da organização podem ter o pedido aprovado. - Quem já é membro do projeto não pede: usa **Atribuir a mim**. ## Triagem A **Triagem** fica na barra lateral do projeto, com o número de propostas pendentes, para quem pode fazer triagem. Atalho: `g` e depois `t`. Ela tem três abas: **Propostas**, **Denúncias** e **Pedidos**. ### Propostas Filtre por **Pendentes**, **Aguardando informação** ou **Recusadas**. As mais antigas aparecem primeiro. Use `j` e `k` para passar de uma proposta para outra. | Ação | O que acontece | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | **Aceitar** | escolha a **Board** e a **Coluna**: a proposta vira um card comum do projeto | | **Pedir informações** | sua **Mensagem** (Markdown, até 5.000 caracteres) vira um comentário no card, e a proposta passa a **Aguardando informação** | | **Recusar** | escolha o **Motivo**: **Não vamos fazer**, **Duplicata**, **Inválida** ou **Spam**. Numa duplicata, indique o **Card original** | O autor é avisado de cada decisão. Ele responde a um pedido de informações nos comentários do card, e a proposta continua em **Aguardando informação** até você aceitar ou recusar. Uma proposta recusada não entra na board e fica no filtro **Recusadas**. O autor continua vendo o card, com o motivo. No menu do card, **Recusar como spam** faz o mesmo que recusar com o motivo Spam. ### Pedidos Filtre por **Abertos**, **Aprovados**, **Recusados** ou **Expirados**. Em cada pedido, use **Aprovar** ou **Recusar**. Na recusa, o **Motivo (opcional)** tem até 500 caracteres. Na página do card, os mantenedores também veem os pedidos daquele card. ## Moderação Num projeto público, quem modera tem estas ferramentas. ### Comentários e conversas No menu de um comentário: - **Ocultar**, com um motivo: **Spam**, **Fora do assunto**, **Abusivo** ou **Outro**. Os membros veem o comentário recolhido, e quem não é membro deixa de vê-lo. **Mostrar a todos** desfaz. - **Denunciar**, para quem participa do projeto sem moderar (quem modera oculta ou recusa). - **Bloquear**, seguido do nome do autor. No menu do card, **Travar conversa** impede quem não é membro de comentar. **Destravar conversa** desfaz. Os comentários e os cards de quem é de fora podem ser excluídos por quem tem a permissão de excluir cards. ### Denúncias Qualquer pessoa logada que vê o projeto, e não modera, pode denunciar um card (**Denunciar card**) ou um comentário, com um motivo e **Detalhes (opcional)**. Quem foi denunciado não fica sabendo quem denunciou. As denúncias ficam na aba **Denúncias** da Triagem, das mais antigas para as mais novas. Filtre por **Abertas**, **Resolvidas**, **Dispensadas** ou **Todas** e use **Resolver**, **Dispensar** ou **Bloquear autor**. ### Bloquear usuários Um usuário bloqueado continua lendo o projeto, mas não comenta, não propõe cards, não denuncia e não pede cards. Os pedidos abertos dele são recusados na hora. - Bloqueie pelo menu de um comentário da pessoa ou por **Bloquear autor**, numa denúncia. - A lista fica em **Configurações → Moderação → Usuários bloqueados**, com o botão **Desbloquear**. A seção **Moderação** só aparece em projetos públicos. - Só quem não é membro pode ser bloqueado. ## Permissões | Ação | Quem pode | | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | Tornar público ou privado | o dono do projeto pessoal; numa organização, quem gerencia projetos (`org:projects:manage`) | | Ligar comentários, propostas e triagem, escolher README e guia | quem gerencia o projeto (`project:manage`) | | Marcar cards para contribuição | `card:write` ou `card:triage` | | Usar a Triagem (propostas, pedidos e denúncias) e ocultar comentários | `card:triage` ou `project:manage` | | Travar e destravar conversas | `card:write` ou `card:triage` | | Bloquear e desbloquear usuários | `project:manage` | | Excluir cards e comentários de outras pessoas | `card:delete` | | Comentar, propor, pedir um card e denunciar sendo de fora | conta com e-mail verificado, sem bloqueio no projeto | Os papéis de sistema do projeto, escolhidos em **Configurações → Colaboradores e times**: | Papel | Para quem | O que faz | | ------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------ | | `Admin` | mantenedores | tudo, inclusive `card:triage` | | `Triage` | quem ajuda a triar sem administrar | Triagem, denúncias e edição de cards. Não exclui cards, não mexe em membros, sprints, wiki nem configurações | | `Contributor` | quem teve um pedido aprovado | lê o projeto, comenta, propõe cards e edita ou move só os cards atribuídos a ele ou criados por ele | ## Perguntas frequentes ### Um visitante precisa de conta para ler o projeto? Não. Qualquer pessoa lê um projeto público sem login. A conta, com e-mail verificado, só é necessária para comentar, propor, pedir um card, denunciar e dar estrela. ### Por que uma pessoa de fora não consegue comentar? Confira, nesta ordem: se ela está logada e com o e-mail verificado; se **Permitir comentários de não-membros** está ligado; se a conversa do card está travada; e se ela está bloqueada em **Configurações → Moderação**. ### Quem vê uma proposta pendente? Só o autor e quem pode fazer triagem. Para os outros, o card não existe até ser aceito. ### Por que um card sumiu da página Contribuir? O card saiu da lista porque ganhou um responsável, foi concluído ou arquivado, ou teve a **Contribuição** voltada para **Nenhuma**. ### Aprovei um pedido e apareceu "Esta pessoa não é membro da organização" Num projeto de organização, o card só pode ser atribuído a membros da organização. Convide a pessoa para a organização antes de aprovar, ou recuse o pedido. ### Por que meu projeto não aparece no Explorar? Confira se ele está **Público**. Os números do projeto no Explorar são atualizados a cada 5 minutos. Adicione **Tópicos** em **Configurações → Geral** para o projeto aparecer nas buscas por tema. ### Por que não apareço no ranking? Confira se o seu e-mail está verificado e se **Aparecer na busca de pessoas e em rankings** está ligado no seu perfil. Só contam projetos públicos com outra pessoa contribuindo no mesmo período, e o ranking é atualizado a cada 15 minutos. ### Posso trazer as issues de um repositório público do GitHub? Sim. Importe as issues e mantenha os cards sincronizados com elas. Veja o [guia do GitHub](https://app.krakendock.com/docs/github). ## Veja também - [Primeiros passos](https://app.krakendock.com/docs/getting-started) - [Boards e cards](https://app.krakendock.com/docs/boards) - [GitHub](https://app.krakendock.com/docs/github) - [Webhooks](https://app.krakendock.com/docs/webhooks) - [Helpdesk](https://app.krakendock.com/docs/helpdesk)