1RDOPKG(1)                                                            RDOPKG(1)
2
3
4

NAME

6       rdopkg - RDO packaging tool
7

SYNOPSIS

9       rdopkg <action> <arg>...
10
11       rdopkg -c
12
13       rdopkg -h
14

DESCRIPTION

16       rdopkg is a tool for automating RDO/RHOSP packaging tasks, such as
17       introducing patches, updating packages to new versions and submitting
18       packages to RDO.
19
20       Run rdopkg -h to get available actions.
21
22   persistence
23       rdopkg provides multi-step actions where each step is (should be)
24       idempotent so if something fails along the way or human interaction is
25       required, rdopkg drops to shell, lets you fix the problem, and then
26       continue by running rdopkg --continue (rdopkg -c).
27
28       The state is stored in a file named .rdopkg.json in the current
29       directory. The last stored action can be inspected (rdopkg status),
30       continued (rdopkg --continue) or aborted (rdopkg --abort). rdopkg will
31       refuse to perform a new multi-step action if a state file is present.
32

ACTIONS

34   Important actions diagram
35
36
37                    +---------------------+
38                   /  WHAT DO YOU NEED?  /
39                  +-----+----------+----+
40                             |
41                             |
42                             |
43                      build a new package
44                             |
45                             v
46                    +---------------------+
47                   /  what is changing?  /
48                  +----+-----+-----+----+
49                       |     |     |
50                +------+     |     +--------+
51                |            |              |
52           just update   introduce    update to new
53             .spec       patch(es)   upstream version
54                |            |              |
55                |            |              |
56                v            v              v
57             +-----+     +-------+    +-------------+
58             | fix |     | patch |    | new-version |
59             +-----+     +-------+    +-------------+
60
61   ACTION: fix
62       Apply changes to the .spec file.
63
64       Flow:
65
66       ·   Bump Release, prepare a new %changelog entry header.
67
68       ·   Drop to shell, let user edit the .spec file.
69
70       ·   After running rdopkg, ensure description was added to %changelog
71           and commit changes in a new commit.
72
73       Example:
74
75           cd python-novaclient
76           rdopkg fix
77           vim python-novaclient.spec
78           rdopkg -c
79
80       More use cases can be found in rdopkg-feature-fix(7).
81
82   ACTION: patch
83       Introduce new patches to the package.
84
85       This action works with the patches branch (see AUTOMAGIC → patches
86       branch).
87
88       By default, rdopkg resets the local patches branch to the remote
89       patches branch. You can skip this with -l/--local-patches to directly
90       use the local patches branch as is.
91
92       Don’t forget to git fetch before running the action.
93
94       After running rdopkg patch, the new commit will contain the changes if
95       there are any.
96
97       You can use -C/--changelog option to select how rdopkg detects new/old
98       patches and changelog message:
99
100       ·   detect: detect new/old patches using commit hash/subject (default)
101
102       ·   count: count old and new patches (doesn’t work for simultaneous
103           removal & addition of patches and rewriting -patches history)
104
105       ·   plain: just use generic "- Update patches" message
106
107       Or you can use -B/--no-bump to skip Release bump and changelog
108       generation and only update patch files and their references in the
109       .spec file. This is useful when you only need to align distgit with the
110       patches branch.
111
112       Use --amend to amend previous git commit with the changes and
113       autogenerated commit message instead of creating a new one. This is
114       very convenient when modifying distgit commits.
115
116       Please see AUTOMAGIC for additional information about using magic
117       patches_base and patches_ignore comments in your .spec file to
118       influcence patches generation.
119
120       Flow:
121
122       ·   Unless -l/--local-patches was used, reset the local patches branch
123           to the remote patches branch.
124
125       ·   Update patch files from local patches branch using git
126           format-patch.
127
128       ·   Update .spec file with correct patch files references.
129
130       ·   Unless ‘-B/--no-bump` was used, update .spec file: bump Release,
131           create new %changelog entry with new patches’ titles depending on
132           -C/--changelog option.
133
134       ·   If a %global commit asdf1234 macro declaration is present, rewrite
135           it with the current sha1 of the patches branch. (This makes the
136           sha1 value available during your package’s build process. You can
137           use this to build your program so that "mycoolprogram --version"
138           could display the sha1 to users.)
139
140       ·   Create new commit (or amend previous one with -a/--amend) with the
141           changes using %changelog to generate commit message if available.
142
143       ·   Display the diff.
144
145       Example:
146
147           rdopkg patch
148           rdopkg patch -lBa
149
150       More use cases can be found in rdopkg-feature-patch(7).
151
152   ACTION: update-patches
153       An alias for:
154
155           rdopkg patch --local-patches --no-bump
156
157       in the spirit of the ancient update-patches.sh script.
158
159       See ACTION: PATCH above.
160
161   ACTION: new-version
162       Update package to new upstream version.
163
164       This action works with the patches branch (see AUTOMAGIC → patches
165       branch). After a successful rebase, rdopkg will offer to push the
166       rebased patches branch.
167
168       Required new-version argument is a new version to rebase on, presumably
169       a git version tag.
170
171       Don’t forget to git fetch --all before running the action.
172
173       You can use the -N/--new-sources or -n/--no-new-sources options to
174       control whether new-version will run fedpkg new-sources (rhpkg
175       new-sources on Red Hat downstream products). By default, rdopkg will
176       automatically enable this step in following scenarios:
177
178       ·   Fedora distgit detected from origin git remote
179           (pkgs.fedoraproject.org)
180
181       ·   RH distgit detected from git branch (rhos-*, rh-*, ceph-*,
182           rhscon-*)
183
184       Otherwise, fedpkg new-sources is disabled (-n).
185
186       After running rdopkg new-version, a new commit will contain the
187       changes.
188
189       To only update .spec without touching patches branch, -b/--bump-only
190       can be used. Along with -n/--no-new-sources this enables local-only
191       operations, much like rpmdev-bumpspec:
192
193           rdopkg -bn
194
195       To note particular bugs in the changelog, use the -B/--bug option.
196       rdopkg will append the supplied string to changelog in brackets. For
197       example:
198
199           rdopkg new-version --bug rhbz#1234,rhbz#5678
200
201       will result in following %changelog line:
202
203           Update to 1.1.1 (rhbz#1234,rhbz#5678)
204
205       and corresponding Resolves: lines in commit message.
206
207       Flow:
208
209       ·   Show changes between the previous version and the current one,
210           especially modifications to requirements.txt.
211
212       ·   Reset the local patches branch to the remote patches branch
213
214       ·   Rebase the local patches branch on $NEW_VERSION tag.
215
216       ·   Update .spec file: set Version, Release and patches_base to
217           appropriate values and create a new %changelog entry.
218
219       ·   Download source tarball.
220
221       ·   Run fedpkg new-sources (rhpkg new-sources).
222
223       ·   Update patches from the local patches branch.
224
225       ·   Display the diff.
226
227       Example:
228
229           cd python-novaclient
230           git fetch --all
231           rdopkg new-version 2.15.0
232           # rebase failed, manually fix using git
233           rdopkg -c
234
235       More use cases can be found in rdopkg-feature-new-version(7).
236
237   ACTION: lint
238       Run checks for errors in current distgit.
239
240       Available checks selectable with --lint-checks:
241
242       ·   sanity: internal rdopkg sanity checks on the .spec
243
244       ·   rpmlint: run rpmlint tool on the .spec
245
246       ·   all: run all available checks (default)
247
248       Available error levels selectable with --error-level affect the exit
249       code:
250
251       ·   E: exit with code 23 when linting error is found (default)
252
253       ·   W: exit with code 23 when linttng error or warning is found
254
255       ·   -: only print errors/warnings, always returns 0
256
257       Most of the time you probably want just:
258
259           rdopkg lint
260
261       Example of only running rpmlint with W error level:
262
263           rdopkg lint --lint-checks rpmlint --error-level W
264
265   ACTION: clone
266       Clone an RDO package distgit and setup remotes.
267
268       clone uses rdoinfo metadata to clone the specified RDO package distgit
269       and also setup relevant remotes to get you packaging quickly.
270
271       If your github username differs from your $USER, use -u/--review-user.
272
273       Example:
274
275           rdopkg clone -u github-user python-novaclient
276           cd python-novaclient
277           git remote -v
278
279   ACTION: query
280       Query RDO/distro repos for available package versions.
281
282       See rdopkg-adv-requirements(7) for complete example of query and other
283       requirements management actions.
284
285       This action uses repoquery to discover the latest package versions
286       available from RDO and other repos available on a supported
287       distibution.
288
289       See output of rdopkg info for supported releases and distros.
290
291       Query specific RELEASE/DIST:
292
293           rdopkg query kilo/el7 openstack-nova
294
295       Query all dists of a release and show what’s happening:
296
297           rdopkg query -v kilo openstack-nova
298
299   ACTION: reqquery
300       Query RDO/distro repos for versions defined in requirements.txt.
301
302       See rdopkg-adv-requirements(7) for a complete example of reqquery and
303       other requirements management actions.
304
305       This action essentially runs rdopkg query on every module/package
306       defined in requirements.txt and prints a colorful report to quickly
307       find unmet dependencies. It accepts the same RELEAESE/DIST filter as
308       rdopkg query.
309
310       Python module names listed in requirements.txt are mapped to package
311       names using the rdopkg.actionmods.pymod2pkg module.
312
313       Query requirements.txt from 2015.1 tag:
314
315           rdopkg reqquery -R 2015.1 kilo/el7
316
317       Query requirements.txt file:
318
319           rdopkg reqquery -r path/to/requirements.txt kilo/f21
320
321       Query .spec Requires (experimental):
322
323           rdopkg reqquery -s
324
325       Verbosely dump query results to a file and view them:
326
327           rdopkg reqquery -v -d
328           rdopkg reqquery -l
329
330   ACTION: reqcheck
331       Inspect requirements.txt vs .spec Requires.
332
333       See rdopkg-adv-requirements(7) for complete example of reqcheck and
334       other requirements management actions.
335
336       This action parses the current requirements.txt from git and checks
337       whether they’re met in the .spec file. A simple report is produced.
338
339       Python module names listed in requirements.txt are mapped to package
340       names using rdopkg.actionmods.pymod2pkg module.
341
342       Use --spec/-s option to output Requires: suitable for pasting into
343       .spec files. Version comparisons are hidden, whitespace is detected
344       from .spec.
345
346       Example:
347
348           rdopkg reqcheck
349           rdopkg reqcheck -s
350
351   ACTION: reqdiff
352       Show pretty diff of requirements.txt.
353
354       See rdopkg-adv-requirements(7) for a complete example of reqdiff and
355       other requirements management actions.
356
357       Use this to see how requirements changed between versions.
358
359       See diff between current and latest upstream version (automagic):
360
361           rdopkg reqdiff
362
363       See diff between current and specified version:
364
365           rdopkg reqdiff 2015.1
366
367       See diff between two supplied versions:
368
369           rdopkg reqdiff 2015.1 2015.2
370
371   ACTION: kojibuild
372       Build the package in koji.
373
374       Flow:
375
376       ·   Run equivalent of fedpkg build using disgusting fedpkg python
377           module.
378
379       ·   Watch the build.
380
381       Example:
382
383           rdopkg kojibuild
384
385   ACTION: amend
386       Amend last git commit with current dist-git changes and (re)generate
387       the commit message from %changelog.
388
389       This simple action is equivalent to running
390
391           git commit -a --amend -m "$AUTOMAGIC_COMMIT_MESSAGE"
392
393       See AUTOMAGIC → commit message for more information about the generated
394       commit message.
395
396   ACTION: squash
397       Squash last git commit into previous one. The commit message of the
398       previous commit is used.
399
400       This simple action is a shortcut for
401
402           git reset --soft HEAD~
403           git commit --amend --no-edit
404
405       This is useful for squashing commits created by lower level actions
406       such as update-patches.
407
408   ACTION: get-sources
409       Download package source archive.
410
411       Currently, Source0 from .spec file is downloaded.
412
413   ACTION: info
414       Show information about RDO packaging.
415
416       Use this command to find out about:
417
418       ·   currently supported RDO OpenStack releases
419
420       ·   which distros are supported for each release
421
422       ·   what branch to build from
423
424       ·   what build system to build in
425
426       ·   supported packages
427
428       ·   various repositories tied to a package
429
430       ·   package maintainers
431
432       This command is a human interface to rdoinfo.
433
434       Releases/dists/branches overview:
435
436           rdopkg info
437
438       Detailed information about a package:
439
440           rdopkg info novaclient
441
442       Filter packages by maintainers:
443
444           rdopkg info maintainers:jruzicka
445
446   ACTION: info-tags-diff
447       Show rdoinfo tag changes.
448
449           rdopkg info-tags-diff RDOINFODIR
450
451       will show per-package new/changed tags in rdoinfo between HEAD~..HEAD.
452
453       For an existing or new package, a list of changed tags is returned
454
455       Example:
456
457           $ rdopkg info-tags-diff ~/.rdopkg/rdoinfo
458           openstack-changed ['newton-uc', 'newton']
459           openstack-new-pkg ['under-review']
460
461       This is an interface to rdopkg.actionmods.rdoinfo:tags_diff().
462
463   ACTION: findpkg
464       Find and show the single best matching package in rdoinfo.
465
466       This command produces the same output as rdopkg info but
467
468       ·   smart search is performed on package name, project name and
469           upstream URL
470
471       ·   only a single matching package is shown
472
473       Use -s/--strict to disable magic substring search and only match whole
474       fields.
475
476       This command is a human interface to distroinfo.query.find_package()
477       function.
478
479       Examples of usage:
480
481           rdopkg findpkg nova
482           rdopkg findpkg -s openstack-nova
483           rdopkg findpkg git://git.openstack.org/openstack/nova
484           rdopkg findpkg openstack/nova
485           rdopkg findpkg novacli
486
487   ACTION: conf
488       Display rdopkg’s local configuration.
489
490       This command prints the default configuration that ships with rdopkg
491       out of the box. You can override the individual settings here by using
492       .py files in the configuration directories.
493
494       Store your per-user configuration in ~/.rdopkg/conf.d/*.py, or store
495       system-wide configuration in /etc/rdopkg.d/*.py.
496
497   ACTION: tag-patches
498       Tag the local -patches branch with the package’s Name-Version-Release.
499
500       Since the -patches branch can change over time, including rebases,
501       rewrites, etc, we need a mechanism to keep historical records of what
502       the -patches branch looked like over time. Tagging the -patches branch
503       for each new NVR will maintain Git references to each snapshot of the
504       particular patches that went into each build.
505
506       To look at the -patches branch for an old build, you can simply "git
507       checkout name-version-release" for that build and get an exact
508       representation of the Git tree for that build.
509
510       If a previous tag exists with this name, rdopkg will exit with an error
511       unless you use the --force option to overwrite the existing tag with
512       this name.
513
514       You can automatically push the new tag with the --push option. It’s a
515       good idea to create and push the tag after every successful build.
516

AUTOMAGIC

518       Instead of requiring project config files or endless lists of command
519       line arguments, rdopkg tries to guess all the necessary variables.
520
521   patches branch
522       update-patches is a core lower level action for updating the dist-git
523       .spec file with patches from associated patches branch. rdopkg tries
524       hard to detect the patches branch automagically, it’s usually
525       $BRANCH-patches for $BRANCH dist-git but one patches branch per
526       multiple dist-gits is also supported.
527
528       Best illustrated by example, the following are all valid patches
529       branches for rhos-5.0-rhel-7 dist-git and they’re searched in that
530       order:
531
532       ·   rhos-5.0-rhel-7-patches
533
534       ·   rhos-5.0-rhel-patches
535
536       ·   rhos-5.0-patches ←-- preferred for RHOSP
537
538       ·   rhos-patches
539
540       Use rdopkg pkgenv to check detected patches branch.
541
542       You can specify remote patches branch by -p/--patches-branch action
543       parameter for actions that use it, such as patch and new-version.
544
545       You may explicitly set the name of your patches remote and patches
546       branch in your git configuration using the
547       rdopkg.<branch>.patches-remote and rdopkg.<branch>.patches-branch
548       options. For example, if you are working on a dist-git branch named
549       rhel-7.4 and you want to use rhel-7-patches for your patches branch,
550       you would run:
551
552           git config rdopkg.rhel-7.4.patches-branch rhel-7-patches
553
554   patches base
555       rdopkg calculates the git tag on which you are applying patches from
556       the Version tag in your .spec file. If your .spec file contains a macro
557       named milestone, the value of this macro will be appended to the
558       version. That is, if your spec file has:
559
560           Version: 2014.2.3
561
562       Then rdopkg will use 2014.2.3 as the base. If instead your .spec file
563       has:
564
565           %global milestone rc2
566
567           Version: 2014.2.3
568
569       Then rdopkg will use 2014.2.3rc2 as the base.
570
571       In older versions of rdopkg, it was necessary to explicitly set the
572       patch base using a special patches_base comment in your spec file. This
573       is now optional behavior (the patches base is calculated
574       automatically), but you can use this if you need to override the
575       automatic behavior.
576
577       The most common use of patches_base is to specify number of patches on
578       top of patches base (which defaults to spec Version) to skip:
579
580           # patches_base=+2
581
582       You can set an arbitrary git revision as a patches base:
583
584           # patches_base=1.2.3+2
585
586       You shouldn’t need to modify this by hand (other than perhaps the
587       number of skipped patches) as rdopkg manages patches_base as needed.
588
589   patches_ignore
590       update-patches also supports filtering out patches based on matching a
591       regex provided by a magic #patches_ignore comment in the spec file.
592       This is useful, for example, in case the patches branch contains
593       changes that are related to the CI/code review infra, that are useful
594       to keep around but don’t need to end up in the RPM.
595
596       For example, if you add the following comments in your package’s .spec
597       file:
598
599           # patches_base=10.2.5
600           # patches_ignore=DROP-IN-RPM
601
602       then rdopkg will not create .patch files for any commits that have
603       "DROP-IN-RPM" in the Git commit log’s subject line.
604
605       Note: these lines should be directly above any Patch000X lines in your
606       .spec file.
607
608   Release bumping
609       rdopkg fix and rdopkg patch bump the Release tag in .spec file.
610
611       By default, last numeric only part of Release is bumped:
612
613           1.1.1.a.b.c -> 1.1.2.a.b.c
614
615       You can override this using -R/--release-bump-index argument which
616       expects MAJOR/MINOR/PATCH or integer index of release part to bump,
617       starting at 1 from the left:
618
619           -R 1 / -R MAJOR: 1.1.1 -> 2.1.1
620           -R 2 / -R MINOR: 1.1.1 -> 1.2.1
621           -R 3 / -R PATCH: 1.1.1 -> 1.1.2
622           -R 4: 1.1.1.1 -> 1.1.1.2
623           -R 5: 1.1.1.1.1 -> 1.1.1.1.2
624           ...
625
626       DLRN 0.date.hash and 0.1.date.hash formats are detected and default to
627       bumping 2nd Release part (-R 2).
628
629   commit message
630       Commit messages created by rdopkg are generated from .spec file Name,
631       Version and Release (NVR) as well as last %changelog entry.
632
633       All rdopkg actions that modify distgit use following format:
634
635           package-name-1.2.3-4
636
637           Changelog:
638           - Doom the World (rhbz#111111)
639           - Fix Impending Doom support
640           - Save the World (rhbz#222222)
641
642           Resolves: rhbz#111111
643           Resolves: rhbz#222222
644           Change-Id: deadbeedeadbeedeadbeedeadbeedeadbeedeadbee
645
646       For each (rhbz#XYZ) mentioned in latest %changelog entry, Resolves:
647       rhbz#XYZ line is appended to commit message as required by RHOSP
648       workflow.
649
650       protip: To (re)generate nice commit message after modifying .spec file,
651       use rdopkg amend (see ACTION: amend above).
652
653       For example, following %changelog entry:
654
655           %changelog
656           * Tue Feb 11 2014 Jakub Ruzicka <jruzicka@redhat.com> 0.5.0-1
657           - Update to upstream 0.5.0
658           - Fix evil Bug of Doom (rhbz#123456)
659
660       will generate following commit message:
661
662           package-name-0.5.0-1
663
664           Changelog:
665           - Update to upstream 0.5.0
666           - Fix evil Bug of Doom (rhbz#123456)
667
668           Resolves: rhbz#123456
669
670   rdoinfo
671       rdoinfo is a special utility repository with RDO metadata:
672
673       https://github.com/redhat-openstack/rdoinfo
674
675       rdopkg uses rdoinfo to
676
677       ·   detect release/dist from branch name
678
679       ·   check valid RDO updates
680
681       ·   query packages from RDO/distribution repos
682
683       and more.
684
685       You can view the rdoinfo metada using rdopkg info.
686

SEE ALSO

688       rdopkg-adv-new-version(7), rdopkg-adv-requirements(7),
689       rdopkg-feature-pkgenv(7), rdopkg-feature-fix(7),
690       rdopkg-feature-patch(7), rdopkg-feature-new-version(7),
691       rdopkg-feature-actions(7)
692

CONTACT

694       rdopkg is maintained by Jakub Ruzicka <jruzicka@redhat.com>.
695
696       Bugs are tracked as github Issues:
697
698       https://github.com/softwarefactory-project/rdopkg/issues
699
700       To report a new bug:
701
702       https://github.com/softwarefactory-project/rdopkg/issues/new
703
704
705
706                                  10/14/2019                         RDOPKG(1)
Impressum