Проект Документирования 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', вы должны:
-
Сделать копию файла, который собираетесь менять. Если вы изменяете foo.xml, выполните
% cp foo.xml foo.xml.old Затем внесите ваши изменения в foo.xml
% vi foo.xml ... клац клац клац ... ... тестируем изменения, ищем опечатки, и тому подобное ...Делаем diff. Команда, это делающая:
% diff -ru foo.xml.old foo.xml > foo.diffЗдесь выполняется просмотр отличий между двумя файлами и запись этих отличий в файл foo.diff.
После этого вы можете послать foo.diff обратно в адрес проекта. Пошлите PR так, как это было описано выше, включив в тело письма файл foo.diff.
Проект Документирования FreeBSD