Repositório de desafios

Instruções

Este documento contém informações importantes sobre como enviar o seu desafio, assim como práticas recomendadas. Os admins recomendam a leitura integral do documento antes do envio de PRs, mesmo para aqueles que já possuam familiaridade com git e github.

Conteúdo

Este repositório contém os desafios enviados pelos participantes do grupo de programação OsProgramadores. O site do grupo contém a lista de desafios com descrições individuais de cada desafio.

Como contribuir

1. Visite o repositório op-desafios no github.

2. Faça um fork deste repositório clicando no botão Fork no canto superior da tela. Isso criará uma cópia completa do repositório sob o seu controle, no github.

3. Faça um clone do repositório para a sua estação de trabalho:

   git clone https://github.com/<seu_usuario_no_github>/op-desafios
   

4. Entre no diretório criado pelo git (op-desafios).

5. Crie um "git remote" chamado "upstream" apontando para o repositório principal. Isso facilitará a atualização do seu repositório local:

   git remote add upstream https://github.com/osprogramadores/op-desafios
   

6. Antes de começar a trabalhar em qualquer desafio: é importante resetar os números de commit entre a sua cópia local e o repositório principal (isso acontece porque o repositório principal usa rebase ao invés de feature branches). Existem duas maneiras de efetuar essa operação, mas a mais simples é usar "git reset" como indicado abaixo:

   git remote update
   git reset upstream/master --hard
   

   ATENÇÃO

   Os comandos acima irão reverter TODAS as modificações no seu repositório. É importante executá-los antes de introduzir qualquer modificação. Se você tem modificações a preservar, a maneira mais simples (para um iniciante) é copiar os arquivos a serem preservados para outro diretório, efetuar o git reset indicado acima, e copiar os arquivos de volta.

7. Crie um branch de trabalho com um nome adequado. No nosso exemplo, usaremos o nome "dev":

   git checkout -b dev
   

8. Trabalhe normalmente no branch de desenvolvimento. Quando estiver satisfeito com o resultado, faça o commit e o push com:

   git push origin dev --force
   

9. O git push transfere o conteúdo do seu branch corrente ("dev" nesse caso) para a o seu fork no github. Visite a página do seu fork no github (normalmente, https://github.com/SEU-USUARIO-NO-GITHUB/op-desafios) e clique no botão para abrir um PR.

O que fazer depois do envio?

Quando um PR é criado, o github envia um email para os admins, que farão a revisão das modificações e, em caso de aprovação, a incorporação (ou merge) das suas mudanças no repositório principal.

Um PR (ou pull request) é um pedido para incorporar as suas modificações ao repositório principal. A sua tarefa só estará terminada quando os admins tiverem incorporado as suas mudanças ao repositório principal (através de uma operação merge).

O repositório principal contém testes de integração que procuram por erros comuns e bloqueiam a aprovação até que estes tenham sido corrigidos. Por isso, fique atento ao seu email e a página do seu PR no github. Verifique que os testes de integração passaram e procure por mensagens dos admins relacionadas ao seu PR.

Em caso de erros nos testes de integração ou pedido de mudança por parte dos admins, corrija o problema no seu repositório local e crie outro commit com git commit, seguido por git push. Não crie outro PR, e não use o comando git reset até que as suas modificações tenham sido incorporadas no repositório principal.

PRs sem atividade por duas semanas serão automaticamente fechados.

Linguagens de programação e estrutura de diretórios

Ao criar um novo desafio, é importante observar a estrutura de diretórios usada pelo grupo:

desafio-XX/
  seu_usuario_no_github/
    linguagem/
      Seu código fonte(...)
      README.md

Onde:

• seu_usuário_no_github, é o seu usuário no github. :)

• linguagem é o nome de diretório usado para uma das linguagens aceitas:

  • c: C
  • cpp: C++
  • csharp: C#
  • java: Java
  • javascript: Javascript
  • go: Go
  • php: PHP
  • python: Python (versão 3.x)
  • rust: Rust

• README.md é um arquivo com comentários sobre a sua implementação e instruções de como executá-la.

Nota: Apenas desafios feitos em uma das linguagens acima e que possuam o arquivo README.md serão aceitos.

Exemplo de um desafio em Java:

desafio-02/johndoe/java/MeuPrograma.java
desafio-02/johndoe/java/README.md

Importante: Envie um PR por desafio. PRs com múltiplos desafios serão rejeitados.

Testes de integração

Os testes de integração rodam em todos os PRs e capturam vários erros comuns. Os admins só farão a revisão do seu PR se os testes de integração estiverem passando.

Algumas dicas básicas:

• Tente limitar ao máximo o envio de bibliotecas adicionais com os seus desafios.

• Não envie arquivos de configuração do seu IDE.

• Arquivos com espaços ou caracteres não ASCII no nome (acentos, Emoji, etc) não serão aceitos no repositório.

