How to help the Ruby-Team Maintaining Debian Packages

Content:

Helping the ruby-team upgrading packages maintained by the team or building new ones is always welcome. This document will try to give a short description of the general workflow for beginners.

If you are already an expert in Debian packaging and in using Git and salsa.debian.org, you may find the ruby-team pages in the Debian-Wiki more straight forward.

Communication

in the ruby-team mainly happens via *mailing list: debian-ruby@lists.debian.org. So it is a good start to subscribe this list.

There is also an IRC channel where team members hang around and where you may find help:

#debian-ruby on irc.debian.org (OFTC)

Basic knowledge

For this workflow description we assume that you are a little bit familiar with the Debian package management and have built one or another Debian package for personal use before. You should have had installed at least the packages

and you should have taken a closer look into the installed Documents

as well as into the Ruby pages of the Debian Wiki

It will also be useful to set your name and the email-address you want to use developing packages in your ~/bashrc (if you have not already done so):

DEBFULLNAME="your name"
DEBEMAIL=youremail@provider.com

All done? Then let’s get started!

Preparations Part I: Get ready to work with Git and Salsa

The packages maintained by the ruby team are developed using Git repositories at salsa.debian.org.

1.

At first you have to have installed Git itself and a suite to help with Debian packages in Git repositories:

sudo apt install git git-buildpackage pristine-tar cowbuilder python3-requests

Note: In case you have never worked with git before the small and free ebook Learning GIT from riptutorial.com may give you an impression how this version-management-system generally works. But of course there are other tutorials as well.

2.

Next you have to get yourself an account at salsa.debian.org. With this account you get personal webspace for your projects which you can access in Salsa’s web-interface at: https://salsa.debian.org/<your-user-name>.

Note: When you are logged in at salsa.debian.org you will find a dashboard menu on the left side of the page to interact with Salsa’s GitLab.

Normally you don’t want to work with the web-interface of Salsa but clone a repository from there to your local machine, work here and push your changes back to Salsa after you are done.

Especially when you are pushing code, Salsa needs to be sure that the machine you are working at is really yours (even if you may think it might be the other way round after days of work). Therefore you need to create a ssh-key (or use an existing one from ~/ssh/id_rsa.pub) and add the public-key to your Salsa account. Run:

ssh-keygen

to create an ssh-key, and upload the public key, which ends with .pub via Salsa’s web-interface: Go to User settings and choose ssh-keys in the left dash-bar.

If you picked a custom username for Salsa which differs from your username on your local machine you can add the following to ~/.ssh/config (if the file does not exist yet just create it):

host salsa.debian.org
User <your-salsa-username>
PreferredAuthentications publickey
IdentityFile ~/.ssh/<your_custom_name_git_rsa>

3.

To provide the possibility of direct interaction with Salsa’s GitLab API (which may be usefull at some point) you need to install the package libgitlab-api-v4-perl:

sudo apt install libgitlab-api-v4-perl

To make the command-line-client work with Salsa you have to create a personal access token on salsa via web-interface: Go to User settings, choose Access tokens in the left dash-bar, then choose with scope: api and copy the created token. Run:

gitlab-api-v4 configure

and add the token.

Note: You will NOT see your input! Use copy and paste! The configured token is stored in the file ~/.gitlab-api-v4-config.

Preparations Part II: Setting up the building and testing environment

If you built debian packages for personal use before you probably used something like dpkg-buildpackage or debuild on your local machine to build the source and binary packages.

Your daily used machine normally runs a stable Debian system, maybe testing or a mixture of both with some unstable packages. To build and test an official Debian package this needs to happen in an clean unstable environment. So you will have to build and test using chroots or lxc-containers.

1. ruby-meta

The ruby-team offers a set of scripts called meta to make setting up such an environment for building and testing a little bit easier for you. It is located in its own Salsa-repository: salsa.debian.org/ruby-team/meta.

Clone this repository to the local computer where you want to build and test packages:

git clone git@salsa.debian.org:ruby-team/meta.git meta

Enter the newly created directory meta, read the README.md and then create your building and testing environment by running the setup-script (which utilizes sbuild, autopkgtest and lxc to do so):

./setup

The script will install missing packages and therefore ask for your user password. It case the script fails, you have to install some missing packages by yourself and rerun the script. At the end the script informs you:

Finished testbed setup for unstable: <Date>

From now on you can use the build-script in meta repository from within your package’s local git repository to build and test in a clean environment.

2. lintian options

