<commit_before>rdopkg(1)
=========
:doctype: manpage
:toc2:


NAME
----
rdopkg - RDO packaging tool


SYNOPSIS
--------

`rdopkg` <action> <arg>...

`rdopkg` `-c`

`rdopkg` `-h`


DESCRIPTION
-----------
**rdopkg** is a tool for automating RDO/RHOSP packaging tasks, such as
introducing patches, updating packages to new versions and submitting
packages to RDO.

Run `rdopkg -h` to get available actions.

persistence
~~~~~~~~~~~

`rdopkg` provides multi-step actions where each step is (should be) idempotent
so if something fails along the way or human interaction is required, rdopkg
drops to shell, let's you rectify and then continue by running `rdopkg -c`.

The state is stored in `.rdopkg.json` file in current directory. Stored action
can be inspected (`rdopkg -i`) or continued (`rdopkg -c`). When new action is
run in such directory, `rdopkg` asks to confirm if you want to abandon the
previous action.

ACTIONS
-------

Important actions diagram
~~~~~~~~~~~~~~~~~~~~~~~~~

&nbsp;

                          +---------------------+
                         /  WHAT DO YOU NEED?  /
                        +-----+----------+----+
                              |          |
                      +-------+          +-------------+
                      |                                |
               build new package               submit RDO update
                      |                                |
                      v                                |
               +----------------+                      |
              /  what change?  /                       |
             +--+-----+-----+-+                        |
                |     |     |                          |
         +------+     |     +--------+                 |
         |            |              |                 |
    just update   introduce    update to new           |
      .spec       patch(es)   upstream version         |
         |            |              |                 |
         |            |              |                 |
         v            v              v                 v
      +-----+     +-------+    +-------------+    +--------+
      | fix |     | patch |    | new-version |    | update |
      +-----+     +-------+    +-------------+    +--------+

ACTION: fix
~~~~~~~~~~~

Make `.spec` file only changes.

*Flow:*

  * Bump Release, prepare a new %changelog entry header.
  * Drop to shell, let user edit .spec file.
  * After running `rdopkg`, ensure description was added to %changelog
    and commit changes to new commit.

*Example:*
    
    cd python-novaclient
    rdopkg fix
    vim python-novaclient.spec
    rdopkg -c

ACTION: patch
~~~~~~~~~~~~~

Introduce new patches to the package.

This action works with patches branch
(see <<patches-branch,AUTOMAGIC -> patches branch>>).
By default, `rdopkg` resets local patches branch to remote patches branch.
You can skip this this with `--local-patches` to directly use local patches
branch as is.

Note that `patch` is a high level wrapper of `update-patches` action. If
you're interested in just updating patches in `.spec` file from local patches
branch, try using `update-patches` action instead.

Don't forget to `git fetch` before running the action.

After running `rdopkg patch`, new commit will contain the changes.

*Flow:*

  * Unless `-l`/`--local-patches` was used, reset local patches branch to
    remote patches branch.
  * Update .spec file: bump Release, create new %changelog entry with new
    patches' titles and create a commit.
  * Update patches from local patches branch (`update-patches` action)
  * Display the diff.

ACTION: new-version
~~~~~~~~~~~~~~~~~~~

Update package to new upstream version.

This action works with patches branch 
(see <<patches-branch,AUTOMAGIC -> patches branch>>).
After successful rebase, `rdopkg` will offer to push the
rebased patches branch.

Required `new-version` argument is a new version to rebase on, presumably
a git version tag.

Don't forget to `git fetch --all` before running the action.

After running `rdopkg new-version`, new commit will contain the changes.

*Flow:*

  * Show diff from previous version, especially changes to `requirements.txt`.
  * Reset local patches branch to remote patches branch
  * Rebase local patches branch on `$NEW_VERSION` tag.
  * Update `.spec` file: set `Version`, `Release` and `patches_base` to
    appropriate values and create new %changelog entry.
  * Download source tarball.
  * Run `fedpkg new-sources` (`rhpkg new-sources`).
  * Update patches from local patches branch (`update-patches` action)
  * Display the diff.

*Example:*

    cd python-novaclient
    git fetch --all
    rdopkg new-version 2.15.0
    # rebase failed, manually fix using git
    rdopkg -c
    

ACTION: update-patches
~~~~~~~~~~~~~~~~~~~~~~

Update `.spec` file with patches from patches branch.

This is a core low level action used by other actions such as `patch` and
`new-version` to update dist-git patches from patches branch. 
See <<patches-branch,AUTOMAGIC -> patches branch>> for explanation.

`update-patches` is a rework of now obsolete `update-patches.sh` script with
less restrictions and more features such as optional #patches_base, support
for `git am %{patches}` method of applying patches and smart patches branch
detection.

