Наиболее досадной ошибкой неопытных соавторов является сборка архивов, которые распаковывают файлы и каталоги дистрибутива в текущий каталог, что связано с потенциальной возможностью перезаписи имеющихся в нем файлов. Такой подход не рекомендуется.
Вместо этого следует убедиться, что все архивные файлы имеют общий каталог, который назван именем проекта, для того чтобы они распаковывались в один каталог верхнего уровня непосредственно в текущем каталоге. Традиционно имя каталога должно быть таким же, как именная часть архива. Например, предполагается, что архив с именем fоо-0.23.tar.gz распаковывается в подкаталог fоо-0.23.
В примере 19.1 демонстрируется решение для make-файла, которое позволяет реализовать указанный принцип в предположении, что каталог дистрибутива называется "foobar", a SRC содержит список файлов дистрибутива.
foobar-$(VERS) .tar.gz:
@ls $(SRC) | sed s:^:foobar-$(VERS)/: >MANIFEST
@(cd ..; ln -s foobar foobar-$(VERS))
(cd ..; tar -czvf foobar/foobar-$(VERS).tar.gz `cat foobar /MANIFEST`)
@(cd ..; rm foobar-$(VERS))
19.2.4.2. Включайте в дистрибутив README-файл
В дистрибутив программы следует включать файл README, который является путеводителем по дистрибутиву. Согласно давнему соглашению (созданному самим Деннисом Ритчи до 1980 года, и распространенному в Usenet в начале 1980-х годов), данный файл является первым файлом, который будут читать бесстрашные исследователи, после того как распакуют исходный код.
README-файлы должны быть короткими и легко читаемыми. Они должны быть вводным документом, а не крупным произведением. Рассмотрим пункты, которые рекомендуется включать в README-файлы.
1. Краткое описание проекта.
2. Ссылка на Web-сайт проекта (если он существует).
3. Примечания по среде разработки и потенциальным проблемам переносимости.
4. Схема проекта, описывающая важные файлы и подкаталоги.
5. Инструкции по компиляции/установке или ссылка на файл, содержащий такие инструкции (обычно INSTALL).
6. Список кураторов/благодарностей или ссылка на содержащий его файл (обычно CREDITS).
7. Последние новости проекта или ссылка на содержащий их файл (обычно NEWS).
8. Адреса списков рассылки проекта.
В свое время данный файл обычно назывался READ.ME, однако с таким именем плохо взаимодействуют браузеры, которые слишком склонны интерпретировать файл с суффиксом .ME как нетекстовый и позволяют только загружать его, а не просматривать. Такой подход устарел и уже не рекомендуется.
19.2.4.3. Придерживайтесь стандартной практики именования файлов
Еще до просмотра README-файла бесстрашный исследователь внимательно изучит имена файлов в корневом каталоге распакованного дистрибутива. Имена файлов в нем сами по себе способны нести полезную информацию. Соблюдая определенные стандартные принципы наименования, разработчик может дать исследователю ценную подсказку о том, "куда смотреть дальше".
Ниже приведены некоторые стандартные имена файлов верхнего уровня, а также описания соответствующих файлов. Не каждый дистрибутив нуждается во всех перечисленных файлах.
README
Файл-путеводитель, который прочитывают первым.
INSTALL
Инструкции по конфигурированию, компиляции и установке.
AUTHORS
Перечень участников проекта (GNU-соглашение).
NEWS
Последние новости проекта.
HISTORY
История проекта.
CHANGES
Перечень значительных изменений между различными редакциями.
COPYING
Лицензионные условия проекта (GNU-соглашение).
LICENSE
Лицензионные условия проекта.
FAQ
Текстовый документ с перечнем часто задаваемых вопросов по проекту.
Следует отметить существование общего соглашения, согласно которому имена файлов, набранные в верхнем регистре, содержат метаинформацию о проекте и предназначены для чтения людьми, а не являются компонентами сборки. Данное уточнение файлов README было давно разработано Фондом свободного программного обеспечения.
Наличие файла FAQ может предотвратить множество неприятностей. Когда какой-либо вопрос по проекту встречается часто, его следует поместить в список часто задаваемых вопросов, после чего предложить пользователям прочесть данный файл, прежде чем отправлять свои вопросы или отчеты об ошибках. Хорошо организованный FAQ-файл способен на порядок или больше снизить нагрузку по поддержке, которая лежит на кураторах проекта.