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

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

Во-первых, огромное спасибо за интерес к пакету! ✨

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

Обсуждения

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

Кроме того, существует раздел с демонстрациями, в котором вы можете рассказать о своей работе с FuzzyLogic.jl. Если ваша работа связана с новым применением FuzzyLogic.jl и вы хотите, чтобы оно также было представлено в разделе «Приложения» в документации, сообщите нам об этом (в чате или в описании проблемы). Вам помогут с рабочим процессом и настройкой, но делать записи вы будете сами 😃.

Открытие проблем

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

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

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

Если вам кажется, что ваша проблема не подходит ни под один из вышеперечисленных шаблонов (например, вы просто хотите что-то спросить), можно также открыть пустую проблему.

Рекомендации по сотрудничеству

Мы следуем руководству ColPrac с рекомендациями по сотрудничеству. Новые участники должны обязательно прочитать это руководство. Ниже приведены некоторые дополнительные рекомендации, которых мы придерживаемся.

Рабочий процесс Git

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

Настройка

1. Клонируйте репозиторий

git clone https://github.com/lucaferranti/FuzzyLogic.jl.git

и войдите в него с помощью команды

cd FuzzyLogic.jl

С этого момента в этих инструкциях предполагается, что вы находитесь в папке FuzzyLogic.jl.

2. Создайте вилку этого репозитория.

3. Добавьте вилку в качестве удаленной с помощью команды

git remote add $new_remote_name $your_fork_link

например

git remote add johndoe https://github.com/johndoe/FuzzyLogic.jl.git

после этого при выполнении git remote -v должен быть получен следующий результат:

lucaferranti  https://github.com/lucaferranti/FuzzyLogic.jl.git (fetch)
lucaferranti  https://github.com/lucaferranti/FuzzyLogic.jl.git (push)
johndoe        https://github.com/johndoe/FuzzyLogic.jl.git (fetch)
johndoe       https://github.com/johndoe/FuzzyLogic.jl.git (push)

Работа с ветвями

0. Выполните команду git branch и убедитесь, что вы находитесь в ветви main. Если это не так, переключитесь на main с помощью

git switch main

Затем убедитесь, что ваша локальная версия обновлена, выполнив команду

git fetch origin
git merge origin/main

1. Создайте новую ветвь с помощью команды

git switch -c $new-branch-name

3. А теперь начнем! Исправляйте ошибки, добавляйте новые функции, изменяйте документацию — и это будет круто!

4. Когда будете готовы, перейдите в главный репозиторий пакета (не в вашу вилку!) и откройте запрос на вытягивание.

5. Если в течение 7 рабочих дней ничего не произойдет, пишите Луке Ферранти (@lucaferranti) каждые 1−2 дня, пока не привлечете его внимание.

Рекомендации по написанию кода

  • Для этого пакета действует руководство по стилю SciMLStyle.

  • Вы можете запускать тесты локально из REPL Julia с помощью команды

include("test/runtests.jl")

  • Каждый файл теста является автономным, поэтому можно запускать и отдельные файлы, например include("test/test_parser.jl").

  • Для упрощения поиска тестов структура папок с тестами должна (примерно) отражать структуру папки src.

Работа над документацией

Локальная настройка

Когда вы в первый раз начнете работать над документацией локально, вам нужно будет установить все необходимые зависимости. Для этого выполните команду

julia docs/setup.jl

Это нужно сделать только в первый раз (если у вас нет docs/Manifest.toml) или делать каждый раз при устаревании манифеста.

Далее вы можете собрать документацию локально, выполнив команду

julia docs/liveserver.jl

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

Работа с literate.

  • Руководства и приложения написаны с использованием Literate.jl. Поэтому не редактируйте напрямую файлы Markdown, расположенные в папке docs/src/tutorials и docs/src/applications, а редактируйте соответствующие файлы Julia, расположенные в папке docs/src/literate.

Дополнительные материалы

Вот список полезных ресурсов для участников разработки.