The dr workflow
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:
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.
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.debThis 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
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.
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:
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.
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.
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
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
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
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.
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
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.
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!