For testing the packages lintian should be called with some extra options to make its report more verbose and pedantic. For using the build script of ruby-team’s meta-repository you should make this options standard for sbuild by adding them to your ~/.sbuildrc:

# this enables all lintian tags:
$lintian_opts = ['-i', '-I', '-E', '--pedantic'];

And after all this preparations: You are finally ready to start your first project!

Case 1: Help upgrading an existing package

First of all: When you want to help upgrading an existing package make the debian-ruby team know about it by posting your intention at the debian-ruby mailing-list! It also helps to file a bugreport for the package about not being upgraded.

1. Fork existing GIT repository of the package

The git repositories of the packages maintained by the ruby-team are stored in https://salsa.debian.org/ruby-team/<package-name>.

As the ruby-team doesn’t know you and you don’t know them the easiest way to start your upgrade attempt will be to fork the ruby-teams repository of the package to your own namespace at Salsa. To do so, log in at salsa.debian.org, go to the ruby-teams package repository https://salsa.debian.org/ruby-team/<package-name> and click on the small Fork-Button on the upper right side of the page (beside the package name). Choose your own namespace as the one to fork to.

You can now work with this fork in your own namespace at https://salsa.debian.org/<yourname>/<package-name> without any fear of destroying something. After you are done you can make a merge request for the teams repository to get your changes back there.

2. Next clone (download) your Salsa Git repository to your local computer.

A debian package repository normally has a lot of tags and at least 3 branches:

The easiest way to get all these tags and branches cloned to your computer is to use gbp instead of git. Go to the location where you want to store the directory with your local git-tree of the package and run:

gbp clone --pristine-tar git@salsa.debian.org:<yourname>/<package-name>.git <package-name>

Then change to the newly created directory

cd <package-name>

and start your changes.

3. Import the new upstream version

This should be easy if the information in the debian/watch file still works. You can check if the new upstream version is found with:

uscan --no-download --verbose

If all works run:

gbp import-orig --pristine-tar --uscan

This will download the upstream source package and create a Debian source-package in the parent directory with uscan and then extract this source-package into the current directory and import it into the master branch. You can also run these two steps separately:

uscan --verbose
gbp import-orig --pristine-tar ../<package>_<new.version>.orig.tar.gz

Now update the debian changelog file to the new version:

gbp dch -a

and open the file debian/changelog with an text-editor of your choice. In the first line replace the word testing with UNRELEASED and as first entry of changes add * Team Upload. Then make git aware of this change by running:

git commit -a -m "set package as unreleased and team-upload"

Last, to update your remote Salsa repository you want to push all changes in all branches using gbp:

gbp push

or using git:

git push -u --all --follow-tags

4. Make all necessary changes in the debian-directory

Remember: All changes are only done in the debian-directory! Do not touch the upstream code! If you have to modify it, make patches using quilt. See:
Debian Wiki: Using Quilt,

New Maintainers’ Guide: Modifying the source
and last not least: Working with Patches to see how patches are managed with Git and gbp pq.

Normally all changes should be done in the master branch of the repository. To check which branch the directory-tree in front of you represents run:

git branch

the master should be highlighted. If it’s not change to master with

git checkout master

Git will then rebuild the tree to match the master branch.

When upgrading the package you have to check all files in the debian-directory, adjust at least the dates in the copyright-file and eventually existing patches. (In the later case check if there already exists a patch-queue branch in the repository of your package!) Also consult the upstream changelog to find out what might have changed in the upstream code that affects the packaging.

Whenever you have done all changes concerning a specific topic you should document your changes in the debian/changelog file and make git aware of your changes by running:

git commit -a -m "short description of your changes"

from within the main-directory of your git repository.

Note: You can also run the git-command without the -m option. In this case an editor (vi if not configured otherwise) will pop up to type in your description of the changes. If you give no description, the changes will not be recorded by git.
(To remind you of the essential vi commands: <I> or <INS> will put the program into input-mode, <ESC> will return to command-mode, :wq while in command-mode will save the changes and exit the program.)
You can change the editor used by Git by setting the GIT_EDITOR environment variable for your shell, or by configuring Git:
git config --global core.editor <my-editor>

Whenever you create a new file, you have to make git aware of this file:

git add debian/<newfile>

When you think you are done with all your changes or when you want to have a longer break you can push your local changes in the actual (master-)branch back to your remote Salsa repository with:

gbp push

To see what will happen, you may try first:

gbp push --dry-run

When you are working at more than one local machines or when you are working together with other people on the same remote repository every time you start working you have to make sure that the local git tree matches the remote one by running:

gbp pull --redo-pq

and you should push your changes whenever you want to change the local machine or pause working.

5. Building and testing the package:

The moment of truth: When you finally think you are done with all necessary changes in the debian directory you try to build the package and test it. If you followed the advices in Preparations Part II, you only need to run the build-script included in the ruby-teams meta repository from within the local git repository of the package you want to have built;

~/<path-where-you-cloned-meta>/build

The script will run the necessary commands to build (sbuild) and test (autopkgtest, lintian) the package and also will rebuild and test all packages (build-)dependening on the package you just built. The final part is essential when trying to build and upload a major upgrade of a package.

This build process will leave your local git repository unchanged, its products can be found in the directory build-area in the parent folder of your repository.

And of course something will go wrong! Maybe the package-building itself doesn’t work at all, some tests may fail or at least lintian will grumble about something. In all these cases you need to find the reason for the problem, go back to work on the files in the debian directory and try to fix the problem. If you are not sure how to do so: Never say die! Ask the debian-ruby mailing-list!

When you think you fixed all problems run the build-script again.

6. Merging to ruby-teams repository, fetching and merging back changes

When building and testing the package finally works, don’t forget to push your latest changes to your remote repository:

gbp push

Then you should brief the ruby-team that you have finished upgrading the package and create a merge request for your (remote) repository into the ruby-teams repository via Salsa’s web-interface: Log in, go to the teams repository of the package and choose Merge Requests on the left dashbar.

You have to create one merge requests for every branch you worked on since you forked the teams repository, which were: upstream, pristine-tar and master.

The team members will inspect the changes you made and may accept them, may change things by themselves or may want you to change things.

In any case before you start working on your repository again you have to make sure that it still matches the teams repository. Therefore you need to add the teams repository to yours:

git remote add team git@salsa.debian.org:ruby-team/<package-name>.git

so that is available for git under the name team. Check with:

git remote -v

You can now update your local repository and get the teams content by running:

git fetch --all

Note: This will not pull any changes to your repository, fetch only downloads objects and refs from another repository.

You can now check the changes between your master branch and the one in the team’s repository:

git diff master team/master

When there are changes in the team’s repository you should merge the team’s master branch into your master branch with:

git merge team/master

If something seems to go wrong you can always abort with:

git merge --abort

When the merging went well, you can push the changes to your remote repository:

gbp push

and start working on your repository again.

Case II: Preparing a new Package

The workflow in this case is very similar to the one described above for upgrading a package but the beginning is a little bit different: There is no remote repository to clone and start with.

So you have to create a new git repository for your package on your local machine first.

1. Debian package from a rubygems Package

In case you want to build a Debian package for a piece of software that is available at rubygems you can let gem2deb do most of the work. Go to the directory where you want your new git repository to be created and run:

gem2deb -p <debian-package-name> -g --purge <gem-Package>

This will run gem fetch <gem-Package> to download the package from rubygems, build a git-tree for the package, build the debian-source- and binary-packages, import the prestine-tar to git-tree and then delete all crap outside the git-tree. As result you have a git-tree with 3 branches:

and 2 tags:

Because on Salsa the debian tag is only set when a package is released you should remove this tag for now. Look up the name of the tag:

git tag

and remove it:

git tag -d debian/upstream-version>-1

2. Debian Package from an upstream Archive-File

In case the software you want to package is only available upstream as some gzip, bzip2, lzma or xz compressed tar archive or as zip archive you have to do a little more.

First check if the package python3-requests is installed on your system:

dpkg -l python3-requests

If it is not install it:

sudo apt install python3-requests

Then go to the directory where you want to store your local git-repository of the package and create a directory with the name of the debian package you want to build and change into it:

mkdir <package-name> && $_

Now place this directory under Git’s version control, i.e. make an empty Git repository:

git init

Next point your Browser to the site where the upstream archive can be downloaded and copy the link for the archive you want to use.

Then go back to your terminal and use gbp to download and import this archive to your empty git repository:

gbp import-orig --interactive --upstream-version=<upstream.program.version> --pristine-tar <https://place-your-copied-archive-url.here>

This lets gbp download the upstream archive, import it into your git directory, create and populate 3 branches master, upstream and pristine-tar and tag the upstream version.

Note: If the url you gave gbp to import is an url-redirect the above gbp-command will not work. In such a case you have to download the archive yourself, place it into the parent directory of you repository an run from within your repository:

gbp import-orig --interactive --upstream-version=<upstream.program.version> --pristine-tar ../<downloaded-archive.tar.xzy>

