18 KiB
Siga este guia para configurar a aplicação para dispositivos móveis do freeCodeCamp localmente no seu sistema. Isso é altamente recomendado se você quer contribuir regularmente.
Alguns dos fluxos de trabalho de contribuição — como a correção de erros na base de código — necessitam que você execute a aplicação do freeCodeCamp localmente.
Como preparar sua máquina local
Comece instalando o software pré-requisito para seu sistema operacional.
Pré-requisitos:
Pré-requisito | Versão | Observações |
---|---|---|
Flutter | 3.x |
- |
Dart (vem junto com o Flutter) | 2.x |
Utilizamos a versão integrada com o Flutter. |
[!ATTENTION] Se você tem uma versão diferente, instale a versão recomendada. Só podemos dar suporte a problemas de instalação para versões recomendadas.
Se o Flutter já estiver instalado em sua máquina, execute os seguintes comandos para validar as versões:
flutter --version
dart --version
[!TIP] É altamente recomendável atualizar para as versões estáveis mais recentes do software listado acima.
Depois de ter os pré-requisitos instalados, você precisa preparar seu ambiente de desenvolvimento. Isto é comum para muitos fluxos de trabalho de desenvolvimento, e você só precisará fazer isso uma vez.
Siga estas etapas para deixar seu ambiente de desenvolvimento pronto:
-
Instale o Git ou seu cliente Git favorito, se você ainda não fez isso. Atualize para a versão mais recente. A versão que veio com seu SO pode estar desatualizada.
-
Configure o Android Studio e os emuladores do Android com a versão mais recente do Android. Recomendamos usar a Pixel 3a XL e a Nexus One (para emulação de telas menores).
-
(Opcional para MacOS) Configuração do Xcode e do iOS Simulator com a versão mais recente do iOS lançada.
-
(Opcional, mas recomendado) Configure uma chave SSH para o GitHub.
-
Instale um editor de código de sua escolha.
Nós recomendamos muito usar o Visual Studio Code ou o Android Studio. Também recomendamos instalar as extensões oficiais.
Faça o fork do repositório no GitHub
Forking é uma etapa onde você obtém sua própria cópia do repositório (vulgo repo) no GitHub.
Isso é essencial, pois permite que você trabalhe em sua própria cópia da aplicação para dispositivos móveis do freeCodeCamp no GitHub, ou fazer download (clone) do repositório para trabalhar localmente. Mais tarde, você poderá solicitar alterações para serem enviadas para o repositório principal através de um pull request (PR).
[!TIP] O repositório principal em
https://github.com/freeCodeCamp/mobile
é frequentemente chamado de repositórioupstream
.Seu fork em
https://github.com/YOUR_USER_NAME/mobile
frequentemente é referenciado como o repositórioorigin
.YOUR_USER_NAME
será substituído pelo seu nome de usuário do GitHub.
Siga estes passos para criar um fork do repositório https://github.com/freeCodeCamp/mobile
:
-
Vá até o repositório da aplicação do freeCodeCamp para dispositivos móveis no GitHub: https://github.com/freeCodeCamp/mobile
-
Clique no botão "Fork" no canto superior direito da interface (Mais detalhes aqui)
-
Depois que o repositório recebeu um fork, você será redirecionado para a cópia do repositório em
https://github.com/YOUR_USER_NAME/mobile
(YOUR_USER_NAME
será substituído pelo seu nome de usuário do GitHub).
Clonar o seu fork no GitHub
Clonar é onde ** você faz o download de uma cópia** de um repositório de um local remoto
que pertence a você ou a outra pessoa. No seu caso, este local remoto é o seu fork
do repositório freeCodeCamp que deve estar disponível em https://github.com/YOUR_USER_NAME/mobile
. (YOUR_USER_NAME
será substituído pelo seu nome de usuário do GitHub.)
Execute esses comandos em sua máquina local:
-
Abra um Terminal/Prompt de Comando/Shell no diretório de seus projetos
ex.:
/yourprojectsdirectory/
-
Clone seu fork do freeCodeCamp, substituindo
YOUR_USER_NAME
pelo seu nome de usuário do GitHubgit clone --depth=1 https://github.com/YOUR_USER_NAME/mobile.git
Isto vai baixar todo o repositório da aplicação do freeCodeCamp para dispositivos móveis para seu diretório de projetos.
Nota: --depth=1
cria um clone raso do seu fork, com apenas o histórico mais recente.
Configurar sincronização a partir do pai
Agora que você baixou uma cópia do seu fork, será necessário configurar um remote upstream
para o repositório pai.
Como mencionado anteriormente, o repositório principal é referenciado como repositório upstream
. Seu fork é referenciado como repositório origin
.
É necessária uma referência do seu clone local para o repositório upstream
além do repositório origin
. Isso é para que você possa sincronizar alterações do repositório principal sem a exigência de fazer fork e clone várias vezes.
-
Mude o diretório para o novo diretório
mobile
:cd mobile
-
Adicione uma referência remota ao repositório principal mobile do freeCodeCamp:
git remote add upstream https://github.com/freeCodeCamp/mobile.git
-
Certifique-se de que a configuração esteja correta:
git remote -v
O resultado deve ser algo parecido com o mostrado abaixo (substituindo
YOUR_USER_NAME
com seu nome de usuário do GitHub):origin https://github.com/YOUR_USER_NAME/mobile.git (fetch) origin https://github.com/YOUR_USER_NAME/mobile.git (push) upstream https://github.com/freeCodeCamp/mobile.git (fetch) upstream https://github.com/freeCodeCamp/mobile.git (push)
Executar a aplicação do freeCodeCamp para dispositivos móveis localmente
Agora que você tem uma cópia local da aplicação do freeCodeCamp para dispositivos móveis, você pode seguir estas instruções para executá-la localmente.
Se você encontrar problemas, primeiro faça uma busca na web e procurar por respostas. Se não for encontrada uma solução, por favor, procure em nossa página de issues do GitHub para encontrar uma solução e reporte o problema se ainda não foi reportado.
E como sempre, fique à vontade em perguntar na categoria 'Contributors' (colaboradores) do fórum ou no servidor de chat.
[!NOTE] O diretório
mobile
contém duas pastas,mobile-api
emobile-app
.mobile-api
contém o código da API usada para servir os podcasts.mobile-app
contém a aplicação em Flutter, que é onde você deve estar quando seguir os passos abaixo.
Configurar dependências
Passo 1: Configure o arquivo de variável de ambiente
As chaves de API padrão e variáveis de ambiente são armazenadas no arquivo sample.env
. Esse arquivo precisa ser copiado para um novo arquivo chamado .env
que é acessado dinamicamente durante a etapa de instalação. Lembre-se de mudar o diretório para mobile-app
antes de executar os comandos a seguir.
# Crie uma cópia da "sample.env" e a nomeie como ".env".
# Preencha-o com as chaves e segredos de API necessários:
macOS/Linux
cp sample.env .env
Windows
copy sample.env .env
As chaves no arquivo .env
_ não _ precisam ser alteradas para executar o aplicativo localmente. Você pode deixar os valores padrão copiados de sample.env
como estão.
Passo 2: Instalar as dependências
Esta etapa vai instalar as dependências necessárias para a execução do aplicativo:
flutter pub get
Passo 3: Iniciar a aplicação do freeCodeCamp para dispositivos móveis
Inicie o emulador de sua escolha (Android ou iOS) e aguarde a conclusão do processo de inicialização.
Agora, você pode iniciar o aplicativo executando o seguinte comando:
flutter run
[!TIP] Se estiver usando o VSCode ou o Android Studio, poderá iniciar a aplicação facilmente sem ter de executar os comandos no terminal. Mais informações aqui.
Fazer alterações localmente
Agora você pode fazer alterações nos arquivos e fazer commit das suas alterações no seu clone local do seu fork.
Siga estes passos:
-
Certifique-se que está no branch
main
:git status
Você deve ver um resultado como este:
Na branch main Sua branch está atualizada com 'origin/main'. nada para enviar no commit, diretório de trabalho limpo
Se você não está no main ou seu diretório de trabalho não está limpo, resolva quaisquer arquivos/commits e saia do
main
:git checkout main
-
Sincronize as últimas mudanças da branch
main
upstream para sua branch main local:[!WARNING] Se você possui qualquer pull request feito a partir da branch
main
, você os perderá ao fim desta etapa.Certifique-se de que foi feito um merge no seu pull request por um moderador antes de executar este passo. Para evitar essa situação, você sempre deve trabalhar em uma brach que não seja a
main
.Este passo irá sincronizar as últimas alterações do repositório principal da aplicação do freeCodeCamp para dispositivos móveis. É importante fazer um rebase em sua branch usando
upstream/main
frequentemente para evitar conflitos depois.Atualize sua cópia local do repositório upstream da aplicação do freeCodeCamp para dispositivos móveis:
git fetch upstream
Faça um hard reset na sua branch main com a main da aplicação do freeCodeCamp para dispositivos móveis:
git reset --hard upstream/main
Faça um push da sua branch main para a origin para obter um histórico claro em seu fork do GitHub:
git push origin main --force
Você pode validar se sua main atual combina com upstream/main fazendo um diff:
git diff upstream/main
O resultado deve mostrar vazio.
-
Crie uma branch novinha em folha:
Trabalhar em uma branch separada para cada issue ajuda a manter sua cópia de trabalho local limpa. Você nunca deve trabalhar na
main
. Isso vai sujar sua cópia da aplicação do freeCodeCamp para dispositivos móveis e você pode ter que começar de novo com um clone ou fork.Veja se você está na
main
como explicado antes e crie uma branch a partir dela:git checkout -b fix/update-guide-for-xyz
Seu nome de branch deve começar com
fix/
,feat/
,docs/
, etc. Evite usar números de issues em branches. Mantenha-os curtos, significativos e únicos.Alguns exemplos de bons nomes para branches são:
fix/update-challenges-for-react fix/update-guide-for-html-css fix/platform-bug-sign-in-issues feat/add-guide-article-for-javascript translate/add-spanish-basic-html
-
Edite páginas e trabalhe no código em seu editor de texto favorito.
-
Quando estiver satisfeito com as alterações, você deve opcionalmente executar a aplicação do freeCodeCamp para dispositivos móveis localmente para visualizar as alterações.
-
Certifique-se de corrigir quaisquer erros e verificar a formatação de suas alterações.
-
Verifique e confirme os arquivos que você está atualizando:
git status
Isso deve mostrar uma lista dos arquivos
unstaged
que você editou.Na branch feat/documentation Sua branch está atualizada com 'upstream/feat/documentation'. As mudanças não estão organizadas para commit: (use "git add/rm <file>..." para atualizar o que será enviado) (use "git checkout -- <file>..." para descartar as alterações no diretório de trabalho) modified: README.md modified: mobile-app/lib/main.dart ...
-
Organize as alterações e faça um commit:
Nesta etapa, você só deve marcar arquivos que você editou ou adicionou. Você pode executar um reset e resolver arquivos que você não pretendeu mudar se necessário.
git add caminho/para/meu/arquivo/alterado.ext
Ou você pode adicionar todos os arquivos
unstaged
para a área de preparação:git add .
Apenas os arquivos que foram movidos para a área de staging serão adicionados quando você fizer um commit.
git status
Resultado:
Na branch feat/documentation Sua branch está atualizada com 'upstream/feat/documentation'. Alterações a serem enviadas: (use "git reset HEAD <file>..." para retirar do staging) modified: README.md modified: mobile-app/lib/main.dart
Agora, você pode fazer o commit das alterações com uma pequena mensagem assim:
git commit -m "fix: my short commit message"
Alguns exemplos:
fix: update guide article for Java - for loop feat: add guide article for alexa skills
Opcional:
É altamente recomendável fazer uma mensagem convencional de commit. Esta é uma boa prática que você verá em alguns dos repositórios de código aberto populares. Como um desenvolvedor, isso incentiva você a seguir os padrões.
Alguns exemplos de mensagens convencionais de commit são:
correção: atualizar artigo do guia HTML fix: atualizar scripts de compilação para Travis-CI fear: adicionar artigo para a documentação de hoisting em JavaScript docs: atualizar diretrizes de contribuição
Escreva pouco, não mais do que 50 caracteres. Você sempre pode adicionar informações extras na descrição da mensagem de commit.
Isso não leva mais tempo do que uma mensagem não convencional como 'atualizar arquivo' ou 'adicionar index.md'
Você pode aprender mais sobre o motivo de usar commits convencionais aqui.
-
Se você se deu conta que precisa editar um arquivo ou atualizar a mensagem de commit você pode fazer isso assim:
git commit --amend
Isso abrirá um editor de texto padrão, como
nano
ouvi
onde você pode editar o título da mensagem de commit e adicionar/editar a descrição. -
Em seguida, você pode fazer push das suas alterações no seu fork:
git push origin branch/nome-aqui
Propondo um Pull Request (PR)
Após ter feito as alterações, veja como abrir um Pull Request.
Solução de problemas
Problemas com a instalação dos pré-requisitos recomendados
Regularmente desenvolvemos nos sistemas mais populares como macOS 10.15, Ubuntu 18.04 e Windows 10 (com WSL2).
É recomendado pesquisar seu issue específico em recursos como Google, Stack Overflow e Stack Exchange. É possível que alguém já tenha enfrentado o mesmo problema que o seu e já possui uma solução.
Se você está em um sistema operacional diferente e/ou ainda está com problemas, veja obtendo ajuda.
Problemas com a Interface do Usuário, fontes, errors de build, etc.
Se você enfrenta problemas com a interface do usuário ou erros de build, uma limpeza pode ser útil:
flutter clean
Problemas ao instalar dependências
Se você receber erros durante a instalação das dependências, certifique-se de que você não está em uma rede restrita ou suas configurações de firewall não impedem você de acessar os recursos.
Seja paciente, pois a primeira configuração pode demorar um pouco, dependendo da largura de banda da sua rede.
Obter ajuda
Se você está com dificuldades e precisa de ajuda, fique à vontade em perguntar na categoria 'Contributors' (colaboradores) em nosso fórum ou na sala de bate-papo dos colaboradores.
Pode haver um erro no console do seu navegador ou no Bash/Terminal/Linha de Comando que ajudará a identificar o problema. Forneça esta mensagem de erro na descrição do seu problema para que outros possam identificá-lo mais facilmente e ajudá-lo a encontrar uma solução.