*Flow:*

 * Export patches from patches branch using `git format-patch`
 * Add these patches to dist-git and edit `.spec` file to apply them
 * Create new commit with the change (or amend previous with `-a`/`--amend`)

*Example:*

    rdopkg update-patches


ACTION: kojibuild
~~~~~~~~~~~~~~~~~

Build the package in `koji`.

See link:rdopkg-adv-building.7.html[rdopkg-adv-building(7)] for complete
example of building and submitting packages for RDO.

This is esentaially a wrapper over `fedpkg build` with added value of
generating update entries for `rdopkg update`.

By default, build is appended to `up.yml` update file (new one is created if
needed) which is then used by `rdopkg update` to submit builds to RDO.
Use `-f/--update-file` to specify different file or `-F/--no-update-file` to
disable this.

*Flow:*

 * Run equivalent of `fedpkg build` using disgusting `fedpkg` python module.
 * Watch the build.
 * Print `rdopkg update` entry for the build and dump it to `up.yml`.<commit_msg>doc: explain new reqs mgmt actions is the manual<commit_after>rdopkg(1)
=========
:doctype: manpage
:toc2:


NAME
----
rdopkg - RDO packaging tool


SYNOPSIS
--------

`rdopkg` <action> <arg>...

`rdopkg` `-c`

`rdopkg` `-h`


DESCRIPTION
-----------
**rdopkg** is a tool for automating RDO/RHOSP packaging tasks, such as
introducing patches, updating packages to new versions and submitting
packages to RDO.

Run `rdopkg -h` to get available actions.

persistence
~~~~~~~~~~~

`rdopkg` provides multi-step actions where each step is (should be) idempotent
so if something fails along the way or human interaction is required, rdopkg
drops to shell, let's you rectify and then continue by running `rdopkg -c`.

The state is stored in `.rdopkg.json` file in current directory. Stored action
can be inspected (`rdopkg -i`) or continued (`rdopkg -c`). When new action is
run in such directory, `rdopkg` asks to confirm if you want to abandon the
previous action.

ACTIONS
-------

Important actions diagram
~~~~~~~~~~~~~~~~~~~~~~~~~

&nbsp;

                          +---------------------+
                         /  WHAT DO YOU NEED?  /
                        +-----+----------+----+
                              |          |
                      +-------+          +-------------+
                      |                                |
               build new package               submit RDO update
                      |                                |
                      v                                |
               +----------------+                      |
              /  what change?  /                       |
             +--+-----+-----+-+                        |
                |     |     |                          |
         +------+     |     +--------+                 |
         |            |              |                 |
    just update   introduce    update to new           |
      .spec       patch(es)   upstream version         |
         |            |              |                 |
         |            |              |                 |
         v            v              v                 v
      +-----+     +-------+    +-------------+    +--------+
      | fix |     | patch |    | new-version |    | update |
      +-----+     +-------+    +-------------+    +--------+

ACTION: fix
~~~~~~~~~~~

Make `.spec` file only changes.

*Flow:*

  * Bump Release, prepare a new %changelog entry header.
  * Drop to shell, let user edit .spec file.
  * After running `rdopkg`, ensure description was added to %changelog
    and commit changes to new commit.

*Example:*
    
    cd python-novaclient
    rdopkg fix
    vim python-novaclient.spec
    rdopkg -c

ACTION: patch
~~~~~~~~~~~~~

Introduce new patches to the package.

This action works with patches branch
(see <<patches-branch,AUTOMAGIC -> patches branch>>).
By default, `rdopkg` resets local patches branch to remote patches branch.
You can skip this this with `--local-patches` to directly use local patches
branch as is.

Note that `patch` is a high level wrapper of `update-patches` action. If
you're interested in just updating patches in `.spec` file from local patches
branch, try using `update-patches` action instead.

Don't forget to `git fetch` before running the action.

After running `rdopkg patch`, new commit will contain the changes.

*Flow:*

  * Unless `-l`/`--local-patches` was used, reset local patches branch to
    remote patches branch.
  * Update .spec file: bump Release, create new %changelog entry with new
    patches' titles and create a commit.
  * Update patches from local patches branch (`update-patches` action)
  * Display the diff.

ACTION: new-version
~~~~~~~~~~~~~~~~~~~

Update package to new upstream version.

This action works with patches branch 
(see <<patches-branch,AUTOMAGIC -> patches branch>>).
After successful rebase, `rdopkg` will offer to push the
rebased patches branch.

Required `new-version` argument is a new version to rebase on, presumably
a git version tag.

Don't forget to `git fetch --all` before running the action.

After running `rdopkg new-version`, new commit will contain the changes.

