Лучшие практики для записи [закрытого] Java с открытым исходным кодом

См. Книгу Карла Фогеля http://producationoss.com/ - источник доступен в Интернете.

Я не уверен, будет ли достигнуто всеобщее согласие относительно «лучших практик», но на упомянутые вами вопросы могут быть простые ответы:

1. Распространение легко с помощью java.net или Sourceforge. Вы опубликуете свой код, используя их стандарты,
2. Упаковка будет в виде ZIP-файлов. Хорошая идея - создать хэш MD5, чтобы клиенты могли проверять целостность своих загрузок.
3. Документация - да, много, пожалуйста. Имейте отдельные javadocs и справочное руководство, показывающее, как использовать ваши материалы.
4. Имейте общедоступный SVN, который разрешает анонимный доступ, чтобы люди могли получать и создавать последний код самостоятельно.
5. Имейте трекер ошибок, который позволяет людям сообщать об ошибках, новых функциях и т. д.
6. Настроить вики для обсуждения, обратной связи и т. д.
7. Maven стал чем-то вроде стандарта с открытым исходным кодом. Хорошего вам помпа.

Я не добавляю так много, но я бы предложил следующее:

Структура каталогов

• Попытайтесь сделать javadocs полными, у большинства модулей или библиотек с открытым исходным кодом их мало комментарии javadoc. Создайте документацию javadocs и поместите ее в каталог, например apidocs . Если применимо в документации javadocs, вы должны указать, кому разрешено вызывать класс и при каких обстоятельствах следует вызывать класс / функцию. Небольшие примеры кода также не повредят, и их стоит добавить.
• Добавьте каталог «examples», чтобы помочь разработчики / пользователи используют / интегрируют ваш модуль.
• Добавьте файлы лицензии в корень вашу структуру каталогов и убедитесь что каждый ваш файл имеет лицензию заголовок.
• Добавьте файл README в корень каталог раздачи для общая информация и / или специфика (ссылка на программу, автор, помощь и поддержка, установка инструкции и т. д.)
• Обычно исходный код помещается в каталоги src, а документация - в папку docs.

Упаковка

• Попробуйте распространить свое программное обеспечение в соответствующих форматах (zip, tar.gz, dmg, exe , банка и т. д.). Например, для веб-приложения у меня были бы zip, tar.gz, war и, возможно, ухо. В зависимости от веб-сайта, на который вы будете загружать файлы, вам может потребоваться использовать формат архива, например zip.
• Создайте установщик, если это возможно, или не слишком утомительно

Публикация

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

• Рекламируйте свой модуль (блог, форумы, Twitter и т. д.)

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

Если вы ищете конкретные структуры каталогов, почему бы не взглянуть на существующие проекты с открытым исходным кодом? Я бы начал с Jakarta Commons , который является широко используемым пакетом.

Без какой-либо статистики, подтверждающей меня, я бы сказал, что во многих проектах используется структура каталогов, подобная той, что указана Maven, даже если они не используют сам Maven (и если вы сможете пройти кривую обучения Maven, это хороший инструмент для сборки в 90% случаев).

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

Лично я использую ant и определяю цель развертывания, которая выполняет следующие действия

2. Создает все артефакты
3. Упаковывает артефакты в единый доставляемый файл (файл .zip)
4. Распаковывает .zip в локальный каталог
5. 1254] Запускает набор тестов из этого локального каталога.
6. Загружает .zip на sourceforge

После этого единственный ручной шаг - определить новый выпуск через веб-сайт sourceforge.

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

Если ваш проект называется Foo, то версию XY следует упаковать в Foo-XYzip и разархивировать в Foo-XY / .... (другими словами, путь к каждому файлу в архив должен начинаться с Foo-XY /)

Имейте Foo-XY / README.txt, содержащий основные инструкции, в виде простого текстового файла. Он должен, по крайней мере, содержать информацию о том, где находится полная документация («документацию см. В docs / index.html»), а также краткие инструкции по использованию («добавить lib / Foo-XYjar в путь к классам») и инструкции по восстановлению («запустить "ant build" для восстановления библиотек в lib и javadoc в apidoc / ").

Если вашему проекту требуются дополнительные библиотеки для работы или компиляции, автоматизируйте это. То есть либо пусть это будет проект Maven, либо убедитесь, что он работает с Ant Ivy.

Я бы предложил разместить исходный код в src /,

Используйте Apache Maven 2 , и вы получите все необходимые артефакты ... с помощью простой команды "mvn package site"

Я бы порекомендовал SourceForge ( http://sourceforge.net ) для хостинга вашего проекта, поскольку у них есть широкий спектр инструментов (ведение блогов, вики, параметры управления исходным кодом, и т.д.), и все это бесплатно.

Что касается того, что помещать в zip / jar-архив ... это действительно зависит от типа проекта. Если это многоразовая библиотека, я бы посоветовал вам поместить в корне архива вашу лицензию и ваш дистрибутив jar. Вы можете поместить зависимости в подкаталог lib, а вашу документацию - в подкаталог docs.

Пример, вероятно, поможет вам лучше ... загрузите Jakarta Commons - Lang API ( http://commons.apache.org/lang ) и посмотрите, что они предоставляют.

Один из других ответов было использование Maven ( http://maven.apache.org ) для управления вашим проектом, и я также рекомендовал бы это,

Книга: Практическое признание дизайна API Java Framework Architec t (Ярослав Тулач, 2008, Apress).

Помимо советов в книге, пожалуйста, сделайте надлежащая документация (комментарии, javadocs) и включать примеры использования где-нибудь в открытом доступе (предпочтительно в стиле вики). Использование может быть очевидным для разработчиков, но не для клиентов (см. Пример JFreeChart).