Introduction
Role models are important.
This Packaging style guide outlines the recommended best practices for real-world programmers to write code that can be maintained both, upstream and downstream.
You can generate a PDF copy of this guide using AsciiDoctor PDF, and an HTML copy with AsciiDoctor using the following commands:
# Generates README.pdf
asciidoctor-pdf -a allow-uri-read README.adoc
# Generates README.html
asciidoctor README.adoc
Tip
|
Install the
|
Tip
|
RuboCop, a static code analyzer (linter) and formatter,
has a |
How To Read This Guide
The guide is separated into sections based on the different cops that the Packaging extension provides. There was an attempt to explicitly mention everything so if anything is still unclear, feel free to open an issue asking for further clarity.
A Living Document
This guide is a work in progress - existing guidelines are constantly being improved, new guidelines are being added, and occasionally some guidelines would get removed.
Why Packaging Extension?
The Debian Ruby team has a lot of experience in packaging and maintaining Ruby libraries and applications for Debian. During this work, they identified several issues in upstream codebases that make it difficult to build a Debian package straight out of those Ruby gems (shipped via rubygems).
The Debian developers (downstream maintainers) have been in touch with the RubyGems and other upstream maintainers and we’re collaborating to try to make things easier for OS packagers while not compromising the experience for upstream maintainers.
As a result, we’ve come up with this style guide, mentioning the best practices that upstream gem and project maintainers can follow to make the lives of packagers easier.
Source Code Layout
Using git in gemspec
Avoid using git ls-files
to produce lists of files. Downstreams (OS packagers) often
need to build your package in an environment that does not have git (on purpose).
Instead, use some pure Ruby alternatives, like Dir
or Dir.glob
.
Rationale
Packages in Debian are built in a clean environment (sbuild,
schroot, et al) and whilst doing so, the build fails with:
Invalid gemspec in [<gem_name>.gemspec]: No such file or directory - git
And adding git
as a dependency for each of the Ruby packaging is something that is not right
and definitely not recommended. Besides, the source package consists of released tarballs
(usually downloaded from GitHub/GitLab releases page or converted from the .gem
file,
obtained using gem fetch foo
), which is extracted during build. So even if we add git
as
a build dependency, it would still fail as the Debian package source tree is not a git repository.
Even when the package is maintained in git, it is uploaded as tarballs to the archive without
any version control information.
Therefore, the best way forward here is to patch out the usage of git
and use some plain Ruby
alternatives like Dir
or Dir.glob
or even Rake::FileList
whilst doing the Debian
maintenance.
There’s not only Debian or other OS packaging situation/examples, but also a couple of others, for instance:
-
ruby-core
as part of their CI system runs their test suite against an unpackaged Ruby tarball which doesn’t have a.git
directory. That means they needed to overwrite the bundler gemspec to not use git.
Actually, not anymore, since git has been removed from bundler’s gemspec. -
If you build your application on a bare docker image without git, and you are pointing to a git sourced gem that uses git on its gemspec, you’ll get:
No such file or directory - git ls-files (Errno::ENOENT)
warnings all around. For example, if you use this in your Gemfile:
gem "foo", git: "https://github.com/has-git-in-gemspec/foo"
Originally, git ls-files
inside the default gemspec template was designed so that users
publishing their first gem wouldn’t unintentionally publish artifacts to it.
Recent versions of bundler won’t let you release if you have uncommitted files in your
working directory, so that risk is lower.
# bad
Gem::Specification.new do |spec|
spec.files = `git ls-files`.split("\n")
end
# good
Gem::Specification.new do |spec|
spec.files = Dir["lib/**/*", "LICENSE", "README.md"]
end
# bad
Gem::Specification.new do |spec|
spec.files = Dir.chdir(File.expand_path(__dir__)) do
`git ls-files -z`.split("\\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
end
end
# good
require "rake/file_list"
Gem::Specification.new do |spec|
spec.files = Rake::FileList["**/*"].exclude(*File.read(".gitignore").split)
end
# bad
Gem::Specification.new do |spec|
spec.files = `git ls-files -- lib/`.split("\n")
spec.executables = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
end
# good
Gem::Specification.new do |spec|
spec.files = Dir.glob("lib/**/*")
spec.executables = Dir.glob("bin/*").map{ |f| File.basename(f) }
end
Using require_relative from test code into lib/
Avoid using require_relative
with relative path from your test code (spec/ or tests/)
to lib/. Use require
instead.
Rationale
Debian has a testing infrastructure that is designed to test packages
in their installed form, i.e., closer to how an end-user would use it than to how a developer
working against it. For this to work, the test-suite must load code that’s installed
system-wide, instead of the code in the source tree. Using require_relative
from the tests
into the lib
directory makes that impossible, but it also makes the test look less like
client-code that would use the code in your gem. Therefore, we recommend that test code uses
the main library code without require_relative
.
Therefore, when one uses a relative path, we end up getting a LoadError
, stating:
cannot load such file — /[PKGBUILDDIR]/foo
.
We want to emphasize that there is nothing wrong with using require_relative
inside lib/
,
it’s just using it from your test code to the lib
directory prevents the "test the library
installed system-wide" use case.
Therefore, it is still recommended to use require_relative
with just this exception to it.
# bad
require_relative "lib/foo"
# good
require "foo"
# bad
require_relative "../../lib/foo/bar"
# good
require "foo/bar"
# good
require_relative "foo/bar/bax"
require_relative "baz/qux"
Contributing
The guide is still a work in progress - new cops are being added, existing ones are being refactored. And whilst doing so, some bits might need a little more polishing and paraphrasing to make things clearer. Improving such guidelines is a great (and simple way) to help the Ruby community!
Also, nothing written in this guide is set in stone. We desire to work together with everyone interested in Ruby coding style, so that we could ultimately create a resource that will be beneficial to the entire Ruby community!
Feel free to open issues or send pull requests with improvements. Thanks in advance for your help!
How to Contribute?
It’s easy, just follow the contribution guidelines below:
-
Fork packaging-style-guide on GitHub.
-
Make your feature addition or bug fix in a feature branch.
-
Include a good description of your changes.
-
Push your feature branch to GitHub.
-
And finally, send a pull request.
License
This work is licensed under a Creative Commons Attribution 3.0 Unported License.
Spread the Word
A community-driven style guide is of little use to a community that doesn’t know about its existence. Tweet/toot about the guide, share it with your friends and colleagues. Every comment, suggestion, or opinion we get, makes the guide a little bit better. And we want to have the best possible guide, don’t we?
Credits
This guide has been put together with the help of our experienced Ruby team in Debian. So a huge thanks to all of them and their work. Particularly, Utkarsh Gupta and Antonio Terceiro, who have helped a lot in putting all this together in the best possible way!
And also a huge thanks to Dana Sherson for her help in putting together the inital scaffolding and to David RodrÃguez, an upstream maintainer of Bundler and RubyGems, for collaborating on this and extending his help to try to make things easier for OS packagers while not compromising the experience for upstream maintainers (which is very important!).