Site de documentação do Flutter

O site de documentação para o framework Flutter, construído com Eleventy e hospedado no Firebase.

Problemas, bugs e solicitações

Agradecemos contribuições e feedback em nosso site. Por favor, registre uma solicitação em nosso rastreador de problemas ou crie um pull request. Para alterações simples (como ajustar algum texto), é mais fácil fazer as alterações usando a IU do GitHub.

Se você tiver um problema com os docs da API em api.flutter.dev, por favor, registre esses problemas no repositório flutter/flutter, e não neste repositório (flutter/website). Os docs da API estão incorporados no código-fonte do Flutter, então a equipe de engenharia lida com eles.

Antes de enviar um PR

Adoramos quando a comunidade se envolve na melhoria de nossos documentos! Mas aqui estão algumas coisas a ter em mente antes de enviar um PR:

• Ao analisar os problemas, às vezes, marcamos um problema com a tag PRs welcome (PRs são bem-vindos). Mas também aceitamos PRs em outros problemas - não precisa ser marcado com essa tag.
• Por favor, não execute nossos documentos pelo Grammarly (ou similar) e envie essas alterações como um PR.
• Seguimos as Diretrizes de estilo de documentação do Google para desenvolvedores - por exemplo, não use "i.e." ou "e.g.", evite escrever na primeira pessoa, e evite escrever no tempo futuro. Você pode começar com os destaques do guia de estilo ou a lista de palavras, ou use a barra de pesquisa que está no topo de cada página do guia de estilo.

Nós realmente agradecemos sua disposição e ajuda em manter os documentos do site atualizados!

Contribuindo

Para atualizar este site, faça um fork do repositório, faça suas alterações e gere um pull request. Para pequenas alterações contidas (como correções de estilo e erros de digitação), você provavelmente não precisa construir este site. Muitas vezes, você pode fazer alterações usando a IU do GitHub. Se necessário, podemos organizar as alterações automaticamente em seu pull request.

[!IMPORTANTE] Se você estiver clonando este repositório localmente, siga as instruções abaixo sobre como clonar com seu submódulo.

Se a sua alteração envolver exemplos de código, adicionar/remover páginas ou afetar a navegação, considere construir e testar seu trabalho antes de enviar.

Se você quiser ou precisar construir o site, siga as etapas abaixo.

Construir o site

Para alterações além de pequenos ajustes de texto e CSS, recomendamos executar o site localmente para habilitar um ciclo de edição-atualização.

Obtenha os pré-requisitos

Instale as seguintes ferramentas para construir e desenvolver o site:

Flutter

A versão estável mais recente do Flutter, que inclui o Dart, é necessária para construir o site e executar suas ferramentas. Se você não tem o Flutter ou precisa atualizar, siga as instruções em Instalar o Flutter ou Atualizar o Flutter.

Se você já tem o Flutter instalado, verifique se ele está no seu caminho e já é a versão estável mais recente:

flutter --version

Node.js

A versão LTS estável mais recente do Node.js é necessária para construir o site. Se você não tem o Node.js ou precisa atualizar, baixe a versão correspondente do seu computador e siga as instruções do arquivo de download do Node.js. Se preferir, você pode usar um gerenciador de versão como o nvm, e executar nvm install a partir do diretório raiz do repositório.

Se você já tem o Node instalado, verifique se ele está disponível em seu caminho e já é a versão estável mais recente (atualmente 22.12 ou posterior):

node --version

Se sua versão estiver desatualizada, siga as instruções de atualização de como você o instalou originalmente.

Clone este repositório e seus submódulos

[!NOTA] Este repositório tem submódulos git, o que afeta como você o clona. A documentação do GitHub tem ajuda geral sobre forking e clonagem de repositórios.

Se você não é membro da organização Flutter, recomendamos que você crie um fork deste repositório em sua própria conta, e então envie um PR desse fork.

Depois de ter um fork (ou você é um membro da organização Flutter), escolha uma das seguintes técnicas de clonagem de submódulo:

1. Clone o repositório e seu submódulo ao mesmo tempo usando a opção --recurse-submodules:

   git clone --recurse-submodules https://github.com/flutter/website.git

2. Se você já clonou o repositório sem seu submódulo, então execute este comando a partir da raiz do repositório:

   git submodule update --init --recursive

[!NOTA] A qualquer momento durante o desenvolvimento você pode usar o comando git submodule para atualizar os submódulos:

git pull && git submodule update --init --recursive

Configure seu ambiente local e sirva as alterações

Antes de continuar a configurar a infraestrutura do site, verifique se as versões corretas do Flutter e Node.js estão configuradas e disponíveis seguindo as instruções em Obtenha os pré-requisitos.

1. Opcional: Depois de clonar o repositório e seus submódulos, crie um branch para suas alterações:

   git checkout -b <NOME_DO_BRANCH>

