🤝 Руководство для разработчиков

Добро пожаловать в проект MapsYandexAPI! Мы рады, что вы хотите внести свой вклад в развитие проекта.

📋 Содержание

Как начать
Структура проекта
Стандарты кода
Процесс разработки
Тестирование
Документация
Создание Pull Request
Сообщения об ошибках
Вопросы и обсуждения

🚀 Как начать

Предварительные требования

Git - система контроля версий
Java 11+ - для Android разработки
Kotlin 1.8+ - основной язык разработки
Android Studio или IntelliJ IDEA - IDE
Xcode 14+ - для iOS разработки (macOS)
Node.js 16+ - для веб-разработки

Клонирование репозитория

git clone https://github.com/your-username/MapsYandexAPI.git
cd MapsYandexAPI

Настройка окружения

Android

# Установка Android SDK
./gradlew setupAndroidSdk

# Синхронизация Gradle
./gradlew build

iOS

# Установка зависимостей
cd iosApp
pod install
cd ..

Веб

# Установка зависимостей
npm install

# Запуск локального сервера
npm start

🏗️ Структура проекта

Основные модули

MapsYandexAPI/
├── 📁 composeApp/           # Android приложение
│   ├── src/main/kotlin/    # Исходный код
│   ├── src/main/res/       # Ресурсы
│   └── build.gradle.kts    # Конфигурация сборки
├── 📁 iosApp/               # iOS приложение
│   ├── MapsYandexAPI/      # Исходный код
│   └── Podfile             # Зависимости CocoaPods
├── 📁 mapkit-bindings/      # Kotlin/Native биндинги
│   └── src/main/kotlin/    # Биндинги MapKit
├── 📁 mapkit-interop/       # Межплатформенный слой
│   └── src/main/kotlin/    # Общий код
├── 📁 common/               # Общий код
│   └── src/main/kotlin/    # Кроссплатформенная логика
├── 📁 docs/                 # Документация
└── 🌐 Веб-файлы             # HTML, CSS, JavaScript

Ключевые файлы

build.gradle.kts - Основная конфигурация Gradle
settings.gradle.kts - Настройки проекта
gradle.properties - Свойства Gradle
local.properties - Локальные настройки (не в git)

📝 Стандарты кода

Kotlin

Стиль кода

Следуйте Kotlin Coding Conventions
Используйте ktlint для проверки стиля
Максимальная длина строки: 120 символов

Пример кода

/**
 * Добавляет маркер на карту с заданными координатами
 *
 * @param coords координаты маркера
 * @param options дополнительные настройки маркера
 * @return созданный маркер
 */
fun addMarker(
    coords: Coordinates,
    options: MarkerOptions? = null
): Marker {
    require(coords.latitude in -90.0..90.0) { "Широта должна быть в диапазоне -90..90" }
    require(coords.longitude in -180.0..180.0) { "Долгота должна быть в диапазоне -180..180" }
    
    return markerFactory.create(coords, options)
}

JavaScript

Стиль кода

Следуйте Airbnb JavaScript Style Guide
Используйте ESLint и Prettier
Максимальная длина строки: 100 символов

Пример кода

/**
 * Добавляет маркер на карту
 * @param {Array} coords - Координаты [широта, долгота]
 * @param {Object} options - Дополнительные настройки
 * @returns {Object} Созданный маркер
 */
function addMarker(coords, options = {}) {
    // Валидация входных данных
    if (!Array.isArray(coords) || coords.length !== 2) {
        throw new Error('Координаты должны быть массивом из двух элементов');
    }
    
    const [lat, lng] = coords;
    if (lat < -90 || lat > 90) {
        throw new Error('Широта должна быть в диапазоне -90..90');
    }
    
    // Создание маркера
    const marker = createMarker(coords, options);
    this.objects.push(marker);
    
    return marker;
}

Общие принципы

Читаемость - код должен быть понятным
Документированность - комментируйте сложные участки
Тестируемость - пишите код, который легко тестировать
Производительность - учитывайте производительность
Безопасность - валидируйте все входные данные

