Contribuindo

Importante

Antes de começar a trabalhar em novos recursos ou mudanças grandes, abra uma issue primeiro para discutir a proposta e obter aprovação. Não queremos que você perca tempo em trabalho que pode não alinhar com a direção do projeto ou não ser mesclado.

Visão geral

Este projeto é um monorepo com dois apps principais:

CLI: apps/cli
Site de documentação: apps/web

Setup

Pré-requisitos

Node.js (lts)
Bun (recomendado)
Git

Instalação

git clone https://github.com/albuquerquesz/kubo.git
cd kubojs
bun install

Desenvolver a CLI

cd apps/cli
# optional global link for testing anywhere
bun link
# run in watch mode (runs tsdown build in watch mode)
bun dev

Agora vá para qualquer outro lugar no sistema (por exemplo uma pasta de teste) e rode:

kubojs

Isso executa a CLI instalada localmente.

Desenvolver a documentação

# from repo root
bun install
cd packages/backend
bun dev:setup  # you can choose local development too in prompts

Copie a URL do Convex de packages/backend/.env.local para apps/web/.env:

NEXT_PUBLIC_CONVEX_URL=http://127.0.0.1:3210/
NEXT_PUBLIC_CONVEX_SITE_URL=http://127.0.0.1:3211/

Configurar autenticação Google

O dashboard usa Better Auth no deployment Convex. Configure os valores abaixo no diretório packages/backend; mantenha os valores reais fora do repositório:

bunx convex env set SITE_URL http://localhost:3333
bunx convex env set BETTER_AUTH_SECRET "<segredo-aleatorio-com-pelo-menos-32-bytes>"
bunx convex env set GOOGLE_CLIENT_ID "<google-client-id>"
bunx convex env set GOOGLE_CLIENT_SECRET "<google-client-secret>"

No cliente OAuth do Google, cadastre http://localhost:3333 como origem autorizada e http://localhost:3333/api/auth/callback/google como URI de redirecionamento. Em produção, use https://kubojs.dev e https://kubojs.dev/api/auth/callback/google, respectivamente.

Agora rode bun dev na raiz. Ele vai reclamar do token do GitHub, então rode isto em packages/backend:

npx convex env set GITHUB_ACCESS_TOKEN=xxxxx
npx convex env set GITHUB_WEBHOOK_SECRET=xxxxx

Fluxo de contribuição

Abra uma issue/discussão antes de começar trabalho grande
Faça fork do repositório
Crie uma branch de feature
Faça mudanças seguindo o estilo de código existente
Atualize a documentação conforme necessário
Teste e formate

# CLI
cd apps/cli && bun dev
cd apps/cli && bun run test

# Web
bun dev

# Lint + format checks
bun check

Commit e push

git add .
git commit -m "feat(web): ..." # or fix(cli): ...
git push origin <your-branch>

Abra um Pull Request e vincule issues relacionadas

Convenções de commit

Use mensagens de commit convencionais com o escopo apropriado:

feat(cli): add new CLI feature
fix(cli): fix CLI bug
feat(web): add new web feature
fix(web): fix web bug
chore(web): update dependencies
docs: update documentation

Ajuda

Issues e Discussions no GitHub
Discord: https://discord.gg/ZYsbjpDaM5

Veja o guia completo de contribuição no repositório: .github/CONTRIBUTING.md.

Contribuindo

Nesta página