Руководство для участников разработки
TL;DR: Чтобы принять участие в разработке с помощью запросов на вытягивание, можно найти и просмотреть проблемы с метками wanted feature (требуемая функция) или good first issue (подходящая первая проблема) в репозиториях GitHub подпакетов DynamicalSystems.jl
Конечная цель DynamicalSystems.jl заключается в том, чтобы быть полезной библиотекой для ученых, работающих в области нелинейной динамики, и сделать нелинейную динамику доступной и воспроизводимой.
Естественно, чтобы достичь такой амбициозной цели, многие из нас должны приложить совместные усилия для совершенствования библиотеки. Принять участие в работе над библиотекой DynamicalSystems.jl можно разными способами.
-
Просто используйте ее. Если вы столкнулись с неожиданным поведением, просто сообщите об этом либо в нашем чате Gitter, либо на странице проблем DynamicalSystems.jl.
-
Предложите методы, которые, по вашему мнению, должны быть включены в нашу библиотеку. Для этого нужно открыть новую проблему с описанием метода, ссылками на статьи, где используется этот метод, и обоснованием причины включения этого метода.
-
Вносите изменения в код, решая проблемы. Легче всего справиться с проблемами, имеющими метку good first issue (подходящая первая проблема).
-
Вносите изменения в код, реализуя новые методы. Это самый замечательный способ внесения улучшений. В отдельных пакетах, формирующих DynamicalSystems.jl, есть множество проблем с тегом wanted feature (требуемая функция), которые могут помочь вам принять участие в разработке.
-
Вносите изменения в код, определяя новую предопределенную динамическую систему, которую вы сочли полезной.
Участие в написании кода
При написании кода необходимо иметь в виду следующие моменты.
-
В целом важна скорость реализации, но не настолько, как ясность реализации. Одним из краеугольных камней DynamicalSystems.jl является наличие понятного и читабельного исходного кода. К счастью, Julia позволяет получить не только идеально читаемый, но при этом еще и супербыстрый код ;) При необходимости добавьте комментарии к коду, чтобы пользователь, которому известен метод, мог сразу понять код.
-
Старайтесь разрабатывать общие, расширяемые функции, а не излишне специализированные для конкретного случая.
-
При работе со строками документации новых методов и систем следуйте соглашениям для строк документации DynamicalSystems.jl. В частности, в первом разделе должны кратко описываться функция, ее позиционные аргументы и возвращаемое значение. В следующем разделе
## Keyword Arguments
описываются ключевые слова. В следующем разделе## Description
при необходимости подробно описывается алгоритм. Наконец, необходимо привести ссылки на документы, имеющие отношение к методу. Чтобы получить представление, взгляните на строки документации поlyapunov
иlyapunovspectrum
.
Стиль строк документации
Строки документации — это самое важное в вашем запросе на вытягивание или коде. Главным приоритетом DynamicalSystems.jl является максимально возможное качество документации и полная прозрачность. Лучший способ достичь этого — использовать хорошие строки документации. В DynamicalSystems.jl рекомендуется структурировать строки документации приведенным ниже образом (эту же рекомендацию мы даем на семинаре Good Scientific Code Workshop).
-
Четкая сигнатура вызова в синтаксисе кода, включая ожидаемые типы входных данных, если необходимо. Сигнатура вызова должна содержать ТОЛЬКО самую важную информацию, а не подробно перечислять каждое ключевое слово.
-
Краткое описание функции
-
[Необязательно] Возвращаемое значение и тип, если они неочевидны.
-
[Необязательно] Ссылки на связанные функции, если это целесообразно.
-
[Необязательно] Список именованных аргументов, если таковые присутствуют в функции.
-
[Необязательно] Подробное обсуждение функциональности, если поведение функции имеет научное значение.
-
[Необязательно] Ссылки на соответствующие научные работы.
Синтаксис строк документации соответствует протоколу Documenter.jl. См. строку документации по функции Ляпунова и используйте ту же структуру.