The dr workflow

Radek Pazdera edited this page May 8, 2014 · 8 revisions

The Basics

The input of dr is code. It takes the source packages that are managed in git repositories, builds them, and makes them available downstream to the people who use your repository. You can submit your package into one of 3 suites, stable, testing, or unstable. Each suite can hold a different version of a package. Your users can select a level of stability they need by switching between them, just as they can in Debian. The relationships are illustrated in the following diagram:

dr illustrated

The important bit here is that you can build your packages directly from your codebase and deploy them with just a single command, and your users will receive the update. dr takes care of the whole process automatically. From pulling the changes, preparing the build environment, installing the dependencies, building, signing, and pushing the packages.

The following sections will explain the different tasks you might want to use dr for.

Adding a package to dr

When your repo is up and running, the next step is to add a few packages to it. Here, you have two options; you can either add a pre-built deb files directly, or use source packages hosted in git repositories and let dr do the work for you.

To add a pre-build package run the following command:

dr add --deb path/to/the/package_1.0-35_all.deb

This is useful in case you would like to host a few packages that you manage in a different way or you didn't build them yourself. However, the full power of dr is not unleashed until you add a source package, so that it can build and manage it for you. To add a source package, point dr to the git repository in which you manage your project's sources. Git is what we use at Kano, and it is the only supported SCM at the moment. Use the following command to add a package:

dr add --git https://github.com/KanoComputing/kano-settings

Adding a source package

dr is clever enough to determine all the information it needs about the package automatically from the sources, so you don't need to do anything else. By default, it will take the code off master. In case you use a different branch as the default one, you need to specify it by passing the -b <branch-name> option to dr add.

Building a package

Now when the package has been added, we need to build it. This can be done very easily using the dr build <package-name> command:

Building a package

dr will switch to an isolated build environment and install all the build dependencies requested by the package. Then it will proceed to building it using the debuild command. Depending on how many dependencies your package has, this process should take around 2 to 5 minutes.

Running a build like this without any other arguments will build the code from the master branch. But most of the development usually happens outside of master in small feature branches, right? Well, in that case you can add the -b <branch-name> option to the dr build command and the package will be built from that branch instead. This can be particularly useful for testing your changes in unstable, before merging them into master.

Pushing packages around

Now that a package has been built, it is time to make it available to users. This is done by pushing a build into a suite. And that's exactly what the following command is for:

dr push kano-settings -v 1.1-1.20140506 -s testing

Both of the parameters, -v | --version and -s | --suite, are optional. If you leave out the first one, dr will use the latest build available, and if you don't use the second one, it will push to testing by default.

Now if you're wondering what to do if something goes wrong, there is a command dr unpush <package> <suite> that does exactly the opposite, i.e., it will remove a package from a suite.

Inspection!

You can also query and inspect the contents of your repository with the dr list command. In fact, here are multiple flavours of it.

To display all the packages that are currently managed by the repository, you can type the following:

dr list packages 

Showing all the packages

That is useful, but it doesn't contain that much information, does it? Well, you can also list packages that are just in a single suite. The following will show all the packages from testing:

dr list suite testing

Show packages in a suite

This will give you the exact information about which packages are you shipping with which OS branch. And finally, you can also display information about all the package builds that are in the system:

dr list versions kano-settings

Show build of a package

Note that it is possible to abbreviate the list commands so you don't have to type yourself into a carpal tunnel syndrome. Just use dr l p|s|v.

Removing builds and packages

From time to time, you might want to remove a broken build or a package that was deprecated. There are two commands to aid you in this quest.

The following will delete a single build:

dr rmbuild kano-settings 1.1-1.20140507build1

And when you grow sick of the whole package and you decide to get rid of it for good, do the following command. Be warned, that the rm command will really remove everything and you won't be able to reverse its effect.

dr rm kano-settings

Daily suite rebuilds

There might be times in your development cylcle, when you would like to rebuild all the packages that have been changed. For example here at Kano we do this every night to make sure all our packages are up-to-date when we start working in the morning. For this, we added the dr update command.

dr update <suite>

The above command will go through the whole suite package-by-package, check whether any of them were updated and rebuild them if necessary. In case you omit the suite name, the testing suite will be updated by defualt.

Releasing (the dragon)

And as soon as you're happy with the state of the packages in the testing suite, you will probably like to push them to stable and announce a new release. That is exactly what the dr release command is for. Typing the following will take all the packages from testing and push them to stable:

dr release

Again, be advised that currently, there is no automatic way of going back as soon as you push a new release out, please back up your repo directory regularly!

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.