FreeBSD The Power to Serve

Проект Документирования FreeBSD: Посылка документации

Я написал некоторое количество документации. Как вам её послать?

Во-первых, спасибо, что вы нашли время и сделали это.

Вы должны сделать вашу документацию доступной для предварительного просмотра. Если это возможно, поместите её на FTP или веб-сервер.

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

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

Скорее всего, вы ещё понадобится сделать cc: этого запроса на комментарии в другие подходящие списки рассылки. Например, что-либо, относящееся к использованию CVSup для синхронизации дерева исходных текстов, будет интересно подписчикам списков рассылки FreeBSD-current и FreeBSD-stable.

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

Чтобы сделать это, заархивируйте её в один tar-файл. Если ваша документация состоит из трех файлов, one, two и three, а вы хотите получить их в виде doc.tar, сделайте следующее:

% tar cf doc.tar one two three

Затем выполните сжатие tar-файла:

% gzip -9 doc.tar

в результате чего появится doc.tar.gz.

И, наконец, перекодируйте файл в вид, который подходит для передачи через любую программу электронной почты.

% uuencode doc.tar.gz doc.tar.gz > doc.uue

Теперь дайте знать о нём группе Проекта Документирования. Правильным способом сделать это является использование программы send-pr, которая должна иметься на вашей машине.

Вы делаете это для того, чтобы ваше послание могло быть отслежено. Когда вы оформляете PR (Problem Report - сообщение о проблеме), ему назначается уникальный номер. Один из коммиттеров может затем направить PR себе, и установить с вами связь по поводу включения новой документации в систему.

send-pr сама по себе очень проста. Все, что она делает - это посылка электронной почты, оформленной особым образом, на определенный адрес. Когда вы запускаете send-pr, вы оказываетесь в текстовом редакторе (вероятнее всего, vi или emacs) с бланком для заполнения и некоторыми инструкциями по заполнению.

Удостоверьтесь, что пункт "Category" установлен в "docs", а в строчке "Class" фигурирует только лишь "change-request". Вы должны включить в это PR ранее созданный файл .uue.

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

Я сделал некоторые изменения и исправления в существующей документации, как вам их послать?

Мы снова благодарим вас за то, что вы потратили на это время.

Прежде всего вам нужно сгенерировать особый файл, называемый diff. В этом diff-файле содержатся только изменения, которые вы внесли. Это облегчает персоне, выполняющей внесение изменений в систему, просмотр ваших изменений, что означает ненужность траты массы времени на объяснения, что конкретно было изменено (хотя вы должны будете объяснить, почему эти изменения так необходимы).

Чтобы сделать 'diff', вы должны:

  1. Сделать копию файла, который собираетесь менять. Если вы изменяете foo.xml, выполните

    % cp foo.xml foo.xml.old
  2. Затем внесите ваши изменения в foo.xml

    % vi foo.xml
    ... клац клац клац ...
    
    ... тестируем изменения, ищем опечатки, и тому подобное ...
  3. Делаем diff. Команда, это делающая:

    % diff -ru foo.xml.old foo.xml > foo.diff

    Здесь выполняется просмотр отличий между двумя файлами и запись этих отличий в файл foo.diff.

После этого вы можете послать foo.diff обратно в адрес проекта. Пошлите PR так, как это было описано выше, включив в тело письма файл foo.diff.


Last modified on: 19 июня 2021 г. by Danilo G. Baio