Вклад в iText 7 Community

Мы были бы крайне признательны, если бы вы внесли свой вклад в наш исходный код и сделали iText 7 Community еще лучше, чем сейчас! Вот рекомендации, которых вам следует придерживаться:

Вклад в iText 7 Community

Появился вопрос или затруднение?

Если у вас есть вопросы об использовании iText 7 Community, вы можете задать их на Stack Overflow.

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

Обнаружили проблему?

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

См. указания по представлению ниже.

Хотите реализовать функцию?

Если вы хотите реализовать новую функцию, то укажите, к какому типу относится это изменение:

  • Значительные изменения, которые вы хотите внести в проект, следует сначала обсудить, чтобы мы могли лучше скоординировать наши усилия, предотвратить дублирование работ и помочь вам в создании изменения таким образом, чтобы оно было успешно принято в проект. Свяжитесь с нами по адресу электронной почты community@itextpdf.com.

  • Незначительные изменения могут быть созданы и отправлены в репозиторий GitHub в качестве запроса на изменение.

Указания по представлению

Представление вопроса или проблемы

Перед представлением вопроса или проблемы выполните поиск на Stack Overflow, возможно, на ваш вопрос уже дан ответ.

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

  • Как задавать хорошие вопросы

  • Обзор проблемы – при возникновении ошибки помогает полная трассировка стека

  • Мотивация или сценарий использования – поясните, почему вы считаете, что это ошибка

  • Версии iText – это регрессия?

  • Операционная система – проблема возникает в Windows или Linux, возможно, на Mac?

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

  • Связанные проблемы – было ли зафиксировано ли возникновение аналогичной проблемы раньше?

  • Предложить исправление – если вы не можете исправить ошибку самостоятельно, возможно, вы сможете указать на возможную причину проблемы (строку кода или фиксацию)

  • Тегируйте вопрос – добавьте тег «itext7» к вашему вопросу, чтобы мы могли его найти.

Если вы получили ответ на свой вопрос, помогите другому пользователю. Хорошая карма рулит!

Представление запроса на изменение

Перед отправкой запроса на изменение учитывайте следующие рекомендации:

  • Выполните на GitHub поиск открытого или закрытого запроса на изменение, связанного с вашим представлением. Следует избегать создания дублей.

  • Убедитесь, что предлагаемое изменение еще не было рассмотрено в ветке разработки.

  • Не отправляйте отдельный запрос на изменение для каждого изменяемого вами файла.

  • Подпишите лицензионное соглашение вкладчика iText (iCLA) перед отправкой запросов на изменение для любого изменения более 20 значимых строк кода (мы не учитываем фигурные скобки и другой синтаксический сахар). Мы не можем принять код без этого соглашения.

  • Клонируйте iText 7 Community на локальный компьютер.

    git clone git@github.com:itext/itext7.git
    cd itext7
    git fetch origin
    git checkout -b develop origin/develop
    

    *Внесите изменения в новую ветку git, основанную на ветке разработки:

    git checkout -b my-fix-branch develop
    

    *Создайте исправление**, включая соответствующие тестовые сценарии**.

  • Соблюдайте наши Правила кодирования.

  • Выполните полный набор тестов iText 7 Community и убедитесь, что все тесты пройдены.

  • Зафиксируйте свои изменения с использованием описательного сообщения фиксации в соответствии с нашими соглашениями об сообщениях фиксации .

    git commit -a
    

    Примечание: дополнительный параметр командной строки «-a» будет автоматически использовать для редактируемых файлов команды «add» и «rm».

  • Теперь самое время исправить фиксации (по желанию или при необходимости) с использованием «git rebase --interactive».

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

  • Отправьте ветку на свою учетную запись GitHub:

    git remote add my-remote git@github.com:my-remote/itext7.git
    git push my-remote my-fix-branch
    
  • На GitHub отправьте запрос на изменение на «itext7: develop».

  • Если предлагаются изменения:

    • Внесите необходимые обновления.

    • Заново выполните набор тестов iText 7 Community, чтобы убедиться, что тесты по-прежнему проходят.

    • Перебазируйте вашу ветку и принудительно отправьте в ваш репозиторий GitHub (это обновит ваш запрос на изменение):

      git fetch origin
      git rebase develop -i
      git push my-remote my-fix-branch -f
      

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

После слияния вашего запроса на изменение

После слияния вашего запроса на изменение вы можете без опаски удалить ветку и извлечь изменения из главного (восходящего) репозитория:

  • Удалите удаленную ветку на GitHub через веб-интерфейс GitHub или локальную оболочку следующим образом:

    git push my-remote --delete my-fix-branch
    
  • Выгрузите ветку разработки:

    git checkout develop -f
    
  • Удалите локальную ветку:

    git branch -D my-fix-branch
    
  • Обновите вашу разработку с использованием новейшей восходящей версии:

    git pull --ff upstream develop
    

Правила кодирования

Для обеспечения единообразия исходного кода при работе всегда придерживайтесь следующих правил:

  • Сначала мы выполняем разработку в Java, а затем переносим на .NET, поэтому предпочтение отдается представлениям кода на Java. Тем не менее, это не должно мешать вам составить хороший запрос на изменение для платформы .NET.

  • Весь код Java обязательно должен быть написан на Java 7. Лямбда-выражения или другие особенности языка Java 8 не допускаются.

  • Все функции или исправления ошибок должны быть тестированы с использованием одного или нескольких [модульных тестов] (http://junit.org/).

  • Все общедоступные методы API должны быть документированы с помощью JavaDoc. Чтобы узнать, как мы документируем наши API, ознакомьтесь с доступными javadocs.

  • Мы соблюдаем правила, содержащиеся в Соглашениях по оформлению кода Oracle для языка программирования Java со следующими дополнениями:

    • Оберните код до 100 символов в одной строкев.

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

У нас есть рекомендации по форматированию наших сообщений о фиксации git. Это обеспечивает более удобочитаемые сообщения, которые легко отслеживать при просмотре истории проекта. Кроме того, мы используем сообщения о фиксации git для ведения журнала изменений iText 7 Community.

Эти рекомендации были взяты из публикации в блоге Криса Бимса «Как написать сообщение о фиксации Git» .

Формат сообщения о фиксации

Каждое сообщение фиксации состоит из темы, тела и нижнего колонтитула:

<subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

Любая строка сообщения о фиксации не должна превышать в длину 72 символа! Это позволяет сделать сообщение более удобочитаемым на GitHub, а также в различных инструментах git.

Тема

Тема содержит краткое описание изменения:

Тело

Нижний колонтитул

Нижний колонтитул содержит сведения о критических изменениях, а также место для ссылки, публикуемой JIRA или GitHub после закрытия фиксации.

Подписание iCLA

Подпишите лицензионное соглашение вкладчика iText (iCLA) перед отправкой запросов на изменение. Для принятия любых крупных изменений кода (больше 20 строк значимого кода) подписание iCLA является обязательным требованием. Это быстрый процесс, мы обещаем!

Вам необходимо подписать документ (цифровой подписью), а затем отправить по электронной почте, факсу или обычной почте форму .

Кодекс поведения вкладчика

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

Мы используем сеть Stack Exchange для бесплатной поддержки и GitHub для размещения кода. Используя эти службы, вы соглашаетесь соблюдать их условия: