Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
359 lines (264 loc) · 16.4 KB

CONTRIBUTING.md

File metadata and controls

359 lines (264 loc) · 16.4 KB

Принос към "Основи на науката за данни"

Благодарим ви за интереса към приноса към учебната програма "Основи на науката за данни"! Приветстваме приноси от общността.

Съдържание

Кодекс на поведение

Този проект е приел Кодекса на поведение за отворен код на Microsoft. За повече информация вижте Често задавани въпроси за Кодекса на поведение или се свържете с opencode@microsoft.com за допълнителни въпроси или коментари.

Как мога да допринеса?

Докладване на грешки

Преди да създадете доклади за грешки, моля, проверете съществуващите проблеми, за да избегнете дублиране. Когато създавате доклад за грешка, включете възможно най-много подробности:

  • Използвайте ясно и описателно заглавие
  • Опишете точните стъпки за възпроизвеждане на проблема
  • Предоставете конкретни примери (кодови откъси, екранни снимки)
  • Опишете наблюдаваното поведение и какво сте очаквали
  • Включете подробности за вашата среда (ОС, версия на Python, браузър)

Предлагане на подобрения

Предложения за подобрения са добре дошли! Когато предлагате подобрения:

  • Използвайте ясно и описателно заглавие
  • Предоставете подробно описание на предложеното подобрение
  • Обяснете защо това подобрение би било полезно
  • Избройте подобни функции в други проекти, ако е приложимо

Принос към документацията

Подобренията в документацията винаги са ценни:

  • Поправете правописни и граматически грешки
  • Подобрете яснотата на обясненията
  • Добавете липсваща документация
  • Актуализирайте остаряла информация
  • Добавете примери или случаи на употреба

Принос към кода

Приветстваме кодови приноси, включително:

  • Нови уроци или упражнения
  • Поправки на грешки
  • Подобрения на съществуващи тетрадки
  • Нови набори от данни или примери
  • Подобрения на приложението за тестове

Първи стъпки

Предварителни изисквания

Преди да допринесете, уверете се, че имате:

  1. Акаунт в GitHub
  2. Инсталиран Git на вашата система
  3. Python 3.7+ и Jupyter инсталирани
  4. Node.js и npm (за приноси към приложението за тестове)
  5. Запознатост със структурата на учебната програма

Вижте INSTALLATION.md за подробни инструкции за настройка.

Форк и клониране

  1. Направете форк на репозитория в GitHub
  2. Клонирайте вашия форк локално: 
    git clone https://github.com/YOUR-USERNAME/Data-Science-For-Beginners.git
cd Data-Science-For-Beginners
  3. Добавете upstream remote: 
    git remote add upstream https://github.com/microsoft/Data-Science-For-Beginners.git

Създаване на клон

Създайте нов клон за вашата работа:

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. Изчистете всички изходи преди да комитнете:

    jupyter nbconvert --clear-output --inplace notebook.ipynb

  2. Включете markdown клетки с обяснения

  3. Използвайте последователно форматиране:

    # 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:

# 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. Тествайте локално:

    cd quiz-app
npm install
npm run serve

  2. Пуснете линтер:

    npm run lint

  3. Успешно изградете:

    npm run build

  4. Следвайте насоките за стил на Vue.js и съществуващите модели

За преводи

Когато добавяте или актуализирате преводи:

  1. Следвайте структурата в папката translations/
  2. Използвайте езиковия код като име на папката (например fr за френски)
  3. Поддържайте същата структура на файловете като английската версия
  4. Актуализирайте връзките към тестовете, за да включват езиков параметър: ?loc=fr
  5. Тествайте всички връзки и форматиране

Процес на Pull Request

Преди подаване

  1. Актуализирайте вашия клон с последните промени:

    git fetch upstream
git rebase upstream/main

  2. Тествайте вашите промени:

    • Пуснете всички модифицирани тетрадки
    • Тествайте приложението за тестове, ако е модифицирано
    • Уверете се, че всички връзки работят
    • Проверете за правописни и граматически грешки

  3. Комитнете вашите промени:

    git add .
git commit -m "Brief description of changes"

    Напишете ясни съобщения за комит:

    • Използвайте сегашно време ("Добавяне на функция", а не "Добавена функция")
    • Използвайте императивно наклонение ("Премести курсора към...", а не "Премества курсора към...")
    • Ограничете първия ред до 72 символа
    • Позовавайте се на проблеми и Pull Requests, когато е уместно

  4. Пушнете към вашия форк:

    git push origin feature/your-feature-name

Създаване на Pull Request

  1. Отидете до репозитория
  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. Изтрийте вашия клон:

    git branch -d feature/your-feature-name
git push origin --delete feature/your-feature-name

  2. Актуализирайте вашия форк:

    git checkout main
git pull upstream main
git push origin main

Насоки за стил

Markdown

  • Използвайте последователни нива на заглавия
  • Включвайте празни редове между секциите
  • Използвайте кодови блокове с указания за език: 
    ```python
import pandas as pd
```
  • Добавяйте alt текст към изображения: ![Alt text](../../translated_images/bg/image.4ee84a82b5e4c9e6651b13fd27dcf615e427ec584929f2cef7167aa99151a77a.png)
  • Поддържайте разумна дължина на редовете (около 80-100 символа)

Python

  • Следвайте насоките за стил на PEP 8
  • Използвайте значими имена на променливи
  • Добавяйте docstrings към функции
  • Включвайте типови подсказки, когато е подходящо: 
    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.

Въпроси?

Благодарим ви!

Вашите приноси правят тази учебна програма по-добра за всички. Благодарим ви, че отделихте време да допринесете!

Отказ от отговорност:
Този документ е преведен с помощта на AI услуга за превод Co-op Translator. Въпреки че се стремим към точност, моля, имайте предвид, че автоматизираните преводи може да съдържат грешки или неточности. Оригиналният документ на неговия роден език трябва да се счита за авторитетен източник. За критична информация се препоръчва професионален човешки превод. Не носим отговорност за недоразумения или погрешни интерпретации, произтичащи от използването на този превод.