Для некоторых огранка драгоценных камней считается искусством для склонных к минералам. Однако в мире Ruby огранка драгоценных камней — это вопрос жизни. Создание RubyGems может быть простым , но и ловушкой для новичка. Следуя некоторым общим рекомендациям сообщества, вы можете создавать драгоценные камни, которые могут жить в гармонии в экосистеме Ruby и пользоваться ими как потребителями, так и участниками в течение многих лет.
Используйте инструменты для разработки драгоценных камней
За исключением опытных резцов или тех, кто хочет или должен иметь полный контроль над каждой строкой кода, существуют инструменты для создания драгоценных камней, которые могут автоматизировать большую часть необходимой ручной работы и избежать любительских ошибок при публикации драгоценных камней для первых время.
Самый большой из инструментов для создания драгоценных камней на данный момент — это Jeweler ( RubyGems , GitHub ), цель которого — предоставить набор инструментов для автоматизации драгоценных камней на основе мастера. У него есть задачи для управления выпуском, версионированием, зависимостями, исполняемыми файлами и задачами Rake — все из коробки; в долгосрочной перспективе это может сэкономить время для частых или начинающих издателей драгоценных камней.
Используйте пути загрузки и require ответственно
Очень легко загромождать путь загрузки или require использования в Ruby без ущерба для этого. Фантастическая статья Джоша Пика в блоге Ruby on Rails детализирует все входы и выходы пути загрузки и требует , что стоит времени на чтение. Некоторые из наиболее важных пунктов его статьи:
- RubyGems (и большинство других менеджеров пакетов) добавляют каталог
lib/вашего гема в путь загрузки; в некоторых случаях это добавляется к пути загрузки. Если ваша директорияlib/содержит какие-либо файлы с такими же именами, что и любые основные файлы Ruby (например,string.rb), файл ваших драгоценных камней будет иметь приоритет. Таким образом, следуйте соглашению, чтобы хранить все ваши файлы в каталоге с именем, совпадающим с вашим гемом в вашей папкеlib/, например.lib/gem_name/something.rb. - Большинство менеджеров пакетов и тестовых сред автоматически добавят ваши
lib/и тестовые папки (spec/иfeatures/являющиеся двумя примерами) к пути загрузки. Если вы предоставляете исполняемый файл илиRakefile, вы можете добавить туда каталогlib/($:.unshift(path_to_lib)). В результате удалите код, используя такие вещи, какFile.dirname(__FILE__)рамках любых требований, поскольку вы можете смело предположить, что вы всегда можете требовать относительно вашей директорииlib/. -
Не зависите ни от чего, кроме папки
lib/вашего проекта (за исключением других гемов); некоторые менеджеры пакетов копируют только через ваш каталогlib/.
├── test_gem.gemspec ├── Gemfile ├── Rakefile ├── README ├── bin │ └── test_gem ├── lib │ ├── test_gem │ │ └── some_module_or_class.rb │ └── test_gem.rb └── spec/features/test └── *
Не требуйте рубинов внутри вашего драгоценного камня
Когда вы включаете в свой гем require 'rubygems' , вы отказываетесь от выбора пользователя использовать менеджер пакетов, отличный от RubyGems. Существует множество мощных и полнофункциональных альтернатив RubyGems, в том числе Rip ( RubyGems , GitHub ) и Dpkg (в основном используются системными администраторами, которым необходимо управлять гемами с помощью пакетов Debian).
Райан Томайко опубликовал блестящую статью в своем блоге под названием «Почему« требовать, чтобы «rubygems» было неправильно »» , в которой подробно описываются технические соображения и лучшие практики, которые следует исключить.
Используйте значимый шаблон управления версиями
Создание версий драгоценных камней может быть болезненным опытом, но это гора, которую покорили очень умные люди (несколько раз). Система семантического управления версиями стремится сделать управление версиями более предсказуемым и, следовательно, более безопасным, и ее можно применять к драгоценным камням с минимальными усилиями. Веб-сайт semver.org содержит подробную спецификацию, а также лучшие практики при создании версий программного обеспечения.
Некоторые важные моменты из спецификации:
- Версии должны быть в формате XYZ (Major.Minor.Patch).
- Вы можете использовать специальные номера версий при выпуске тестовых версий, например. 1.0.0beta1, 1.0.0alpha3, 1.0.0rc1.
- Вы можете вносить изменения в функции и исправлять ошибки в основных версиях.
- Вы можете вносить обратно совместимые изменения функций и исправлять ошибки в малых версиях.
- Исправления ошибок, совместимые с предыдущими версиями, можно делать только в версиях исправлений.
- API следует считать общедоступным и стабильным начиная с 1.0.0 и далее.
Используйте возможности Bundler для тестирования
Малоизвестный секрет Bundler заключается в том, что он может автоматически использовать зависимости в вашем файле .gemspec , предоставленные вручную или созданные инструментом gem, для создания Gemfile .
source :rubygems gemspec
Используя самый простой из Gemfile , вы можете распространять легко поддерживаемый Gemfile.lock и использовать bundle exec для Gemfile.lock тестовых прогонов и предотвращения конфликтов версий Gem.
Иметь достойный способ отслеживать проблемы публично
Создание драгоценного камня без каких-либо проблем является мифом. Однако, помня, что большинство пользователей любых созданных вами драгоценных камней также будут технически опытными, само собой разумеется, что у вас будут люди, которые готовы и желают предоставить необходимые детали для предоставления исправления.
Предоставление достойного способа отслеживания проблем кажется очевидным, но вы будете удивлены, насколько сложно найти место для отправки сообщений об ошибках, запросов к функциям или других проблем некоторым разработчикам гемов.
Если вы размещаете свой драгоценный камень на GitHub, вы получаете фантастический трекер проблем бесплатно. Некоторые люди предпочитают хостинг на таких вещах, как Lighthouse ; что бы вы ни выбрали, просто убедитесь, что он связан с README очевидным образом.
Сделать вклад легко
Касательно последней точки является идея о том, что внести вклад в драгоценный камень должно быть легко. Убедитесь, что у вас есть четкая лицензия, которая объясняет, что и как людям разрешено делать. Также постарайтесь сделать так, чтобы они внесли свой вклад в исходный код, предлагая четкие инструкции и ограничения, которые вы применяете к любому входящему исходному коду.
Размещение вашего кода на GitHub — это фантастический способ развить эту практику, поскольку Git упрощает работу с шаблоном fork-alter-merge, а GitHub оборачивает это в совершенство Pull Request.
GitHub имеет большой раздел справки о запросах на извлечение, который должен оказаться неоценимым для новичков в Git / GitHub.
Когда-то публично, оно остается публичным
После того, как вы опубликовали драгоценный камень, даже если вы совершили катастрофическую ошибку, он должен стать вашим последним средством для извлечения драгоценного камня. Еще более важно то, что, если вы обнаружите, что вам нужно выдернуть версию, ни при каких обстоятельствах вы не должны повторно использовать номер версии выдернутой копии.
Системные администраторы и разработчики в этом отношении во многом полагаются на то, что номера драгоценных камней неизменны и всегда доступны. Даже если вы добавили пароль или другую важную информацию о безопасности, которую вам нужно удалить, вам, вероятно, лучше просто сменить пароль (вам все равно придется это сделать) и опубликовать следующий выпуск.
Раздел справки в RubyGems содержит очень подробный набор инструкций по извлечению драгоценных камней, если вы по какой-то причине по-прежнему чувствуете, что вам необходимо использовать это право на оружие.
Наименование и регистр
Называние — это, вероятно, первое, что вы сделаете сами, и, возможно, один из самых важных шагов, которые вам нужно сделать, чтобы получить право.
Прежде чем вы настроитесь на конкретное имя, обязательно проверьте RubyGems.org и GitHub и убедитесь, что ваше имя не занято.
Есть некоторые общепринятые правила об обсадных колоннах, которые вы не должны нарушать, если у вас нет веских причин. Следующие правила применяются к имени драгоценного камня, а также к любым именам файлов внутри драгоценного камня:
- Нет заглавных букв. Это неизбежно вызовет проблемы у пользователей в Windows или OS X, которые по умолчанию используют файловые системы без учета регистра.
- Используйте подчеркивание для пробелов. Например, «Test Class» должен стать «test_class».
- Попробуйте сохранить один модуль или класс на файл и назовите файл после этого модуля или класса. Например, если файл содержит модуль с именем «EventGenerator», файл должен называться «event_generator».
Если вы будете следовать этим довольно простым правилам, людям вдруг станет намного проще делать предположения о том, как gem install , require и внести свой вклад в ваш код; небольшое усилие здесь проходит долгий путь.
Завершение
Итак, вы хотите создать свои собственные драгоценные камни? Следуя приведенным выше рекомендациям, вы, скорее всего, не будете наступать на пальцы своих предков. Многие очень умные, очень умные люди ответственны за то, чтобы сделать огранку драгоценных камней такой же простой, как сегодня, и в процессе они предлагают ценные инструменты и методы, которые требуют определенного уровня мастерства. Изучите эти инструменты, следуйте приведенным выше рекомендациям, и вы окажетесь на пути к созданию более безопасного, чистого и эффективного сообщества Ruby-кода.