🔄 Процесс разработки

1. Создание ветки

# Обновление основной ветки
git checkout main
git pull origin main

# Создание новой ветки
git checkout -b feature/your-feature-name

2. Разработка

Пишите код согласно стандартам
Добавляйте тесты для новой функциональности
Обновляйте документацию при необходимости

3. Коммиты

# Добавление файлов
git add .

# Создание коммита
git commit -m "feat: добавлена поддержка кластеризации маркеров

- Реализован алгоритм кластеризации
- Добавлены настройки кластеризации
- Обновлена документация API"

Конвенции коммитов

Используйте Conventional Commits:

feat: - новая функциональность
fix: - исправление ошибки
docs: - изменения в документации
style: - форматирование кода
refactor: - рефакторинг кода
test: - добавление тестов
chore: - обновление зависимостей

4. Push и Pull Request

# Отправка ветки
git push origin feature/your-feature-name

Затем создайте Pull Request на GitHub.

🧪 Тестирование

Типы тестов

Unit тесты

@Test
fun `should create marker with valid coordinates`() {
    // Given
    val coords = Coordinates(55.7558, 37.6176)
    val options = MarkerOptions(title = "Test")
    
    // When
    val marker = mapKit.addMarker(coords, options)
    
    // Then
    assertThat(marker.coordinates).isEqualTo(coords)
    assertThat(marker.title).isEqualTo("Test")
}

Integration тесты

@Test
fun `should initialize map with configuration`() {
    // Given
    val config = MapConfig(
        apiKey = "test-key",
        center = Coordinates(55.7558, 37.6176),
        zoom = 10
    )
    
    // When
    mapKit.init(config)
    
    // Then
    assertThat(mapKit.isInitialized()).isTrue()
    assertThat(mapKit.getCenter()).isEqualTo(config.center)
}

E2E тесты

@Test
fun `should display marker on map`() {
    // Given
    val coords = Coordinates(55.7558, 37.6176)
    
    // When
    mapKit.addMarker(coords)
    
    // Then
    assertThat(mapKit.getObjects()).hasSize(1)
    assertThat(mapKit.getObjects().first()).isInstanceOf(Marker::class.java)
}

Запуск тестов

# Все тесты
./gradlew test

# Только unit тесты
./gradlew testDebugUnitTest

# Только integration тесты
./gradlew connectedDebugAndroidTest

# Покрытие кода
./gradlew jacocoTestReport

Требования к покрытию

Unit тесты: минимум 80%
Integration тесты: минимум 70%
E2E тесты: критическая функциональность

📚 Документация

Обновление документации

При добавлении новой функциональности обновляйте:

README.md - общий обзор
API_REFERENCE.md - справка по API
USER_GUIDE.md - руководство пользователя
CHANGELOG.md - история изменений

Пример обновления API документации

#### `addCluster(markers, options?)`
Добавляет кластер маркеров на карту.

**Параметры:**
- `markers` (Array) - Массив маркеров для кластеризации
- `options` (Object, опционально) - Настройки кластера

**Пример:**
```javascript
const markers = [
    [55.7558, 37.6176],
    [55.7559, 37.6177],
    [55.7560, 37.6178]
];

const cluster = mapKit.addCluster(markers, {
    maxZoom: 15,
    radius: 50
});


## 🔀 Создание Pull Request

### Шаблон Pull Request

```markdown
## 📝 Описание

Краткое описание изменений

## 🎯 Тип изменений

- [ ] 🐛 Исправление ошибки
- [ ] ✨ Новая функциональность
- [ ] 📚 Обновление документации
- [ ] 🎨 Улучшение UI/UX
- [ ] ⚡ Улучшение производительности
- [ ] 🔧 Рефакторинг

## 🔍 Что изменилось

- Описание изменений 1
- Описание изменений 2
- Описание изменений 3

## 🧪 Тестирование

- [ ] Unit тесты добавлены/обновлены
- [ ] Integration тесты добавлены/обновлены
- [ ] E2E тесты добавлены/обновлены
- [ ] Тесты проходят локально

