Skip to content

Home

Jump to bottom
Jacob Burroughs edited this page Oct 28, 2026 · 12 revisions

Environment Setup

To manage the ruby debian package build, you must be working on an Ubuntu system or in an Ubuntu VM (https://multipass.run/ is a nice option for relatively lightweight VMs)

New Major Version - These were the steps followed for Ruby 3.3 -> 3.4

docker run -it --rm -v ~/.ssh:/root/.ssh:ro ubuntu:22.04 bash
apt update && apt install -y git-buildpackage rename nano
cd
git clone git@github.com:instructure/deb-ruby.git
cd deb-ruby
git config --global user.email "username@instructure.com" # replace it with your actual username
git config --global user.name "username" # replace it with your actual username
export DEBEMAIL="username@instructure.com" # replace it with your actual username
git switch --orphan upstream
git commit --allow-empty -m "Initial empty upstream branch"
git checkout master-3.3
git checkout -b master-3.4
./debian/newruby 3.4
# This will fail because of the error "error: unable to sign the tag" - but that's fine
nano debian/ruby3.4.postinst
# change 3.3 to 3.4
git add .
git commit -m "update debian/ruby3.4.postinst"
# next run the minor version upgrade steps which includes --no-sign-tags
gbp import-orig --pristine-tar --uscan --no-sign-tags --debian-branch=master-3.4
# etc...

New Minor Version

docker run -it --rm -v ~/.ssh:/root/.ssh:ro ubuntu:26.04 bash
apt update && apt install -y git-buildpackage rename nano
cd
git clone git@github.com:instructure/deb-ruby.git
cd deb-ruby
git config --global user.email "username@instructure.com" # replace it with your actual username
git config --global user.name "username" # replace it with your actual username
export DEBEMAIL="username@instructure.com" # replace it with your actual username

git checkout master-X.Y
git branch -f upstream HEAD
gbp import-orig --pristine-tar --uscan --no-sign-tags --debian-branch=$(git branch --show-current)
git checkout origin/$(git branch --show-current) .github
git commit -m "Restore .github"
gbp dch --debian-branch=$(git branch --show-current) --git-author -D focal --dch-opt='--vendor=ppa'
sed -i '1s/-1/-ppa1/' debian/changelog
git add debian/changelog
git commit -m "Bump changelog for $(sed -nr '1s/.*\((.*)-ppa1\).*/\1/p' debian/changelog)"
git push origin

  1. Checkout the master-X.Y branch

  2. Run gbp import-orig --pristine-tar --uscan --no-sign-tags --debian-branch=$(git branch --show-current), which will put the latest version of ruby on the tip of the branch

  3. Checkout the .github directory from the previous version on the branch, and commit it (Sadly there doesn’t seem to be a way to teach gbp to keep that directory) git checkout origin/$(git branch --show-current) .github && git commit -m "Restore .github"

  4. Run gbp dch --debian-branch=$(git branch --show-current) --git-author -D focal --dch-opt='--vendor=ppa' to generate a changelog entry, and edit the version number to be of the form -Nppa1 instead of `-N

  5. Push to github, and watch the github action that is triggered on push

  6. Watch the builds here: https://launchpad.net/~instructure/+archive/ubuntu/ruby-testing/+packages a. A hard refresh of the page may be needed to actually see the package building.

  7. As needed, address any build issues

    a. In some cases you may see a handful of test failures that seem timing related. In that case just retry the build and hope it gets assigned to a faster build runner; I have seen it take a few tries sometimes.

    b. You may see issues with debian/librubyX.Y.symbols; just apply the diff from the error to that file and the push up a new change

    c. Before pushing, always run gbp dch --debian-branch=master-X.Y --git-author -D focal --dch-opt='--vendor=ppa' to generate a new changelog entry. If the GH action hasn't uploaded yet, you can just bump the timestamp without incrementing the ppa version.

    d. Referring to the original debian source can be helpful: https://salsa.debian.org/ruby-team/ruby/-/tree/master/debian?ref_type=heads

    e. Refreshing patches can be done with quilt: https://wiki.debian.org/UsingQuilt

    f. If you see non-timing related test failures, check if anything needs to be excluded due to pre-existing reasons https://github.com/instructure/deb-ruby/tree/master-3.4/debian/tests/excludes

  8. Once the build is passing and published, create a docker container, add the PPA, and install the new version of ruby to make sure all is sane (more important for new major revisions, but doesn’t hurt for minor ones)

    docker run -it --rm ubuntu:22.04 bash
    apt update && apt install software-properties-common
    add-apt-repository ppa:instructure/ruby-testing
    apt update && apt install ruby3.4

a. irb; RUBY_VERSION
b. ruby --enable-yjit -v
c. rubyX.Y --enable-yjit -v

  1. Go to this page https://launchpad.net/~instructure/+archive/ubuntu/ruby-testing/+copy-packages, select the new package, select “ruby” as the “Destination PPA”, leave “rebuild the copied sources” selected, and select “Copy Packages”

  2. Again, watch the builds for success and retry as necessary

Clone this wiki locally