Участие в проекте Leaflet

1. Как участвовать
2. Сообщение об ошибках
3. Вклад в код
4. Запуск тестов
5. Улучшение документации
6. Кодекс поведения
7. Спасибо

Как участвовать

Вклад сторонних разработчиков абсолютно необходим в нашем стремлении создать лучшую картографическую библиотеку, которая когда-либо существовала. Однако, это не единственный способ вовлечься в разработку Leaflet. Вы можете значительно помочь проекту, обнаруживая и сообщая об ошибках; улучшая документацию; помогая другим на Stack Overflow, GIS Stack Exchange и GitHub issues; отправляя твиты на @LeafletJS; и распространяя информацию о Leaflet среди коллег и друзей.

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

Перед тем как сообщить об ошибке на странице issues проекта, сначала убедитесь, что ваша проблема вызвана Leaflet, а не вашим кодом приложения (например, передача неверных аргументов методам и т.д.). Вторым шагом является поиск уже сообщенных ошибок для похожих случаев, и если ошибка уже сообщена, просто добавьте любые дополнительные детали в комментариях.После того, как вы убедитесь, что нашли новую ошибку в Leaflet, вот несколько советов по созданию полезного отчета, который сделает исправление ошибки намного быстрее и проще:

• Напишите описательное, конкретное название. Плохо: Проблема с полилиниями. Хорошо: Выполнение X в IE9 вызывает Z.
• Включите информацию о браузере, операционной системе и версии Leaflet в описание.
• Создайте простой тестовый случай, который демонстрирует ошибку (например, используя Leaflet plunker).
• Проверьте, можно ли воспроизвести ошибку в других браузерах.
• Проверьте, возникает ли ошибка в стабильной версии, основной или в обеих.
• Дополнительный совет: если ошибка появляется только в основной версии, а стабильная версия работает корректно, используйте git bisect, чтобы найти конкретный коммит, который ввел ошибку.

Если вы просто хотите получить помощь с вашим проектом, попробуйте задать вопрос на Stack Overflow или GIS Stack Exchange вместо этого.

Внесение изменений в код

Рассмотрение патчей

Хотя мы с удовольствием принимаем патчи, мы также стремимся сохранить Leaflet простым, легковесным и максимально быстрым. Поэтому исправления ошибок, оптимизации производительности и небольшие улучшения, которые не добавляют много кода, имеют гораздо больше шансов быть принятыми быстро.Перед отправкой pull request с новой функцией проверьте, обсуждалась ли она уже на GitHub issues и задайте себе два вопроса:

1. Уверены ли вы, что эта новая функция важна достаточно, чтобы оправдать её присутствие в ядре Leaflet? Или будет ли она выглядеть лучше как плагин в отдельном репозитории?
2. Написана ли она простым и кратким образом, который не добавляет объёма кодовой базе?

Если ваша функция или улучшение API действительно было включено в основной репозиторий, пожалуйста, рассмотрите возможность отправки ещё одного pull request с соответствующим обновлением документации.

Настройка системы сборки

Система сборки Leaflet использует NodeJS. Чтобы настроить систему сборки Leaflet, установите NodeJS. Затем выполните следующие команды в корневой директории проекта для установки зависимостей:

npm install

или, если вы предпочитаете yarn вместо npm:

yarn install

Внесение изменений в исходный код Leaflet

Если вы ещё не знакомы с тем, как работает GitHub (форкирование, pull requests и т.д.), не забудьте ознакомиться с отличной статьей о форкировании на сайте помощи GitHub — это поможет вам быстро начать работу.Вы всегда должны писать каждую порцию изменений (функцию, исправление ошибки и т.д.) в своей собственной тематической ветке. Пожалуйста, не коммитите изменения в ветку main вашего форка — иначе ваши не связанные изменения будут включены в один и тот же pull request.Вы также должны следовать стилю кода и соглашениям о пробелах оригинальной кодовой базы. В частности, используйте табуляцию для отступов и пробелы для выравнивания.

Перед тем как сделать коммит, выполните команду npm run lint, чтобы найти и исправить любые ошибки в коде. Эта же команда автоматически выполняется при коммите. Вы можете предотвратить её выполнение с помощью флага --no-verify: git commit -m "WIP" --no-verify.

