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

Правила участия в разработке JuMP

В этом документе объясняются некоторые способы, с помощью которых вы можете внести свой вклад в разработку JuMP.

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

Данный проект и все его участники руководствуются Правилами поведения JuMP. Принимая участие в разработке, вы обязуетесь соблюдать эти правила.

Форум сообщества

Сначала присоединитесь к форуму сообщества.

Это полезный ресурс, где можно задавать вопросы касательно использования JuMP. На форуме можно также обсуждать возможные запросы функций и ошибки, прежде чем создавать проблему на GitHub (подробнее об этом см. ниже).

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

Чат разработчиков

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

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

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

Документы пишутся на языке Markdown и формируются с помощью Documenter.jl. Исходный код всей документации можно найти здесь.

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

Если же изменения более серьезные или затрагивают несколько файлов, то придется сначала внести их локально, а затем отправить запрос на вытягивание через Git. (Дополнительные сведения см. в разделе Contribute code to JuMP ниже.)

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

Отправка отчета об ошибке

Еще один способ внести вклад в развитие JuMP — отправлять отчеты об ошибках.

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

Если вы не уверены, действительно ли столкнулись с ошибкой, сначала напишите сообщение на форуме сообщества. Кто-нибудь либо поможет вам решить проблему, либо подскажет, где лучше всего опубликовать отчет об ошибке.

Добавление кода в JuMP

Наконец, вы можете также добавлять свой код в JuMP.

Если у вас нет опыта работы с Git, GitHub или разработки для Julia, первые шаги могут оказаться немного сложными. Однако в Интернете доступно множество руководств, в том числе следующие:

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

После того как вы освоите Git и GitHub, рабочий процесс добавления кода в JuMP будет происходить примерно так.

Шаг 1. Решите, над чем будете работать

Сначала нужно найти открытую проблему, которую вы хотите решить (или открыть новую). Затем, чтобы не тратить лишнего времени, обсудите планируемый способ ее решения, чтобы узнать, согласны ли другие участники с предлагаемыми вами изменениями. Получение отзывов на ранних этапах позволит улучшить качество кода и сэкономить время на написании кода, который не будет включен в JuMP.

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

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

Перейдите в репозиторий https://github.com/jump-dev/JuMP.jl и нажмите кнопку Fork (Создать вилку) в правом верхнем углу. В результате в вашей учетной записи GitHub будет создана копия репозитория JuMP.

Шаг 3. Установите JuMP локально

Откройте Julia и выполните следующую команду:

] dev JuMP

В результате репозиторий JuMP Git скачается в папку ~/.julia/dev/JuMP. В Windows это будет папка C:\\Users\\<my_name>\\.julia\\dev\\JuMP.

] command означает, что сначала нужно ввести символ ], чтобы войти в режим pkg в Julia, затем ввести все остальное. Не копируйте код напрямую.

Шаг 4. Извлеките новую ветвь

В следующих командах замените GITHUB_ACCOUNT во всех местах на свое имя пользователя GitHub.

Далее необходимо извлечь ветвь разработки. В терминале (или командной строке в Windows) выполните следующие команды:

$ cd ~/.julia/dev/JuMP

$ git remote add GITHUB_ACCOUNT https://github.com/GITHUB_ACCOUNT/JuMP.jl.git

$ git checkout master

$ git pull

$ git checkout -b my_new_branch

Строки, начинающиеся с $, означают, что команду следует выполнить в терминале (или командной строке в Windows).

Шаг 5. Внесите изменения

Теперь внесите изменения в исходный код в каталоге ~/.julia/dev/JuMP.

При этом должны выполняться следующие требования.

  • Следуйте руководству по стилю (Style guide) и используйте JuliaFormatter.

  • Добавляйте тесты и документацию для любых изменений или новых функций.

После изменения исходного кода необходимо перезапускать Julia, чтобы изменения вступили в силу. Это лишние хлопоты, поэтому установите Revise.jl.

Шаг 6a. Протестируйте изменения кода

Чтобы проверить работоспособность ваших изменений, запустите набор тестов JuMP, открыв Julia и выполнив следующие команды:

cd("~/.julia/dev/JuMP")
] activate .
] test

Выполнение тестов может занять много времени (~10—​15 минут).

При использовании Revise.jl тесты также можно запустить, вызвав include: julia include("test/runtests.jl") Это может быть быстрее, если нужно повторять тесты несколько раз.

Шаг 6b. Протестируйте изменения документации

Откройте Julia и выполните следующие команды:

cd("~/.julia/dev/JuMP/docs")
] activate .
include("src/make.jl")

Формирование документации может занять много времени (~10 минут).

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

Шаг 7. Создайте запрос на вытягивание

После внесения изменений вы готовы к их отправке на GitHub. Выполните следующие команды.

$ cd ~/.julia/dev/JuMP

$ git add .

$ git commit -m "A descriptive message of the changes"

$ git push -u GITHUB_ACCOUNT my_new_branch

Затем перейдите на страницу https://github.com/jump-dev/JuMP.jl и следуйте появляющимся инструкциям, чтобы открыть запрос на вытягивание.

Шаг 8. Ответьте на комментарии

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

Чтобы ответить на комментарии, вернитесь к шагу 5, внесите необходимые изменения, протестируйте их на шаге 6, а затем сделайте новую фиксацию на шаге 7. Ваш запрос на вытягивание обновится автоматически.

Шаг 9. Очистка

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

$ cd ~/.julia/dev/JuMP

$ git checkout master

$ git pull

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