rdopkg-adv-requirements(7)
==========================
:doctype: manpage


NAME
----
rdopkg-adv-requirements - rdopkg adventures: requirements management 


SYNOPSIS
--------

This is a story about managing requirements of an RDO package using `rdopkg`.


PROLOGUE
--------

`rdopkg` contains actions to help you with requirements management, namely:

 * `rdopkg reqdiff` shows diff of requirements.txt between versions
 * `rdopkg reqcheck` compares `requirements.txt` with `.spec` Requires
 * `rdopkg query` queries RDO repos for version of a supplied package
 * `rdopkg reqquery` queries RDO repos for versions of `requirements.txt`

This docuemnt will give you some examples of how to use these commands.

Please make sure you have the latest `rdopkg`, at least **0.28**.

Let's explore `python-openstackclient` RDO package. All commands are run in
its distgit with `patches` and `upstream` remotes set up:

    $ cd python-openstackclient
    $ git fetch --all
    $ git remote -v
    openstack	git@github.com:openstack/python-openstackclient.git (fetch)
    openstack	git@github.com:openstack/python-openstackclient.git (push)
    origin	ssh://jruzicka@pkgs.fedoraproject.org/python-openstackclient (fetch)
    origin	ssh://jruzicka@pkgs.fedoraproject.org/python-openstackclient (push)
    patches	git@github.com:redhat-openstack/python-openstackclient.git (fetch)
    patches	git@github.com:redhat-openstack/python-openstackclient.git (push)

Let's assume we see the package for the first time and we want to check
whether its requirements are met.

....
$ rdopkg pkgenv
Package:  python-openstackclient
Version:  1.0.3
Upstream: 1.1.0
OS dist:  RDO

Dist-git branch:        master
Local patches branch:   master-patches
Remote patches branch:  patches/master-patches
Remote upstream branch: openstack/master

RDO release/dist guess: kilo/f22
....

Now we know that

 * package is at version `1.0.3` while upstream is at `1.1.0`
 * `rdopkg` was able to detect the upstream remote/branch (automagic works)
 * `master` branch currently corresponds to Kilo release (see `rdopkg info`)

so we can start inspecting the requirements.


CHAPTER 1
---------

**rdopkg reqdiff**

`reqdiff` shows a human friendly summary of changes to `requirements.txt` file
between two git refs (usually version tags).

When `patches` and `upstream` remotes are set correctly, the action can be run
without arguments and `rdopkg` will do a diff between current and latest
upstream versions:

....
$ rdopkg reqdiff
requirements.txt diff between 1.0.3 and 1.1.0:

ADDED:
  os-client-config

CHANGED:
  cliff >=1.10.0  (was >=1.7.0)
  oslo.config >=1.9.3  (was >=1.9.0)
  oslo.i18n >=1.5.0  (was >=1.3.0)
  oslo.serialization >=1.4.0  (was >=1.2.0)
  oslo.utils >=1.4.0  (was >=1.2.0)
  python-novaclient >=2.22.0  (was >=2.18.0,!=2.21.0)
  stevedore >=1.3.0  (was >=1.1.0)
....

With one argument, diff between current package version and supplied git ref
is done:

    $ rdopkg reqdiff 1.1.0
    requirements.txt diff between 1.0.3 and 1.1.0:
    ...

Finally, we can supply two git refs to get `requirements.txt` diff
between them:

....
$ rdopkg reqdiff 0.4.0 1.0.0
requirements.txt diff between 0.4.0 and 1.0.0:

ADDED:
  Babel >=1.3
  cliff-tablib >=1.0
  oslo.i18n >=1.0.0
  oslo.serialization >=1.0.0
  oslo.utils >=1.0.0
  python-neutronclient >=2.3.6,<3
  stevedore >=1.1.0

CHANGED:
  cliff >=1.7.0  (was >=1.4.3)
  python-cinderclient >=1.1.0  (was >=1.0.6)
  python-glanceclient >=0.14.0  (was >=0.9.0)
  python-keystoneclient >=0.11.1  (was >=0.9.0)
  python-novaclient >=2.18.0  (was >=2.17.0)
  requests >=2.2.0,!=2.4.0  (was >=1.1)

REMOVED:
  keyring >=2.1
  pycrypto >=2.6
....

Note that `reqdiff` is automatically shown during `rdopkg new-version`.


CHAPTER 2
---------

**rdopkg reqcheck**