• Arquivos com conteúdo binário serão automaticamente rejeitados.

• Alguns editores (quando mal configurados) destroem caracteres UTF-8 (ou mandam caracteres inválidos). Arquivos com conteúdo UTF-8 inválido serão bloqueados pela integração.

• Arquivos contendo espaços ou tabs no final da linha (trailing spaces) serão rejeitados.

• Algumas linguagens de programação (ver abaixo) possuem checagens mais específicas. Nesse caso, algumas restrições se aplicarão ao código em si (estilo de formatação, erros, etc). Consulte a próxima seção para maiores detalhes.

Testes de linguagens específicas

Go

Use tabs para indentar o seu código (seguindo o padrão Go).

O seu código deverá passar sem erro pelas seguinte ferramentas padrão:

• golint
• go vet
• gofmt -s -l
• go build

Leia a documentação da linguagem Go sobre como obter essas ferramentas (normalmente, instaladas por default ou com um comando extra).

Java

1. O código deve ser formatado utilizando o estilo de desenvolvimento do Google.

2. O código será testado utilizando a OpenJDK VM na última versão LTS disponível: 17.

3. Utilizamos uma biblioteca open-source disponibilizada pelo Google para verificar a formatação do código. Dentro do repositório dela há mais informações sobre como integrá-la com ferramentas como Maven e Gradle caso deseje. A versão utilizada atualmente é a 1.15.0.

4. Para formatar os arquivos de acordo com o padrão utilizado, basta seguir os seguintes passos:

   curl -LJO "https://github.com/google/google-java-format/releases/download/v1.15.0/google-java-format-1.15.0-all-deps.jar"
   java -jar <caminho-para-o-jar-baixado>/google-java-format-1.15.0-all-deps.jar --replace <lista-arquivos-java>

5. Pull Requests contendo código em Java serão automaticamente verificados pela biblioteca indicada. Ao submeter um PR, observe a tela do PR e verifique se a integração falhou. Em caso de erro, clique no link e verifique as mensagens de erro.

6. Se precisar realizar alguma correção,faça no mesmo PR em que criou a solução original, não precisa abrir outro.

Python

1. Apenas Python 3.x é suportado.

2. Use espaços (não tabs!) para indentar o seu código.

3. Use indentação em 4 espaços.

4. Cheque o seu código com o pylint antes de enviar. O arquivo de configuração usado pelo repo está em ci/pylint3.rc. Para checar o seu programa, rode:

   pylint --rcfile=<diretorio_do_seu_repo>/ci/pylint3.rc <nome_do_seu_arquivo.py>
   

5. Pull Requests contendo código em Python serão automaticamente verificados pelo pylint. Ao submeter um PR, observe a tela do PR e verifique se a integração falhou. Em caso de erro, clique no link e verifique as mensagens de erro do pylint. Corrija o código, faça outro commit e push.

Javascript

1. O código será inspecionado pela ferramenta ESlint, utilizando as configurações padrões da ferramenta.

2. Instale NodeJS na sua máquina, seguindo as instruções aqui

3. Feche e abra o prompt de comando e faça o download do plugin do eslint no repositório localmente:

   cd <diretorio_do_seu_repo>
   npm install --save-dev eslint-config-standard-with-typescript@23.0.0 eslint@8.24.0

4. Cheque o seu código com o eslint antes de enviar. O arquivo de configuração usado pelo repo está em ci/.eslintrc.yml. Para checar o seu programa, rode:

   npx eslint -c <diretorio_do_seu_repo>/ci/.eslintrc.yml <caminho_arquivo.js>
   

   Por exemplo, se seu diretório está em /home/user/op-desafios, o arquivo se chama primos.js e está na pasta atual, o comando deve ser:

   npx eslint -c /home/user/op-desafios/ci/.eslintrc.yml primos.js
   

5. Pull Requests contendo código em Javascript serão automaticamente verificados pelo eslint. Ao submeter um PR, observe a tela do PR e verifique se a integração falhou. Em caso de erro, clique no link e verifique as mensagens de erro do eslint. Corrija o código, faça outro commit e push.

⚠️ Não faça commit da pasta node_modules e dos arquivos package.json e package-lock.json. Não faça git add *, adicione somente sua pasta de solução no commit.

Corrigindo um desafio

Qualquer um pode se voluntariar para corrigir os desafios na lista de pull requests. Você pode usar um script auxiliar para fazer checkout de um fork.

Digamos que você tenha que corrigir o desafio do usuário MatMercer na branch d10:

./checkout-fork.sh MatMercer:d10

# os comandos abaixo dependem do desafio e linguagem de programação usada
cd desafio-10/MatMercer/go
make

Ainda tem dúvidas?

Em caso de problemas ou dúvidas, entre em contato com um dos administradores no nosso canal no Telegram