> For the complete documentation index, see [llms.txt](https://docs.ipcheck.ing/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ipcheck.ing/developer/pt-br/contributing/how-to-contribute.md). # Como Contribuir Disciplina de branches, diretrizes de pull request e estilo de mensagens de commit. O MyIP é open source e acolhe contribuições externas. Esta página descreve o fluxo que o projeto realmente usa, da primeira issue até um pull request mesclado. Tudo aqui espelha [`CONTRIBUTING.md`](https://github.com/jason5ng32/MyIP/blob/main/CONTRIBUTING.md) e `AGENTS.md` no repositório. O projeto também tem um [Código de Conduta](https://github.com/jason5ng32/MyIP/blob/main/CODE_OF_CONDUCT.md) (Contributor Covenant). Ao participar, você concorda em cumpri-lo. ## Antes de escrever código Abra uma issue primeiro para qualquer coisa não trivial. Uma breve discussão inicial custa menos do que um pull request rejeitado. Novos recursos, mudanças de comportamento, novas dependências e refatorações se enquadram nisso. Correções pequenas e óbvias — um erro de digitação, um link quebrado, um bug de uma linha — podem ir direto para um pull request. Se você é novo no projeto, procure issues rotuladas `boa issue para começar`. ## O fluxo {% stepper %} {% step %} ### Abra uma issue Descreva a mudança e por que ela é necessária. Espere um mantenedor confirmar a direção antes de investir tempo. Veja [Reportando problemas](/developer/pt-br/contributing/reporting-issues.md). {% endstep %} {% step %} ### Faça fork e crie branch a partir de `dev` Faça um fork do repositório e então crie sua branch a partir de **`dev`** — não `main`. ```bash git clone https://github.com//MyIP.git cd MyIP git checkout dev git checkout -b fix/mac-input-validation ``` {% endstep %} {% step %} ### Configure e compile Instale com pnpm e faça o app funcionar. Veja [Ambiente de desenvolvimento](/developer/pt-br/development/dev-environment.md). ```bash pnpm install pnpm dev ``` {% endstep %} {% step %} ### Faça a mudança Uma preocupação por branch. Siga as [Convenções de Codificação](/developer/pt-br/development/coding-conventions.md), e adicione ou atualize testes em `tests/` para qualquer lógica não visual que você alterar. {% endstep %} {% step %} ### Execute `pnpm check` `pnpm check` executa a suíte de testes e uma build de produção. Ela deve estar verde antes de você fazer push. ```bash pnpm check ``` {% endstep %} {% step %} ### Faça rebase sobre a versão mais recente `dev` Faça rebase — não faça merge `dev` na sua branch. Isso mantém o histórico legível. ```bash git fetch upstream git rebase upstream/dev ``` {% endstep %} {% step %} ### Abra a pull request contra `dev` Preencha o template do pull request: um resumo, o tipo de mudança e a checklist. Vincule a issue que ele corrige. {% endstep %} {% endstepper %} ## Por que os pull requests têm como destino `dev` {% hint style="warning" %} **Nunca abra um pull request contra `main`.** `main` recebe apenas merges de release de `dev` branch. Um pull request com destino a `main` será solicitado a mudar o destino. {% endhint %} O repositório está `dev` em, `dev` fora. Todo o trabalho chega em `dev` primeiro; `main` segue apenas por um `dev` → `main` merge de release. Isso mantém `main` alinhado com o que é lançado, e isso significa que toda mudança é exercitada em `dev` primeiro. ## Regras de pull request * **Destino `dev`.** Veja acima. * **Uma preocupação por pull request.** Não agrupe um recurso com um ajuste de ambiente de desenvolvimento sem relação. Separe-os. * **Faça rebase antes de enviar**, para que sua branch fique sobre a versão atual de `dev`. * **Descreva o que mudou e por quê.** Os revisores não deveriam precisar deduzir a intenção a partir do diff. * **`pnpm check` verde.** A CI executa `pnpm test` e `pnpm run build` no Node 24 para cada pull request para `dev` ou `main`; uma execução em vermelho bloqueia o merge. ## Estilo de mensagem de commit Os commits usam um `Type(scope):` prefixo, retirado do próprio histórico do projeto. O escopo é opcional e nomeia a área afetada (`ui`, `api`, um nome de recurso, um nome de módulo). | Prefixo | Usado para | Exemplo real do repositório | | --------------- | -------------------------------------------- | --------------------------------------------------------------------------------------------------- | | `Feat(...)` | Nova funcionalidade | `Feat(ui): seletor de país do Globalping compartilhado para MTR / latência / censura` | | `Fix(...)` | Correção de bug | `Fix(ui): alinhar a validação da entrada de MAC com o backend (exatamente 12 dígitos hexadecimais)` | | `Refactor(...)` | Reestruturação, sem mudança de comportamento | `Refactor(country-name): substituir tabela mantida manualmente por Intl.DisplayNames` | | `Perf(...)` | Trabalho de desempenho | `Perf(frontend): carregar de forma preguiçosa apenas o locale ativo da UI` | | `Style(...)` | Acabamento visual ou de texto | `Style(toggle): estado pressionado de alto contraste para primitivos de toggle` | | `Chore(...)` | Ferramentas, dependências, manutenção | `Chore: simplificar o mapeamento de caminhos do jsconfig` | Escreva as mensagens em inglês, no imperativo, e mantenha uma preocupação por commit. ## A regra de i18n Os idiomas que a UI oferece são um único registro central, `common/locale-registry.js`. Cada um carrega uma `status`: um(a) **`full`** locale é um em que toda alteração de texto precisa ser aplicada, um(a) **`beta`** pode-se publicar um pacote parcial e recorrer ao inglês. O próprio registro é a lista atual de qual locale tem qual status. {% hint style="danger" %} Qualquer mudança que exponha texto visível ao usuário deve atualizar **cada `full` arquivo de locale no mesmo commit** — incluindo os `frontend/data/changelog.json` itens. `tests/locale-packs.test.js` e `tests/changelog.test.js` impõem isso, então uma tradução parcial falha `pnpm check`. {% endhint %} Se você não conseguir escrever um locale com segurança, ainda assim adicione a chave em todos os arquivos com a sua melhor tentativa, e diga isso no pull request. Detalhes: [i18n](/developer/pt-br/development/i18n.md). **Adicionar um novo idioma é um trabalho diferente, muito menor** — apenas no front-end, preparado por `pnpm i18n-new `, e uma tradução parcial é um primeiro PR bem-vindo. Veja [Traduzindo o MyIP](/developer/pt-br/contributing/translating.md). ## Testes Lógica não visual que pode rodar sem uma chamada de rede — funções puras, validadores, transformações, composables com entradas simuláveis — é entregue com uma especificação em `tests/` na mesma mudança. Renderização da UI, comportamento real de rede e APIs do navegador estão fora do escopo. Veja [Testes](/developer/pt-br/development/testing.md). ## Revisão de código Um mantenedor revisa cada pull request. Espere perguntas, mudanças solicitadas ou uma discussão sobre a abordagem antes de um merge. Isso é normal, não uma rejeição. Envie commits de acompanhamento para a mesma branch — o pull request é atualizado automaticamente. Se sua mudança for visual e não puder ser verificada sem interface gráfica, diga isso e anexe uma captura de tela ou uma gravação curta. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.ipcheck.ing/developer/pt-br/contributing/how-to-contribute.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.