|
|
# Принос към "Основи на науката за данни"
|
|
|
|
|
|
Благодарим ви за интереса към приноса към учебната програма "Основи на науката за данни"! Приветстваме приноси от общността.
|
|
|
|
|
|
## Съдържание
|
|
|
|
|
|
- [Кодекс на поведение](../..)
|
|
|
- [Как мога да допринеса?](../..)
|
|
|
- [Първи стъпки](../..)
|
|
|
- [Насоки за принос](../..)
|
|
|
- [Процес на Pull Request](../..)
|
|
|
- [Насоки за стил](../..)
|
|
|
- [Споразумение за лиценз на приносителя](../..)
|
|
|
|
|
|
## Кодекс на поведение
|
|
|
|
|
|
Този проект е приел [Кодекса на поведение за отворен код на Microsoft](https://opensource.microsoft.com/codeofconduct/).
|
|
|
За повече информация вижте [Често задавани въпроси за Кодекса на поведение](https://opensource.microsoft.com/codeofconduct/faq/)
|
|
|
или се свържете с [opencode@microsoft.com](mailto:opencode@microsoft.com) за допълнителни въпроси или коментари.
|
|
|
|
|
|
## Как мога да допринеса?
|
|
|
|
|
|
### Докладване на грешки
|
|
|
|
|
|
Преди да създадете доклади за грешки, моля, проверете съществуващите проблеми, за да избегнете дублиране. Когато създавате доклад за грешка, включете възможно най-много подробности:
|
|
|
|
|
|
- **Използвайте ясно и описателно заглавие**
|
|
|
- **Опишете точните стъпки за възпроизвеждане на проблема**
|
|
|
- **Предоставете конкретни примери** (кодови откъси, екранни снимки)
|
|
|
- **Опишете наблюдаваното поведение и какво сте очаквали**
|
|
|
- **Включете подробности за вашата среда** (ОС, версия на Python, браузър)
|
|
|
|
|
|
### Предлагане на подобрения
|
|
|
|
|
|
Предложения за подобрения са добре дошли! Когато предлагате подобрения:
|
|
|
|
|
|
- **Използвайте ясно и описателно заглавие**
|
|
|
- **Предоставете подробно описание на предложеното подобрение**
|
|
|
- **Обяснете защо това подобрение би било полезно**
|
|
|
- **Избройте подобни функции в други проекти, ако е приложимо**
|
|
|
|
|
|
### Принос към документацията
|
|
|
|
|
|
Подобренията в документацията винаги са ценни:
|
|
|
|
|
|
- **Поправете правописни и граматически грешки**
|
|
|
- **Подобрете яснотата на обясненията**
|
|
|
- **Добавете липсваща документация**
|
|
|
- **Актуализирайте остаряла информация**
|
|
|
- **Добавете примери или случаи на употреба**
|
|
|
|
|
|
### Принос към кода
|
|
|
|
|
|
Приветстваме кодови приноси, включително:
|
|
|
|
|
|
- **Нови уроци или упражнения**
|
|
|
- **Поправки на грешки**
|
|
|
- **Подобрения на съществуващи тетрадки**
|
|
|
- **Нови набори от данни или примери**
|
|
|
- **Подобрения на приложението за тестове**
|
|
|
|
|
|
## Първи стъпки
|
|
|
|
|
|
### Предварителни изисквания
|
|
|
|
|
|
Преди да допринесете, уверете се, че имате:
|
|
|
|
|
|
1. Акаунт в GitHub
|
|
|
2. Инсталиран Git на вашата система
|
|
|
3. Python 3.7+ и Jupyter инсталирани
|
|
|
4. Node.js и npm (за приноси към приложението за тестове)
|
|
|
5. Запознатост със структурата на учебната програма
|
|
|
|
|
|
Вижте [INSTALLATION.md](INSTALLATION.md) за подробни инструкции за настройка.
|
|
|
|
|
|
### Форк и клониране
|
|
|
|
|
|
1. **Направете форк на репозитория** в GitHub
|
|
|
2. **Клонирайте вашия форк** локално:
|
|
|
```bash
|
|
|
git clone https://github.com/YOUR-USERNAME/Data-Science-For-Beginners.git
|
|
|
cd Data-Science-For-Beginners
|
|
|
```
|
|
|
3. **Добавете upstream remote**:
|
|
|
```bash
|
|
|
git remote add upstream https://github.com/microsoft/Data-Science-For-Beginners.git
|
|
|
```
|
|
|
|
|
|
### Създаване на клон
|
|
|
|
|
|
Създайте нов клон за вашата работа:
|
|
|
|
|
|
```bash
|
|
|
git checkout -b feature/your-feature-name
|
|
|
# or
|
|
|
git checkout -b fix/your-bug-fix
|
|
|
```
|
|
|
|
|
|
Конвенции за именуване на клонове:
|
|
|
- `feature/` - Нови функции или уроци
|
|
|
- `fix/` - Поправки на грешки
|
|
|
- `docs/` - Промени в документацията
|
|
|
- `refactor/` - Рефакториране на код
|
|
|
|
|
|
## Насоки за принос
|
|
|
|
|
|
### За съдържание на уроци
|
|
|
|
|
|
Когато допринасяте уроци или модифицирате съществуващи:
|
|
|
|
|
|
1. **Следвайте съществуващата структура**:
|
|
|
- README.md със съдържание на урока
|
|
|
- Jupyter тетрадка с упражнения
|
|
|
- Задача (ако е приложимо)
|
|
|
- Връзка към предварителни и последващи тестове
|
|
|
|
|
|
2. **Включете тези елементи**:
|
|
|
- Ясни учебни цели
|
|
|
- Обяснения стъпка по стъпка
|
|
|
- Кодови примери с коментари
|
|
|
- Упражнения за практика
|
|
|
- Връзки към допълнителни ресурси
|
|
|
|
|
|
3. **Осигурете достъпност**:
|
|
|
- Използвайте ясен, прост език
|
|
|
- Осигурете alt текст за изображения
|
|
|
- Включете коментари в кода
|
|
|
- Вземете предвид различни стилове на учене
|
|
|
|
|
|
### За Jupyter тетрадки
|
|
|
|
|
|
1. **Изчистете всички изходи** преди да комитнете:
|
|
|
```bash
|
|
|
jupyter nbconvert --clear-output --inplace notebook.ipynb
|
|
|
```
|
|
|
|
|
|
2. **Включете markdown клетки** с обяснения
|
|
|
|
|
|
3. **Използвайте последователно форматиране**:
|
|
|
```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. **Тествайте вашата тетрадка** напълно преди подаване
|
|
|
|
|
|
### За Python код
|
|
|
|
|
|
Следвайте насоките за стил [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)
|
|
|
```
|
|
|
|
|
|
### За приноси към приложението за тестове
|
|
|
|
|
|
Когато модифицирате приложението за тестове:
|
|
|
|
|
|
1. **Тествайте локално**:
|
|
|
```bash
|
|
|
cd quiz-app
|
|
|
npm install
|
|
|
npm run serve
|
|
|
```
|
|
|
|
|
|
2. **Пуснете линтер**:
|
|
|
```bash
|
|
|
npm run lint
|
|
|
```
|
|
|
|
|
|
3. **Успешно изградете**:
|
|
|
```bash
|
|
|
npm run build
|
|
|
```
|
|
|
|
|
|
4. **Следвайте насоките за стил на Vue.js** и съществуващите модели
|
|
|
|
|
|
### За преводи
|
|
|
|
|
|
Когато добавяте или актуализирате преводи:
|
|
|
|
|
|
1. Следвайте структурата в папката `translations/`
|
|
|
2. Използвайте езиковия код като име на папката (например `fr` за френски)
|
|
|
3. Поддържайте същата структура на файловете като английската версия
|
|
|
4. Актуализирайте връзките към тестовете, за да включват езиков параметър: `?loc=fr`
|
|
|
5. Тествайте всички връзки и форматиране
|
|
|
|
|
|
## Процес на Pull Request
|
|
|
|
|
|
### Преди подаване
|
|
|
|
|
|
1. **Актуализирайте вашия клон** с последните промени:
|
|
|
```bash
|
|
|
git fetch upstream
|
|
|
git rebase upstream/main
|
|
|
```
|
|
|
|
|
|
2. **Тествайте вашите промени**:
|
|
|
- Пуснете всички модифицирани тетрадки
|
|
|
- Тествайте приложението за тестове, ако е модифицирано
|
|
|
- Уверете се, че всички връзки работят
|
|
|
- Проверете за правописни и граматически грешки
|
|
|
|
|
|
3. **Комитнете вашите промени**:
|
|
|
```bash
|
|
|
git add .
|
|
|
git commit -m "Brief description of changes"
|
|
|
```
|
|
|
|
|
|
Напишете ясни съобщения за комит:
|
|
|
- Използвайте сегашно време ("Добавяне на функция", а не "Добавена функция")
|
|
|
- Използвайте императивно наклонение ("Премести курсора към...", а не "Премества курсора към...")
|
|
|
- Ограничете първия ред до 72 символа
|
|
|
- Позовавайте се на проблеми и Pull Requests, когато е уместно
|
|
|
|
|
|
4. **Пушнете към вашия форк**:
|
|
|
```bash
|
|
|
git push origin feature/your-feature-name
|
|
|
```
|
|
|
|
|
|
### Създаване на Pull Request
|
|
|
|
|
|
1. Отидете до [репозитория](https://github.com/microsoft/Data-Science-For-Beginners)
|
|
|
2. Кликнете "Pull requests" → "New pull request"
|
|
|
3. Кликнете "compare across forks"
|
|
|
4. Изберете вашия форк и клон
|
|
|
5. Кликнете "Create pull request"
|
|
|
|
|
|
### Формат на заглавието на PR
|
|
|
|
|
|
Използвайте ясни, описателни заглавия, следвайки този формат:
|
|
|
|
|
|
```
|
|
|
[Component] Brief description
|
|
|
```
|
|
|
|
|
|
Примери:
|
|
|
- `[Lesson 7] Fix Python notebook import error`
|
|
|
- `[Quiz App] Add German translation`
|
|
|
- `[Docs] Update README with new prerequisites`
|
|
|
- `[Fix] Correct data path in visualization lesson`
|
|
|
|
|
|
### Описание на PR
|
|
|
|
|
|
Включете в описанието на вашия PR:
|
|
|
|
|
|
- **Какво**: Какви промени направихте?
|
|
|
- **Защо**: Защо тези промени са необходими?
|
|
|
- **Как**: Как реализирахте промените?
|
|
|
- **Тестване**: Как тествахте промените?
|
|
|
- **Екранни снимки**: Включете екранни снимки за визуални промени
|
|
|
- **Свързани проблеми**: Връзка към свързани проблеми (например "Fixes #123")
|
|
|
|
|
|
### Процес на преглед
|
|
|
|
|
|
1. **Автоматични проверки** ще се изпълнят на вашия PR
|
|
|
2. **Поддържащите ще прегледат** вашия принос
|
|
|
3. **Отговорете на обратната връзка**, като направите допълнителни комити
|
|
|
4. След одобрение, **поддържащ ще слее** вашия PR
|
|
|
|
|
|
### След като вашият PR бъде слят
|
|
|
|
|
|
1. Изтрийте вашия клон:
|
|
|
```bash
|
|
|
git branch -d feature/your-feature-name
|
|
|
git push origin --delete feature/your-feature-name
|
|
|
```
|
|
|
|
|
|
2. Актуализирайте вашия форк:
|
|
|
```bash
|
|
|
git checkout main
|
|
|
git pull upstream main
|
|
|
git push origin main
|
|
|
```
|
|
|
|
|
|
## Насоки за стил
|
|
|
|
|
|
### Markdown
|
|
|
|
|
|
- Използвайте последователни нива на заглавия
|
|
|
- Включвайте празни редове между секциите
|
|
|
- Използвайте кодови блокове с указания за език:
|
|
|
````markdown
|
|
|
```python
|
|
|
import pandas as pd
|
|
|
```
|
|
|
````
|
|
|
- Добавяйте alt текст към изображения: ``
|
|
|
- Поддържайте разумна дължина на редовете (около 80-100 символа)
|
|
|
|
|
|
### Python
|
|
|
|
|
|
- Следвайте насоките за стил на PEP 8
|
|
|
- Използвайте значими имена на променливи
|
|
|
- Добавяйте docstrings към функции
|
|
|
- Включвайте типови подсказки, когато е подходящо:
|
|
|
```python
|
|
|
def process_data(df: pd.DataFrame) -> pd.DataFrame:
|
|
|
"""Process the input dataframe."""
|
|
|
return df
|
|
|
```
|
|
|
|
|
|
### JavaScript/Vue.js
|
|
|
|
|
|
- Следвайте насоките за стил на Vue.js 2
|
|
|
- Използвайте предоставената конфигурация на ESLint
|
|
|
- Пишете модулни, многократно използваеми компоненти
|
|
|
- Добавяйте коментари за сложна логика
|
|
|
|
|
|
### Организация на файлове
|
|
|
|
|
|
- Дръжте свързаните файлове заедно
|
|
|
- Използвайте описателни имена на файлове
|
|
|
- Следвайте съществуващата структура на директории
|
|
|
- Не комитвайте ненужни файлове (.DS_Store, .pyc, node_modules и др.)
|
|
|
|
|
|
## Споразумение за лиценз на приносителя
|
|
|
|
|
|
Този проект приветства приноси и предложения. Повечето приноси изискват от вас да
|
|
|
се съгласите със Споразумение за лиценз на приносителя (CLA), което декларира, че имате право да,
|
|
|
и действително предоставяте ни правата да използваме вашия принос. За подробности посетете
|
|
|
https://cla.microsoft.com.
|
|
|
|
|
|
Когато подадете Pull Request, CLA-бот автоматично ще определи дали трябва
|
|
|
да предоставите CLA и ще украси PR съответно (например, етикет, коментар). Просто следвайте
|
|
|
инструкциите, предоставени от бота. Ще трябва да направите това само веднъж за всички репозитории, използващи нашия CLA.
|
|
|
|
|
|
## Въпроси?
|
|
|
|
|
|
- Проверете нашия [Discord канал #data-science-for-beginners](https://aka.ms/ds4beginners/discord)
|
|
|
- Присъединете се към нашата [Discord общност](https://aka.ms/ds4beginners/discord)
|
|
|
- Прегледайте съществуващите [проблеми](https://github.com/microsoft/Data-Science-For-Beginners/issues) и [Pull Requests](https://github.com/microsoft/Data-Science-For-Beginners/pulls)
|
|
|
|
|
|
## Благодарим ви!
|
|
|
|
|
|
Вашите приноси правят тази учебна програма по-добра за всички. Благодарим ви, че отделихте време да допринесете!
|
|
|
|
|
|
---
|
|
|
|
|
|
**Отказ от отговорност**:
|
|
|
Този документ е преведен с помощта на AI услуга за превод [Co-op Translator](https://github.com/Azure/co-op-translator). Въпреки че се стремим към точност, моля, имайте предвид, че автоматизираните преводи може да съдържат грешки или неточности. Оригиналният документ на неговия роден език трябва да се счита за авторитетен източник. За критична информация се препоръчва професионален човешки превод. Не носим отговорност за недоразумения или погрешни интерпретации, произтичащи от използването на този превод. |