After the gbp-import you will notice that the debian directory and all the files in it are still missing in your repository.

So let’s create it:

mkdir debian

and let dh_make populate it with templates:

dh_make -p <package-name>_<version> --addmissing

dh_make asks you some questions about the package, chooses the templates to copy and writes a first entry into the copyright file.

Note: To avoid questions you can give dh_make more options. Namely -c <copyright-typ> might be interesting if you know the license typ of the program because dh_make does not ask for it.

After dh_make has populated the debian directory you have to make git aware of all the new files:

git add debian/.

and commit all changes:

git commit -a -m "create and and let dh_make fill the debian directory"

3. Creating the remote Salsa repository

Wether you have created your local git repository from a rubygem package or from an upstream archive before making any further changes in the debian directory you should setup your remote Salsa repository.

Point your browser to https://salsa.debian.org/<your-username>, log in and create a new project with the name of your new debian package via Salsa’s web-interface.

Then go back to your terminal and tell git that the created new and empty git repository at Salsa is your remote origin:

git remote add origin git@salsa.debian.org:<your-username>/<project-name>.git

and push your local repository to the remote:

gbp push

or:

git push -u --all --follow-tags

Now you can start …

4. working on the debian directory and all further tasks

Especially when you created your repository from an upstream archive, adjusting the files in the debian directory will be much more work than upgrading an existing package. You have to touch every single file, work on it or decide to delete it. You have to set dependencies and build-dependencies for the package, the description and so on. Check the upstream docs to get some of the information you need.

Sadly dh_make has no template files for ruby packages. You may want to have a look at other ruby repositories’ debian directories to get some ideas.

Nevertheless: Concerning the workflow with git and gbp is similar to upgrading a package: You have to commit your changes with comment:

git commit -a -m "short description of your changes"

You have to inform git of newly created files:

git add debian/<newfile>

And at the end of your work you have to push your changes to your remote repository:

gbp push

The same applies for building and testing the package: It is similar to upgrading an existing package.

Only getting your work finally into a ruby team’s repository will differ slightly: You cannot make a merge request, the team has to fork your repository into their namespace.

Troubleshooting

I cloned my local repository from the team’s repository instead of forking it into my namespace at Salsa. Now I can not push.

The easiest way to fix this would be to ask the team for membership.

If you don’t want to do so, you have to fork the team’s repository of you package to your namespace now and then tell git, that the repository in your namespace is the origin for your local repository.

First check the remote names:

$ git remote -v
origin	git@salsa.debian.org:ruby-team/<package-name>.git (fetch)
origin	git@salsa.debian.org:ruby-team/<package-name>.git (push)

then set the new origin:

git remote set-url origin git@salsa.debian.org:<your_username>/<package-name>.git

and add the team’s repository again under the name team, so that you can fetch changes froom there:

git remote add team git@salsa.debian.org:ruby-team/<package-name>.git

Now check again:

$ git remote -v
origin	git@salsa.debian.org:<your_username>/<package-name>.git (fetch)
origin	git@salsa.debian.org:<your_username>/<package-name>.git (push)
team	git@salsa.debian.org:ruby-team/<package-name>.git (fetch)
team	git@salsa.debian.org:ruby-team/<package-name>.git (push)

Instead of forking I imported the team’s repository into my namespace at Salsa. Now I can not make a merge request.

There are two possibilities to fix this:

Either you rename your remote repository, fork the team’s repository into your namespace (which will now have the same name as the old one and therefore be identified by git as the origin) and push you changes again with gbp or git.

Or use libgitlab-api-v4-perl to set the fork-property of your remote repository:

gitlab-api-v4 set_project_fork <your_username>/<packagename> ruby-team/<package-name>

You can now place a merge request through Salsa’s web-interface.

When you finally decide to become member of the ruby team

How to become member of the team

(yet to be written)

Duties of team members

(yet to be written)

What changes regarding the workflow with salsa?

Mainly one thing: You do not need to fork a project at the start. You can clone the team’ repository of a package out of the teams namespace and push back your changes directly into the team’s repository of a package.

The GitLab ( the software Salsa uses) knows different roles. The team will probably let you start with the basic rights. Ask the team what you are allowed to do and how you should adjust your workflow!

Especially when preparing a big version upgrade for a package (like 1.2.3 to 2.0.1) it might be a good idea to create a new branch and start there.

 

site info

© 2007-2022 Klaus-M. Klingsporn | generated with webgen | page last changed: 24.11.2020 | Impressum