Como contribuir

From DragonMineZ Wiki
EnglishEspañolPortuguês
This page is a translated version of the page Contributing and the translation is 100% complete.

Como contribuir explica como ajudar o DragonMineZ: reportar bugs, testar versões, sugerir recursos, melhorar a documentação ou trabalhar no código. Seja o que for que você queira fazer, a equipe terá prazer em colaborar com você. Siga estas diretrizes para que o processo seja tranquilo para todos os colaboradores. Se quiser fazer uma doação ao projeto, veja Apoiar o projeto no Patreon.

Primeiros passos

  1. Leia o Código de Conduta. Ao contribuir, você concorda em respeitar o Código de Conduta.
  2. Confira as issues existentes. Veja as issues para saber se alguém já reportou seu problema ou propôs sua ideia.
  3. Faça um fork do repositório e clone seu fork no seu ambiente local para testar e desenvolver (veja abaixo).
  4. Prepare seu ambiente com as ferramentas listadas abaixo.

Para clonar seu fork: 

git clone https://github.com/your-username/DragonMineZ.git

Verifique se você tem estas ferramentas instaladas:

  • Java Development Kit (JDK) 17 (o build usa uma toolchain do Java 17)
  • Git
  • Uma IDE com suporte a Gradle (IntelliJ IDEA ou Eclipse)

Você não precisa instalar o Gradle nem o Forge por conta própria: o repositório inclui o wrapper do Gradle (gradlew / gradlew.bat), que baixa o Gradle, o Minecraft Forge (1.20.1-47.4.10) e todas as dependências no primeiro build.

Se você não vai fazer um fork do repositório nem criar um addon, pode pular o passo 3. Para desenvolver addons, veja Primeiros passos com addons.

Compilar e executar

Execute estes comandos a partir da raiz do repositório (./gradlew no Linux e no macOS, .\gradlew.bat no Windows):

Comando O que faz
./gradlew build Build completo. O jar distribuível é build/libs/dragonminez-<version>.jar (ele inclui as bibliotecas de banco de dados); o jar -slim não é feito para ser distribuído.
./gradlew runClient Inicia um cliente de desenvolvimento (diretório de trabalho run/).
./gradlew runServer Inicia um servidor dedicado de desenvolvimento (diretório de trabalho run/).
./gradlew runData Executa a geração de dados (diretório de trabalho run-data/) e grava em src/generated/resources/. Execute depois de alterar os providers de datagen e revise o diff gerado.
  • Não há uma suíte de testes automatizados. Valide sua mudança com build e, quando ela afetar a jogabilidade, testando-a no runClient e/ou no runServer.
  • Mods de desenvolvimento só de cliente (JEI runtime, shaders etc.) são adicionados apenas ao runClient. Mantenha assim, para que eles não vazem para os dados gerados nem para o servidor dedicado.
  • A otimização de recursos (PackSquash) roda no CI e fica desativada por padrão nos builds locais. Force-a com -PoptimizeResources=true ou -PoptimizeResources=false.

Traduções

  • src/main/resources/assets/dragonminez/lang/en_us.json é o arquivo de idioma de origem. Adicione nele uma entrada para cada texto novo que os jogadores possam ver e mantenha estáveis as chaves existentes.
  • Os outros idiomas são traduzidos pela comunidade no Crowdin. O arquivo em inglês é enviado ao Crowdin automaticamente quando muda na main.
  • Antes de abrir um pull request, verifique se todos os arquivos de idioma são JSON válido com scripts/check_lang.sh (ele precisa do jq).

Como contribuir

Reportar bugs

Se você encontrou um bug, abra um relatório de bug e inclua o máximo de detalhes possível:

  • Uma descrição clara do problema
  • Passos para reproduzi-lo
  • Resultado esperado e resultado real
  • Capturas de tela, logs ou relatórios de crash, se houver

Testar o jogo

Qualquer pessoa pode testar as versões públicas e compartilhar o que encontrar com a equipe: bugs, exploits, problemas de balanceamento, crashes ou qualquer outra coisa que pareça estranha. Você não precisa ser desenvolvedor nem abrir um pull request para ajudar dessa forma.

  • Teste apenas versões públicas. Não teste versões internas ou não lançadas, a menos que tenha recebido acesso explícito.
  • Compartilhe o que encontrar em um relatório de bug ou no Discord.
  • Se o que você encontrar for uma vulnerabilidade de segurança (por exemplo, algo que possa ser explorado para prejudicar outros jogadores ou servidores), siga a Política de segurança em vez de abrir uma issue pública.

Sugerir recursos

Tem uma ótima ideia? Abra uma sugestão de recurso e inclua:

  • Uma explicação clara e concisa do recurso
  • Seus possíveis benefícios e impacto
  • Alternativas ou conceitos relacionados

Você também pode sugerir recursos no servidor do Discord.

Enviar pull requests

Passo 1: Crie uma branch. A main contém a linha estável atual; a próxima versão é desenvolvida na sua própria branch de versão (por exemplo, v2.2). Baseie sua branch naquela a que sua mudança se destina; se não tiver certeza, pergunte no Discord. Use um nome de branch descritivo: 

git checkout -b fix/short-description

Passo 2: Faça suas mudanças.

  • Escreva código limpo e conciso.
  • Teste suas mudanças localmente para garantir que funcionam como esperado.
  • Siga as convenções e padrões de código do projeto.

Passo 3: Faça commit das suas mudanças com uma mensagem de commit significativa: 

git commit -m "Fix: Resolved issue with XYZ feature"

Passo 4: Envie suas mudanças (push). 

git push origin fix/short-description

Passo 5: Abra um pull request. Vá ao seu fork no GitHub e envie um pull request.

  • Descreva as mudanças e vincule as issues relacionadas.
  • Esteja pronto para discutir e revisar seu código com base no feedback.
  • Todo pull request é compilado automaticamente pelo workflow Compile Check (./gradlew build). Se falhar, seu pull request não será mesclado. As execuções de workflow de quem contribui pela primeira vez podem precisar da aprovação de um mantenedor antes de começar.

Verificações automáticas

Workflow Quando roda O que faz
Compile Check Todo pull request, e pushes para qualquer branch exceto main que mexam em código, recursos ou arquivos do Gradle Executa ./gradlew build
Java CI Pull requests e pushes para a main que mexam em Java ou no build.gradle.kts Executa ./gradlew build e envia o grafo de dependências
Crowdin Check & Upload Pushes para a main que mexam na pasta lang, a cada 2 dias ou manualmente Valida os arquivos de idioma com scripts/check_lang.sh e envia o en_us.json ao Crowdin
CodeQL Diariamente Análise de segurança do código Java e dos workflows

Os mantenedores publicam as versões no Modrinth e no CurseForge a partir da main com seus workflows de lançamento.

Diretrizes para colaboradores

  1. Padrões de código
    • Use nomes descritivos para variáveis e métodos.
    • Formate o código de forma consistente (indentação, espaçamento etc.).
    • Escreva comentários para a lógica complexa.
  2. Documentação
    • Atualize ou adicione documentação para recursos novos ou alterados.
    • Garanta que esta wiki reflita as mudanças importantes.
  3. Testes
    • Teste a fundo nos cenários relevantes, incluindo um servidor dedicado (runServer) quando sua mudança mexer em classes do cliente, rede ou lógica do servidor.
    • Corrija qualquer problema de linting ou de compilação antes de enviar seu pull request.
  4. Compatibilidade
    • Muitos sistemas leem JSON que jogadores, donos de servidores e autores de addons editam (configurações, missões, desejos, pacotes de Esferas do Dragão). Não renomeie nem remova chaves de configuração, campos JSON, chaves de salvamento NBT ou nomes de registro sem discutir antes: mundos e configurações antigos precisam continuar carregando.
    • Os pacotes de rede são identificados pela ordem de registro: adicione pacotes novos no final de NetworkHandler.register(), nunca no meio.
    • Valide no servidor tudo o que um cliente envia; nunca confie no cliente para estatísticas, desbloqueios, missões, desejos ou progresso.
  5. Documentação do projeto
    • CLAUDE.md e a pasta AI/ (Agents.md, Context.md, Memory.md, QuestAddonAPI.md) descrevem em detalhes a arquitetura, os sistemas de dados, o build e a automação de lançamentos. Foram escritos para assistentes de programação com IA, mas são igualmente úteis para colaboradores humanos: leia AI/Context.md antes de mudanças maiores.

Comunidade

Entre no servidor do Discord para conversas em tempo real.

Apoiar o projeto no Patreon

O DragonMineZ é um projeto movido pela comunidade, e seu apoio ajuda a equipe a continuar melhorando o mod e lançando novos recursos. Considere se tornar apoiador no Patreon para apoiar o desenvolvimento e a manutenção do mod. Os apoiadores recebem benefícios exclusivos, como:

  • Acesso antecipado a novos recursos
  • Novidades dos bastidores
  • Reconhecimento na comunidade

Toda contribuição, por menor que seja, ajuda o DragonMineZ a continuar melhorando.

Licença

Ao contribuir, você concorda que suas contribuições serão licenciadas sob a mesma licença que rege o projeto.

Obrigado

A equipe está animada para ver suas contribuições e ideias. Se tiver alguma dúvida ou precisar de ajuda, fale com a equipe.

Retrieved from "https://wiki.dragonminez.com/pt/wiki/Contributing?oldid=19268"