You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
360 lines
11 KiB
360 lines
11 KiB
# Contribuir para Data Science para Principiantes
|
|
|
|
Obrigado pelo seu interesse em contribuir para o currículo de Data Science para Principiantes! Agradecemos as contribuições da comunidade.
|
|
|
|
## Índice
|
|
|
|
- [Código de Conduta](../..)
|
|
- [Como Posso Contribuir?](../..)
|
|
- [Primeiros Passos](../..)
|
|
- [Diretrizes de Contribuição](../..)
|
|
- [Processo de Pull Request](../..)
|
|
- [Diretrizes de Estilo](../..)
|
|
- [Acordo de Licença de Contribuidor](../..)
|
|
|
|
## Código de Conduta
|
|
|
|
Este projeto adotou o [Código de Conduta de Código Aberto da Microsoft](https://opensource.microsoft.com/codeofconduct/).
|
|
Para mais informações, consulte as [FAQ do Código de Conduta](https://opensource.microsoft.com/codeofconduct/faq/)
|
|
ou contacte [opencode@microsoft.com](mailto:opencode@microsoft.com) para quaisquer questões ou comentários adicionais.
|
|
|
|
## Como Posso Contribuir?
|
|
|
|
### Reportar Erros
|
|
|
|
Antes de criar relatórios de erros, verifique os problemas existentes para evitar duplicados. Ao criar um relatório de erro, inclua o máximo de detalhes possível:
|
|
|
|
- **Use um título claro e descritivo**
|
|
- **Descreva os passos exatos para reproduzir o problema**
|
|
- **Forneça exemplos específicos** (trechos de código, capturas de ecrã)
|
|
- **Descreva o comportamento observado e o que esperava**
|
|
- **Inclua os detalhes do seu ambiente** (SO, versão do Python, navegador)
|
|
|
|
### Sugerir Melhorias
|
|
|
|
Sugestões de melhorias são bem-vindas! Ao sugerir melhorias:
|
|
|
|
- **Use um título claro e descritivo**
|
|
- **Forneça uma descrição detalhada da melhoria sugerida**
|
|
- **Explique por que esta melhoria seria útil**
|
|
- **Liste quaisquer funcionalidades semelhantes em outros projetos, se aplicável**
|
|
|
|
### Contribuir para a Documentação
|
|
|
|
Melhorias na documentação são sempre apreciadas:
|
|
|
|
- **Corrigir erros ortográficos e gramaticais**
|
|
- **Melhorar a clareza das explicações**
|
|
- **Adicionar documentação em falta**
|
|
- **Atualizar informações desatualizadas**
|
|
- **Adicionar exemplos ou casos de uso**
|
|
|
|
### Contribuir com Código
|
|
|
|
Aceitamos contribuições de código, incluindo:
|
|
|
|
- **Novas lições ou exercícios**
|
|
- **Correções de erros**
|
|
- **Melhorias em notebooks existentes**
|
|
- **Novos conjuntos de dados ou exemplos**
|
|
- **Melhorias na aplicação de quizzes**
|
|
|
|
## Primeiros Passos
|
|
|
|
### Pré-requisitos
|
|
|
|
Antes de contribuir, certifique-se de que tem:
|
|
|
|
1. Uma conta no GitHub
|
|
2. Git instalado no seu sistema
|
|
3. Python 3.7+ e Jupyter instalados
|
|
4. Node.js e npm (para contribuições na aplicação de quizzes)
|
|
5. Familiaridade com a estrutura do currículo
|
|
|
|
Consulte [INSTALLATION.md](INSTALLATION.md) para instruções detalhadas de configuração.
|
|
|
|
### Fazer Fork e Clonar
|
|
|
|
1. **Faça fork do repositório** no GitHub
|
|
2. **Clone o seu fork** localmente:
|
|
```bash
|
|
git clone https://github.com/YOUR-USERNAME/Data-Science-For-Beginners.git
|
|
cd Data-Science-For-Beginners
|
|
```
|
|
|
|
3. **Adicione o upstream remoto**:
|
|
```bash
|
|
git remote add upstream https://github.com/microsoft/Data-Science-For-Beginners.git
|
|
```
|
|
|
|
|
|
### Criar uma Branch
|
|
|
|
Crie uma nova branch para o seu trabalho:
|
|
|
|
```bash
|
|
git checkout -b feature/your-feature-name
|
|
# or
|
|
git checkout -b fix/your-bug-fix
|
|
```
|
|
|
|
Convenções de nomenclatura de branches:
|
|
- `feature/` - Novas funcionalidades ou lições
|
|
- `fix/` - Correções de erros
|
|
- `docs/` - Alterações na documentação
|
|
- `refactor/` - Refatoração de código
|
|
|
|
## Diretrizes de Contribuição
|
|
|
|
### Para Conteúdo de Lições
|
|
|
|
Ao contribuir com lições ou modificar as existentes:
|
|
|
|
1. **Siga a estrutura existente**:
|
|
- README.md com o conteúdo da lição
|
|
- Notebook Jupyter com exercícios
|
|
- Tarefa (se aplicável)
|
|
- Link para quizzes pré e pós-lição
|
|
|
|
2. **Inclua estes elementos**:
|
|
- Objetivos de aprendizagem claros
|
|
- Explicações passo a passo
|
|
- Exemplos de código com comentários
|
|
- Exercícios para prática
|
|
- Links para recursos adicionais
|
|
|
|
3. **Garanta acessibilidade**:
|
|
- Use linguagem clara e simples
|
|
- Forneça texto alternativo para imagens
|
|
- Inclua comentários no código
|
|
- Considere diferentes estilos de aprendizagem
|
|
|
|
### Para Notebooks Jupyter
|
|
|
|
1. **Limpe todos os outputs** antes de fazer commit:
|
|
```bash
|
|
jupyter nbconvert --clear-output --inplace notebook.ipynb
|
|
```
|
|
|
|
2. **Inclua células markdown** com explicações
|
|
|
|
3. **Use formatação consistente**:
|
|
```python
|
|
# Import libraries at the top
|
|
import pandas as pd
|
|
import numpy as np
|
|
import matplotlib.pyplot as plt
|
|
|
|
# Use meaningful variable names
|
|
# Add comments for complex operations
|
|
# Follow PEP 8 style guidelines
|
|
```
|
|
|
|
4. **Teste o notebook** completamente antes de submeter
|
|
|
|
### Para Código Python
|
|
|
|
Siga as diretrizes de estilo [PEP 8](https://www.python.org/dev/peps/pep-0008/):
|
|
```python
|
|
# Good practices
|
|
import pandas as pd
|
|
|
|
def calculate_mean(data):
|
|
"""Calculate the mean of a dataset.
|
|
|
|
Args:
|
|
data (list): List of numerical values
|
|
|
|
Returns:
|
|
float: Mean of the dataset
|
|
"""
|
|
return sum(data) / len(data)
|
|
```
|
|
|
|
|
|
### Para Contribuições na Aplicação de Quizzes
|
|
|
|
Ao modificar a aplicação de quizzes:
|
|
|
|
1. **Teste localmente**:
|
|
```bash
|
|
cd quiz-app
|
|
npm install
|
|
npm run serve
|
|
```
|
|
|
|
2. **Execute o linter**:
|
|
```bash
|
|
npm run lint
|
|
```
|
|
|
|
3. **Construa com sucesso**:
|
|
```bash
|
|
npm run build
|
|
```
|
|
|
|
4. **Siga o guia de estilo Vue.js** e os padrões existentes
|
|
|
|
### Para Traduções
|
|
|
|
Ao adicionar ou atualizar traduções:
|
|
|
|
1. Siga a estrutura na pasta `translations/`
|
|
2. Use o código do idioma como nome da pasta (ex.: `pt` para Português)
|
|
3. Mantenha a mesma estrutura de ficheiros da versão em inglês
|
|
4. Atualize os links dos quizzes para incluir o parâmetro de idioma: `?loc=pt`
|
|
5. Teste todos os links e a formatação
|
|
|
|
## Processo de Pull Request
|
|
|
|
### Antes de Submeter
|
|
|
|
1. **Atualize a sua branch** com as alterações mais recentes:
|
|
```bash
|
|
git fetch upstream
|
|
git rebase upstream/main
|
|
```
|
|
|
|
2. **Teste as suas alterações**:
|
|
- Execute todos os notebooks modificados
|
|
- Teste a aplicação de quizzes, se modificada
|
|
- Verifique se todos os links funcionam
|
|
- Revise erros ortográficos e gramaticais
|
|
|
|
3. **Faça commit das suas alterações**:
|
|
```bash
|
|
git add .
|
|
git commit -m "Brief description of changes"
|
|
```
|
|
|
|
Escreva mensagens de commit claras:
|
|
- Use o tempo presente ("Adicionar funcionalidade" em vez de "Adicionou funcionalidade")
|
|
- Use o modo imperativo ("Mover cursor para..." em vez de "Move cursor para...")
|
|
- Limite a primeira linha a 72 caracteres
|
|
- Referencie problemas e pull requests quando relevante
|
|
|
|
4. **Faça push para o seu fork**:
|
|
```bash
|
|
git push origin feature/your-feature-name
|
|
```
|
|
|
|
|
|
### Criar o Pull Request
|
|
|
|
1. Acesse o [repositório](https://github.com/microsoft/Data-Science-For-Beginners)
|
|
2. Clique em "Pull requests" → "New pull request"
|
|
3. Clique em "compare across forks"
|
|
4. Selecione o seu fork e branch
|
|
5. Clique em "Create pull request"
|
|
|
|
### Formato do Título do PR
|
|
|
|
Use títulos claros e descritivos seguindo este formato:
|
|
```
|
|
[Component] Brief description
|
|
```
|
|
|
|
Exemplos:
|
|
- `[Lesson 7] Corrigir erro de importação no notebook Python`
|
|
- `[Quiz App] Adicionar tradução para alemão`
|
|
- `[Docs] Atualizar README com novos pré-requisitos`
|
|
- `[Fix] Corrigir caminho de dados na lição de visualização`
|
|
|
|
### Descrição do PR
|
|
|
|
Inclua na descrição do seu PR:
|
|
|
|
- **O quê**: Quais alterações foram feitas?
|
|
- **Porquê**: Por que estas alterações são necessárias?
|
|
- **Como**: Como implementou as alterações?
|
|
- **Testes**: Como testou as alterações?
|
|
- **Capturas de ecrã**: Inclua capturas de ecrã para alterações visuais
|
|
- **Problemas Relacionados**: Link para problemas relacionados (ex.: "Fixes #123")
|
|
|
|
### Processo de Revisão
|
|
|
|
1. **Verificações automáticas** serão executadas no seu PR
|
|
2. **Os mantenedores irão rever** a sua contribuição
|
|
3. **Responda ao feedback** fazendo commits adicionais
|
|
4. Uma vez aprovado, um **mantenedor irá fazer merge** do seu PR
|
|
|
|
### Após o Merge do Seu PR
|
|
|
|
1. Apague a sua branch:
|
|
```bash
|
|
git branch -d feature/your-feature-name
|
|
git push origin --delete feature/your-feature-name
|
|
```
|
|
|
|
2. Atualize o seu fork:
|
|
```bash
|
|
git checkout main
|
|
git pull upstream main
|
|
git push origin main
|
|
```
|
|
|
|
|
|
## Diretrizes de Estilo
|
|
|
|
### Markdown
|
|
|
|
- Use níveis de cabeçalho consistentes
|
|
- Inclua linhas em branco entre seções
|
|
- Use blocos de código com especificadores de linguagem:
|
|
````markdown
|
|
```python
|
|
import pandas as pd
|
|
```
|
|
````
|
|
|
|
- Adicione texto alternativo às imagens: ``
|
|
- Mantenha comprimentos de linha razoáveis (cerca de 80-100 caracteres)
|
|
|
|
### Python
|
|
|
|
- Siga o guia de estilo PEP 8
|
|
- Use nomes de variáveis significativos
|
|
- Adicione docstrings às funções
|
|
- Inclua dicas de tipo quando apropriado:
|
|
```python
|
|
def process_data(df: pd.DataFrame) -> pd.DataFrame:
|
|
"""Process the input dataframe."""
|
|
return df
|
|
```
|
|
|
|
|
|
### JavaScript/Vue.js
|
|
|
|
- Siga o guia de estilo Vue.js 2
|
|
- Use a configuração ESLint fornecida
|
|
- Escreva componentes modulares e reutilizáveis
|
|
- Adicione comentários para lógica complexa
|
|
|
|
### Organização de Ficheiros
|
|
|
|
- Mantenha ficheiros relacionados juntos
|
|
- Use nomes de ficheiros descritivos
|
|
- Siga a estrutura de diretórios existente
|
|
- Não faça commit de ficheiros desnecessários (.DS_Store, .pyc, node_modules, etc.)
|
|
|
|
## Acordo de Licença de Contribuidor
|
|
|
|
Este projeto aceita contribuições e sugestões. A maioria das contribuições requer que concorde com um Acordo de Licença de Contribuidor (CLA), declarando que tem o direito de, e realmente concede-nos os direitos para usar a sua contribuição. Para mais detalhes, visite
|
|
https://cla.microsoft.com.
|
|
|
|
Quando submeter um pull request, um CLA-bot determinará automaticamente se precisa fornecer um CLA e decorará o PR apropriadamente (ex.: etiqueta, comentário). Basta seguir as instruções fornecidas pelo bot. Só precisará fazer isto uma vez em todos os repositórios que utilizam o nosso CLA.
|
|
|
|
## Questões?
|
|
|
|
- Consulte o nosso [Canal Discord #data-science-for-beginners](https://aka.ms/ds4beginners/discord)
|
|
- Junte-se à nossa [comunidade Discord](https://aka.ms/ds4beginners/discord)
|
|
- Revise os [problemas](https://github.com/microsoft/Data-Science-For-Beginners/issues) e [pull requests](https://github.com/microsoft/Data-Science-For-Beginners/pulls) existentes
|
|
|
|
## Obrigado!
|
|
|
|
As suas contribuições tornam este currículo melhor para todos. Obrigado por dedicar o seu tempo a contribuir!
|
|
|
|
---
|
|
|
|
**Aviso**:
|
|
Este documento foi traduzido utilizando o serviço de tradução por IA [Co-op Translator](https://github.com/Azure/co-op-translator). Embora nos esforcemos para garantir a precisão, é importante notar que traduções automáticas podem conter erros ou imprecisões. O documento original na sua língua nativa deve ser considerado a fonte autoritária. Para informações críticas, recomenda-se a tradução profissional realizada por humanos. Não nos responsabilizamos por quaisquer mal-entendidos ou interpretações incorretas decorrentes do uso desta tradução. |