2. A partir do diretório raiz do repositório, busque as dependências Dart do site.

   dart pub get

3. Opcional: Recomendamos que você use pnpm, mas você também pode usar npm. Instale pnpm, um gerenciador de pacotes alternativo e eficiente para pacotes npm. Se você já tem pnpm, verifique se tem a versão estável mais recente.

   node --version

   Se você ainda não tem o pnpm instalado, recomendamos usar o corepack para instalar e gerenciar as versões do pnpm, já que o corepack é fornecido com a maioria das instalações do Node. Se você instalou o node usando o Homebrew, precisará instalar o corepack separadamente:

   brew install corepack

   Se você não usou o corepack antes, precisará primeiro habilitá-lo com corepack enable. Em seguida, para instalar a versão correta do pnpm, a partir do diretório raiz do repositório, execute corepack install:

   corepack enable;
   corepack install

   Para instalar pnpm sem usar o corepack, você pode usar seu método de instalação preferido.

4. (opcional) Depois de ter o pnpm instalado e configurado, busque as dependências npm do site usando pnpm install. Recomendamos que você use pnpm, mas você também pode usar npm.

   pnpm install

   Execute pnpm install novamente sempre que incorporar as últimas alterações no branch main ou se você encontrar erros de dependência ou importação ao construir o site.

5. A partir do diretório raiz, execute a ferramenta dash_site para validar sua configuração e aprender sobre os comandos disponíveis.

   ./dash_site --help

6. A partir do diretório raiz, sirva o site localmente.

   ./dash_site serve

   Este comando gera e serve o site em uma porta local que é impressa em seu terminal.

7. Veja suas alterações no navegador navegando para http://localhost:4000.

   Observe que a porta pode ser diferente se 4000 estiver ocupada.

   Se você quiser verificar a saída e estrutura HTML bruta gerada, veja o diretório _site em um explorador de arquivos ou IDE.

8. Faça suas alterações no repositório local.

   O site deve ser reconstruído automaticamente na maioria das alterações, mas se algo não atualizar, saia do processo e execute o comando novamente. Melhorias nesta funcionalidade estão planejadas. Por favor, abra um novo problema para acompanhar o problema se isso ocorrer.

9. Confirme suas alterações no branch e envie seu PR.

Se sua alteração for grande, ou você gostaria de testá-la, considere validar suas alterações.

[!DICA] Para encontrar comandos adicionais que você pode executar, execute ./dash_site --help a partir do diretório raiz do repositório.

Validar suas alterações

Verifique a documentação e o código de exemplo

Se você fez alterações no código nos diretórios /examples ou /tool, confirme seu trabalho e execute o seguinte comando para verificar se ele está atualizado e corresponde aos padrões do site.

./dash_site check-all

Se este script relatar quaisquer erros ou avisos, então resolva esses problemas e execute o comando novamente. Se você tiver algum problema, deixe um comentário em seu problema ou pull request, e faremos o possível para ajudá-lo. Você também pode conversar conosco no canal #hackers-devrel no Discord de contribuidores do Flutter!

Atualizar trechos de código

Uma construção que falha com o erro Error: Some code excerpts needed to be updated! significa que um ou mais trechos de código nos arquivos Markdown do site não são idênticos às regiões de código declaradas nos arquivos .dart correspondentes.

Os arquivos .dart são a fonte da verdade para trechos de código, e as instruções <?code-excerpt> precedentes nos arquivos Markdown especificam como os trechos são copiados dos arquivos .dart.

Para resolver esse erro e atualizar os trechos Markdown para corresponder, a partir da raiz do diretório website, execute ./dash_site refresh-excerpts.

Para saber mais sobre como criar, editar e usar trechos de código, confira a documentação do pacote de atualização de trechos.

[Opcional] Implantar em um site de staging

Pull requests enviados podem ser automaticamente organizados por um mantenedor do site. Se você gostaria de organizar o site sozinho, você pode construir uma versão completa e carregá-la no Firebase.

1. Se você ainda não tem um projeto Firebase,

• Navegue até o Console do Firebase e crie seu próprio projeto Firebase (por exemplo, flutter-dev-staging).

• Volte para seu terminal local e verifique se você está logado.

  firebase login

• Certifique-se de que seu projeto existe e ative esse projeto:

  firebase projects:list
  firebase use <seu-projeto>

2. A partir do diretório raiz do repositório, construa o site:

   ./dash_site build

   Isso constrói o site e o copia para seu diretório local _site. Se esse diretório existia anteriormente, ele será substituído.

3. Implante no site de hospedagem padrão do seu projeto Firebase ativado:

   firebase deploy --only hosting

4. Navegue até o seu PR no GitHub e inclua o link da versão organizada. Considere adicionar uma referência ao commit que você organizou, para que os revisores saibam se alguma alteração adicional foi feita.