Sites de documentação e de marketing do Flutter

O site de documentação (docs.flutterbrasil.dev) e o site de marketing (flutterbrasil.dev, incluindo o blog) do framework Flutter, construídos com Jaspr e hospedados no Firebase.

Problemas, bugs e solicitações

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

Se você tiver um problema com a documentação da API em api.flutter.dev, por favor, registre-o no repositório flutter/flutter, não neste repositório (flutter/website). A documentação da API está incorporada no código-fonte do Flutter, então a equipe de engenharia cuida dela.

Antes de enviar um PR

Adoramos quando a comunidade se envolve em melhorar nossa documentação! Aqui estão algumas coisas a ter em mente antes de enviar um PR:

• Ao fazer a triagem de problemas, às vezes rotulamos um problema com a tag PRs welcome. No entanto, recebemos PRs em outros problemas também— não precisa estar marcado com esse rótulo.
• Por favor, não execute nossa documentação através do Grammarly (ou uma ferramenta similar) e envie essas alterações como um PR.
• Seguimos o Google Developer Documentation Style Guidelines— por exemplo, evite "i.e." ou "e.g.", evite escrever em primeira pessoa e evite o tempo futuro. Você pode começar com os destaques do guia de estilo ou a lista de palavras, ou usar a barra de pesquisa no topo de cada página do guia de estilo.

Agradecemos sinceramente sua disposição e ajuda em manter a documentação do site atualizada!

Contribuindo

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

Se sua alteração envolve exemplos de código, adiciona/remove páginas ou afeta a navegação, por favor, compile e teste seu trabalho antes de enviar.

Se você quer ou precisa compilar o site, siga os passos abaixo.

Compilar o site

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

Obter os pré-requisitos

Para compilar e desenvolver o site, você precisará instalar a versão estável mais recente do Flutter, que inclui Dart.

Se você não tem o Flutter ou precisa atualizar, siga as instruções em Install Flutter ou Upgrading Flutter.

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

flutter --version

Clonar este repositório

Se você não é membro da organização Flutter, recomendamos que você crie um fork deste repositório na sua própria conta do GitHub e então envie um pull request a partir desse fork.

Depois de ter um fork (ou se você é membro da organização Flutter), clone o repositório com git clone:

git clone https://github.com/flutter/website.git

Configurar seu ambiente local e servir alterações

Antes de continuar configurando a infraestrutura do site, verifique se a versão correta do Flutter está configurada e disponível seguindo as instruções em Obter os pré-requisitos.

1. Opcional: Após clonar o repositório, crie um branch para suas alterações:

   git checkout -b <BRANCH_NAME>

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

   dart pub get

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

   dart run dash_site --help
   

4. Do diretório raiz, sirva o site localmente.

   Para servir o site de documentação (docs.flutterbrasil.dev):

   dart run dash_site serve
   

   Para servir o site de marketing e o blog (flutterbrasil.dev):

   dart run dash_site --site=www serve
   

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

5. Visualize suas alterações no navegador navegando para a URL local impressa no seu terminal.

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

   Para visualizar suas alterações no navegador, você precisará atualizar a página. O site deve reconstruir automaticamente na maioria das alterações, mas se algo não atualizar, saia do processo e execute o comando novamente.

7. Faça commit das 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.

Tip

Para conhecer outros comandos disponíveis, execute dart run dash_site --help do diretório raiz do repositório. Passe --site=www para qualquer comando para direcioná-lo ao flutterbrasil.dev em vez de docs.flutterbrasil.dev.

Validar suas alterações

Verificar documentação e código de exemplo

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

dart run dash_site check-all

Se este script reportar quaisquer erros ou avisos, resolva-os e execute o comando novamente. Se você tiver dúvidas, deixe um comentário no seu problema ou pull request, e faremos o nosso melhor para ajudar. Você também pode conversar conosco no canal #hackers-devrel no Flutter contributors Discord!

Verificar links

Se você fez alterações no conteúdo e quer verificar se todos os links internos e referências de links Markdown são válidos, compile o site localmente e execute os seguintes comandos.

1. Compile o site localmente.

   Para compilar o site de documentação (docs.flutterbrasil.dev):

   dart run dash_site build

   Para compilar o site de marketing e o blog (flutterbrasil.dev):

   dart run dash_site --site=www build

2. Verifique se todas as referências de links Markdown estão resolvidas.

   dart run dash_site check-link-references

3. Verifique se todos os links internos são válidos.

   Este comando depende de a ferramenta de CLI firebase estar no seu PATH. Se você não a instalou ou não a atualizou há algum tempo, siga Set up or update the Firebase CLI.

   dart run dash_site check-links

Se algum dos comandos reportar erros ou avisos, resolva-os, recompile o site e execute o comando novamente.

Atualizar trechos de código

Uma compilação que falha com o erro Error: Some code excerpts need 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 de verdade para trechos de código, e as instruções <?code-excerpt> anteriores nos arquivos Markdown especificam como os trechos são copiados dos arquivos .dart.

Para resolver este erro e atualizar os trechos Markdown para corresponder, do diretório raiz do website, execute dart run dash_site refresh-excerpts.

Para aprender mais sobre criar, editar e usar trechos de código, confira a documentação do pacote excerpt updater.