## 📸 Скриншоты

Добавьте скриншоты, если это UI изменения

## 📋 Чек-лист

- [ ] Код соответствует стандартам проекта
- [ ] Документация обновлена
- [ ] CHANGELOG.md обновлен
- [ ] Все тесты проходят
- [ ] Код прошел code review

## 🔗 Связанные issues

Closes #123

Процесс review

Автоматические проверки должны пройти
Code review от команды разработчиков
Тесты должны проходить
Документация должна быть обновлена

🐛 Сообщения об ошибках

Шаблон issue

## 🐛 Описание ошибки

Краткое описание проблемы

## 🔍 Шаги для воспроизведения

1. Откройте приложение
2. Нажмите на кнопку X
3. Ошибка происходит

## 📱 Окружение

- **Платформа**: Android/iOS/Web
- **Версия**: 1.0.0
- **Устройство**: Samsung Galaxy S21
- **OS**: Android 12

## 📸 Скриншоты

Добавьте скриншоты ошибки

## 📋 Дополнительная информация

Любая дополнительная информация

💬 Вопросы и обсуждения

Каналы связи

GitHub Issues - для багов и предложений
GitHub Discussions - для вопросов и обсуждений
Pull Requests - для code review

Правила общения

Будьте вежливы и уважительны
Используйте русский или английский язык
Задавайте конкретные вопросы
Предоставляйте контекст при описании проблем

🏆 Признание вклада

Способы внесения вклада

🐛 Сообщения об ошибках
💡 Предложения по улучшению
📚 Обновление документации
🧪 Написание тестов
🔧 Исправление ошибок
✨ Новая функциональность

Благодарности

Все участники проекта будут добавлены в:

README.md - список участников
CONTRIBUTORS.md - детальная информация
GitHub Contributors - автоматически

📞 Получение помощи

Если у вас есть вопросы:

Проверьте документацию - возможно, ответ уже есть
Поищите в issues - похожие проблемы могли обсуждаться
Создайте issue - если не нашли ответ
Присоединитесь к обсуждениям - для общих вопросов

🎯 Цели проекта

Краткосрочные цели

Улучшение производительности
Добавление новых типов карт
Расширение API

Долгосрочные цели

Поддержка 3D карт
AR интеграция
Машинное обучение

📈 Метрики качества

Мы отслеживаем:

Покрытие тестами
Время сборки
Размер приложения
Производительность
Качество кода

🔮 Будущее проекта

Проект активно развивается. Мы планируем:

Расширение платформ - поддержка новых ОС
Улучшение API - более удобные методы
Оптимизация - лучшая производительность
Интеграции - работа с другими сервисами

Спасибо за ваш вклад в проект! 🎉

Если у вас есть вопросы или предложения, не стесняйтесь обращаться к команде разработчиков.

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History

CONTRIBUTING.md

File metadata and controls

🤝 Руководство для разработчиков

📋 Содержание

🚀 Как начать

Предварительные требования

Клонирование репозитория

Настройка окружения

Android

iOS

Веб

🏗️ Структура проекта

Основные модули

Ключевые файлы

📝 Стандарты кода

Kotlin

Стиль кода

Пример кода

JavaScript

Стиль кода

Пример кода

Общие принципы

🔄 Процесс разработки

1. Создание ветки

2. Разработка

3. Коммиты

Конвенции коммитов

4. Push и Pull Request

🧪 Тестирование

Типы тестов

Unit тесты

Integration тесты

E2E тесты

Запуск тестов

Требования к покрытию

📚 Документация

Обновление документации

Пример обновления API документации

Процесс review

🐛 Сообщения об ошибках

Шаблон issue

💬 Вопросы и обсуждения

Каналы связи

Правила общения

🏆 Признание вклада

Способы внесения вклада

Благодарности

📞 Получение помощи

🎯 Цели проекта

Краткосрочные цели

Долгосрочные цели

📈 Метрики качества

🔮 Будущее проекта