`reqcheck` is used to check whether requires defined in `requirements.txt` are
met in the `.spec` file. Human friendly summary is printed.

....
$ rdopkg reqcheck

VERSION NOT ENFORCED:
  python-babel >=1.3
  python-cliff >=1.7.0
  python-oslo-i18n >=1.3.0
  python-oslo-serialization >=1.2.0
  python-oslo-utils >=1.2.0
  python-pbr >=0.6,!=0.7,<1.0
  python-cinderclient >=1.1.0
  python-glanceclient >=0.15.0
  python-keystoneclient >=1.1.0
  python-neutronclient >=2.3.11,<3
  python-novaclient >=2.18.0,!=2.21.0
  python-requests >=2.2.0,!=2.4.0
  python-six >=1.9.0
  python-stevedore >=1.1.0

MISSING:
  python-cliff-tablib >=1.0
  python-oslo-config >=1.9.0
....

Human brain superpowers are used to evaluate the report and fix the `.spec`
file if needed.


CHAPTER 3
---------

**rdopkg query**

Is package X available in RDO? At which version? `rdopkg query` was created to
answer these recurring questions.

We can query a specific release/dist:

    $ rdopkg query kilo/f22 python-novaclient    
    kilo/f22
        python-novaclient-2.23.0-1.fc23  @  RDO Kilo f22
        python-novaclient-2.20.0-1.fc22  @  Fedora 22

We now see that `python-novaclient-2.20.0-1` is present in base Fedora 22 repo
but newer `python-novaclient-2.23.0-1` is available from RDO Kilo f22 repo.

We can also query a package across all dists of an RDO release. We might
want to use `-v`/`--verbose` to see what's happening in the background:

....
$ rdopkg query -v kilo python-novaclient

repoquery --nvr --repofrompath=rdopkg_RDO_Kilo_f22,...
RDO Kilo f22: python-novaclient-2.23.0-1.fc23
repoquery --nvr --repofrompath=rdopkg_Fedora_22_Updates,...
...

kilo/f22
    python-novaclient-2.23.0-1.fc23  @  RDO Kilo f22
    python-novaclient-2.20.0-1.fc22  @  Fedora 22
kilo/f21
    python-novaclient-2.23.0-1.fc23  @  RDO Kilo f21
    python-novaclient-2.17.0-3.fc21  @  Fedora 21
kilo/el7
    python-novaclient-2.23.0-1.el7  @  RDO Kilo el7
....

See `rdopkg info` to get supported release/dist combinations.


CHAPTER 4
---------

**rdopkg reqquery**

`reqquery` queries versions of `requirements.txt` or `.spec` Requires in RDO
repos and provides colorful report to easily check whether dependencies are
available and in correct versions. 

Simplest use case without arguments queries all `requirements.txt` of current
package version in autodetected release/dist:

....
$ rdopkg reqquery
Autodetected filter: kilo/f22
Querying requirements file from git: 1.0.3 -- requirements.txt

kilo/f22
  pbr
    nvr:   python-pbr-0.10.8-1.fc22
    need:  >=0.6,!=0.7,<1.0
    state: OK
  python-novaclient
    nvr:   python-novaclient-2.23.0-1.fc23
    need:  >=2.18.0,!=2.21.0
    state: OK
  cliff-tablib
    nvr:   python-cliff-tablib not available
    need:  >=1.0
    state: not met
...
....

We can also select the release/dist filter manually (see `rdopkg info`):

    $ rdopkg reqquery kilo/el7

By default, current version `requirements.txt` are used, but we can select
a different requirements source:

 * git ref (version):

    $ rdopkg reqquery -R 1.2.3

 * file:

    $ rdopkg reqquery -r path/to/requirements.txt

 * from current `.spec` file:

    $ rdopkg reqquery -s
    
As it usually takes quite some time to `repoquery` all the repos, we might
want to run with `-v`/`--verbose`, dump to `requirements.yml` with
`-d`/`--dump` and then view the report with `-l`/`--load`:

....
$ rdopkg reqquery -v -d
Autodetected filter: kilo/f22
Querying requirements file from git: 1.0.3 -- requirements.txt

repoquery --nvr --repofrompath=...
RDO Kilo f22: N/A
...

$ rdopkg reqquery -l
....


EPILOGUE
--------

See `rdopkg ACTION -h` to get options for each ACTION.

See link:rdopkg.1.html[rdopkg(1)] manual for more information.