*Flow:*

  * Show diff from previous version, especially changes to `requirements.txt`.
  * Reset local patches branch to remote patches branch
  * Rebase local patches branch on `$NEW_VERSION` tag.
  * Update `.spec` file: set `Version`, `Release` and `patches_base` to
    appropriate values and create new %changelog entry.
  * Download source tarball.
  * Run `fedpkg new-sources` (`rhpkg new-sources`).
  * Update patches from local patches branch (`update-patches` action)
  * Display the diff.

*Example:*

    cd python-novaclient
    git fetch --all
    rdopkg new-version 2.15.0
    # rebase failed, manually fix using git
    rdopkg -c
    

ACTION: update-patches
~~~~~~~~~~~~~~~~~~~~~~

Update `.spec` file with patches from patches branch.

This is a core low level action used by other actions such as `patch` and
`new-version` to update dist-git patches from patches branch. 
See <<patches-branch,AUTOMAGIC -> patches branch>> for explanation.

`update-patches` is a rework of now obsolete `update-patches.sh` script with
less restrictions and more features such as optional #patches_base, support
for `git am %{patches}` method of applying patches and smart patches branch
detection.

*Flow:*

 * Export patches from patches branch using `git format-patch`
 * Add these patches to dist-git and edit `.spec` file to apply them
 * Create new commit with the change (or amend previous with `-a`/`--amend`)

*Example:*

    rdopkg update-patches


ACTION: query
~~~~~~~~~~~~~

Query RDO/distro repos for available package versions.

This action uses `repoquery` to discover latest package versions available
from RDO and other repos available on a supported distibution.

See output of `rdopkg info` for supported releases and distros.

*Query specific RELEASE/DIST:*

     rdopkg query kilo/el7 openstack-nova

*Query all dists of a release and show what's happening:*

     rdopkg query -v kilo openstack-nova


ACTION: reqquery
~~~~~~~~~~~~~~~~

Query RDO/distro repos for versions defined in requirements.txt.

This action essentially runs `rdopkg query` on every module/package defined in
`requirements.txt`. It accepts the same RELEAESE/DIST filter.

Python module names listed in `requirements.txt` are mapped to package names
using `rdopkg.actionmods.pymod2pkg` module.

*Query `requirements.txt` from `2015.1` tag:*

    rdopkg reqquery -R 2015.1 kilo/el7

*Query `requirements.txt` file:*

    rdopkg reqquery -r path/to/requirements.txt kilo/f21

*Query `.spec` Requires (experimental):*

    rdopkg reqquery -s

*Verbosely dump query results to a file and view them:*

    rdopkg reqquery -v -d -R 2015.1
    rdopkg reqquery -l


ACTION: reqcheck
~~~~~~~~~~~~~~~~

Inspect `requirements.txt` vs `.spec` Requires.

This action parses current `requirements.txt` from git and checks whether
they're met in the `.spec` file. Simple report is printed.

Python module names listed in `requirements.txt` are mapped to package names
using `rdopkg.actionmods.pymod2pkg` module.

NOTE: Checking for exact version ranges is dumb at the moment.

*Example:*

    rdopkg reqcheck


ACTION: reqdiff
~~~~~~~~~~~~~~~

Show pretty diff of `requirements.txt`.

Use this to see how requirements changed between versions.

*See diff between current and latest upstream version (automagic):*

    rdopkg reqdiff

*See diff between current and specified version:*

    rdopkg reqdiff 2015.1

*See diff between two supplied versions:*

    rdopkg reqdiff 2015.1 2015.2


ACTION: kojibuild
~~~~~~~~~~~~~~~~~

Build the package in `koji`.

See link:rdopkg-adv-building.7.html[rdopkg-adv-building(7)] for complete
example of building and submitting packages for RDO.

This is esentaially a wrapper over `fedpkg build` with added value of
generating update entries for `rdopkg update`.

By default, build is appended to `up.yml` update file (new one is created if
needed) which is then used by `rdopkg update` to submit builds to RDO.
Use `-f/--update-file` to specify different file or `-F/--no-update-file` to
disable this.

*Flow:*

 * Run equivalent of `fedpkg build` using disgusting `fedpkg` python module.
 * Watch the build.
 * Print `rdopkg update` entry for the build and dump it to `up.yml`.
{'fraction_non_alphanumeric': 0.12389440740236767, 'fraction_numerical': 0.003537896312423459, 'mean_word_length': 2.189195053156867, 'pattern_counts': {'":': 0, '<': 19, '<?xml version=': 0, '>': 25, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 36, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1598530', 'n_tokens_mistral': 4178, 'n_tokens_neox': 3979, 'n_words': 1646}