Также убедитесь, что вы правильно настроили конфигурацию строковых концов в Git! В противном случае diff покажет, что все строки файла были изменены, даже если вы изменили только одну. Счастливого кодирования!

Использование RollupJS

Исходный JavaScript-код для Leaflet состоит из нескольких десятков файлов, расположенных в директории src/. Но обычно Leaflet загружается в веб-браузере как один JavaScript-файл.

Чтобы создать этот файл, выполните команду npm run build или yarn run build.

Вы найдете файлы dist/leaflet-src.js и dist/leaflet.js. Разница заключается в том, что dist/leaflet-src.js содержит карты исходного кода и не утюжен, поэтому он лучше подходит для разработки. Файл dist/leaflet.js утюжен и поэтому меньше по размеру, что делает его лучше для развертывания.При разработке (или устранении ошибок) основных функций Leaflet часто используются веб-страницы в директории debug/, а также выполняются юнит-тесты (spec/index.html) в графическом браузере. Это требует быстрого перегенерирования связанных файлов.Чтобы это сделать, выполните команду npm run watch или yarn run watch. Это будет продолжать перестраивать связанные файлы каждый раз, когда изменяется исходный файл.

Выполнение тестов

Чтобы выполнить тесты из командной строки, установите Google Chrome, затем выполните:

npm test

Чтобы выполнить тесты в других браузерах одновременно, вы можете выполнить:

npm test -- -- --browsers Firefox,Chrome,Safari,IE

(Примечание: удвоение "--" специального параметра является важным)

Чтобы выполнить тесты вручную в браузере, откройте spec/index.html.

Улучшение документации

Код живого веб-сайта Leaflet, содержащего всю документацию и примеры, расположен в директории docs/ ветки main и автоматически генерируется из набора HTML и Markdown файлов с помощью Jekyll.

Самый простой способ внесения небольших улучшений, таких как исправление опечаток, без необходимости покидать браузер, — это редактирование одного из файлов с помощью встроенного редактора GitHub: просмотрите директорию docs/, выберите файл для редактирования, нажмите кнопку "Edit", внесите изменения и следуйте инструкциям. После слияния изменения сразу появятся на сайте.Чтобы работать с документацией локально, убедитесь, что у вас установлена Ruby. Вы можете скачать её с сайта Ruby или использовать rbenv (рекомендуется). Для установки той же версии Ruby, что указана в .ruby-version, если вы используете rbenv, выполните команду rbenv install из директории docs/.Если вам нужно сделать правки в локальном репозитории, чтобы увидеть, как это выглядит в процессе, выполните следующие шаги:

1. Откройте терминал в директории docs/.
2. Убедитесь, что вы на ветке main, выполнив команду git checkout main.
3. Выполните команду bundle install, чтобы установить зависимости.
4. Выполните команду npm run serve, чтобы запустить документацию.
5. Откройте http://localhost:4000 в вашем веб-браузере.

Теперь любые изменения в файлах в docs/ будут применяться при перезагрузке страниц. После коммита изменений отправьте pull request.

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

С версии Leaflet 1.0.0-rc1 документация API в файле reference-1.0.0.html обрабатывается с помощью Leafdoc. Это означает, что для каждого метода, опции или свойства в коде есть специальный комментарий, документирующий эту функцию. Чтобы редактировать документацию API, просто измените эти комментарии в исходном коде.

Для генерации документации убедитесь, что установлены разработочные зависимости (выполните либо npm install, либо yarn install), затем выполните команду

npm run docs

и вы найдете файл .html в директории dist/.

При каждом выпуске новой версии Leaflet этот файл будет генерироваться и копироваться в docs/reference.html - нет необходимости отправлять pull request с изменениями в этот файл для обновления документации API.## Код поведения

Все приглашаются участвовать в сообществе Leaflet и связанных проектах: мы хотим создать дружественную и приветливую среду. Харассмент участников или другое недопустимое поведение не будет терпимо в наших пространствах. Код поведения участников применяется ко всем проектам под организацией Leaflet. Сообщите о любых проблемах на адреса agafonkin@gmail.com или ivan@sanchezortega.es.

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

Ваш вклад в Leaflet и его сообщество не только заслуживает благодарности, но и делает вас вдохновляющим человеком. Присоединяйтесь к этому одобренному списку вдохновляющих людей и помогайте нам расширять границы возможного с онлайн-картами!