1RDOPKG(1) RDOPKG(1)
2
6 rdopkg - RDO packaging tool
7
9 rdopkg <action> <arg>...
10 rdopkg -c
12 rdopkg -h
14
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 Run rdopkg -h to get available actions.
21 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 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
34 Important actions diagram
35 +---------------------+
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 ACTION: fix
62 Apply changes to the .spec file.
63 Flow:
65 · Bump Release, prepare a new %changelog entry header.
67 · Drop to shell, let user edit the .spec file.
69 · After running rdopkg, ensure description was added to %changelog
71 and commit changes in a new commit.
72 Example:
74 cd python-novaclient
76 rdopkg fix
77 vim python-novaclient.spec
78 rdopkg -c
79 More use cases can be found in rdopkg-feature-fix(7).
81 ACTION: patch
83 Introduce new patches to the package.
84 This action works with the patches branch (see AUTOMAGIC → patches
86 branch).
87 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 Don’t forget to git fetch before running the action.
93 After running rdopkg patch, the new commit will contain the changes if
95 there are any.
96 You can use -C/--changelog option to select how rdopkg detects new/old
98 patches and changelog message:
99 · detect: detect new/old patches using commit hash/subject (default)
101 · count: count old and new patches (doesn’t work for simultaneous
103 removal & addition of patches and rewriting -patches history)
104 · plain: just use generic "- Update patches" message
106 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 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 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 Flow:
121 · Unless -l/--local-patches was used, reset the local patches branch
123 to the remote patches branch.
124 · Update patch files from local patches branch using git
126 format-patch.
127 · Update .spec file with correct patch files references.
129 · 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 · 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 · Create new commit (or amend previous one with -a/--amend) with the
141 changes using %changelog to generate commit message if available.
142 · Display the diff.
144 Example:
146 rdopkg patch
148 rdopkg patch -lBa
149 More use cases can be found in rdopkg-feature-patch(7).
151 ACTION: update-patches
153 An alias for:
154 rdopkg patch --local-patches --no-bump
156 in the spirit of the ancient update-patches.sh script.
158 See ACTION: PATCH above.
160 ACTION: new-version
162 Update package to new upstream version.
163 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 Required new-version argument is a new version to rebase on, presumably
169 a git version tag.
170 Don’t forget to git fetch --all before running the action.
172 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 · Fedora distgit detected from origin git remote
179 (pkgs.fedoraproject.org)
180 · RH distgit detected from git branch (rhos-*, rh-*, ceph-*,
182 rhscon-*)
183 Otherwise, fedpkg new-sources is disabled (-n).
185 After running rdopkg new-version, a new commit will contain the
187 changes.
188 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 rdopkg -bn
194 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 rdopkg new-version --bug rhbz#1234,rhbz#5678
200 will result in following %changelog line:
202 Update to 1.1.1 (rhbz#1234,rhbz#5678)
204 and corresponding Resolves: lines in commit message.
206 Flow:
208 · Show changes between the previous version and the current one,
210 especially modifications to requirements.txt.
211 · Reset the local patches branch to the remote patches branch
213 · Rebase the local patches branch on $NEW_VERSION tag.
215 · Update .spec file: set Version, Release and patches_base to
217 appropriate values and create a new %changelog entry.
218 · Download source tarball.
220 · Run fedpkg new-sources (rhpkg new-sources).
222 · Update patches from the local patches branch.
224 · Display the diff.
226 Example:
228 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 More use cases can be found in rdopkg-feature-new-version(7).
236 ACTION: lint
238 Run checks for errors in current distgit.
239 Available checks selectable with --lint-checks:
241 · sanity: internal rdopkg sanity checks on the .spec
243 · rpmlint: run rpmlint tool on the .spec
245 · all: run all available checks (default)
247 Available error levels selectable with --error-level affect the exit
249 code:
250 · E: exit with code 23 when linting error is found (default)
252 · W: exit with code 23 when linttng error or warning is found
254 · -: only print errors/warnings, always returns 0
256 Most of the time you probably want just:
258 rdopkg lint
260 Example of only running rpmlint with W error level:
262 rdopkg lint --lint-checks rpmlint --error-level W
264 ACTION: clone
266 Clone an RDO package distgit and setup remotes.
267 clone uses rdoinfo metadata to clone the specified RDO package distgit
269 and also setup relevant remotes to get you packaging quickly.
270 If your github username differs from your $USER, use -u/--review-user.
272 Example:
274 rdopkg clone -u github-user python-novaclient
276 cd python-novaclient
277 git remote -v
278 ACTION: query
280 Query RDO/distro repos for available package versions.
281 See rdopkg-adv-requirements(7) for complete example of query and other
283 requirements management actions.
284 This action uses repoquery to discover the latest package versions
286 available from RDO and other repos available on a supported
287 distibution.
288 See output of rdopkg info for supported releases and distros.
290 Query specific RELEASE/DIST:
292 rdopkg query kilo/el7 openstack-nova
294 Query all dists of a release and show what’s happening:
296 rdopkg query -v kilo openstack-nova
298 ACTION: reqquery
300 Query RDO/distro repos for versions defined in requirements.txt.
301 See rdopkg-adv-requirements(7) for a complete example of reqquery and
303 other requirements management actions.
304 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 Python module names listed in requirements.txt are mapped to package
311 names using the rdopkg.actionmods.pymod2pkg module.
312 Query requirements.txt from 2015.1 tag:
314 rdopkg reqquery -R 2015.1 kilo/el7
316 Query requirements.txt file:
318 rdopkg reqquery -r path/to/requirements.txt kilo/f21
320 Query .spec Requires (experimental):
322 rdopkg reqquery -s
324 Verbosely dump query results to a file and view them:
326 rdopkg reqquery -v -d
328 rdopkg reqquery -l
329 ACTION: reqcheck
331 Inspect requirements.txt vs .spec Requires.
332 See rdopkg-adv-requirements(7) for complete example of reqcheck and
334 other requirements management actions.
335 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 Python module names listed in requirements.txt are mapped to package
340 names using rdopkg.actionmods.pymod2pkg module.
341 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 Example:
347 rdopkg reqcheck
349 rdopkg reqcheck -s
350 ACTION: reqdiff
352 Show pretty diff of requirements.txt.
353 See rdopkg-adv-requirements(7) for a complete example of reqdiff and
355 other requirements management actions.
356 Use this to see how requirements changed between versions.
358 See diff between current and latest upstream version (automagic):
360 rdopkg reqdiff
362 See diff between current and specified version:
364 rdopkg reqdiff 2015.1
366 See diff between two supplied versions:
368 rdopkg reqdiff 2015.1 2015.2
370 ACTION: kojibuild
372 Build the package in koji.
373 Flow:
375 · Run equivalent of fedpkg build using disgusting fedpkg python
377 module.
378 · Watch the build.
380 Example:
382 rdopkg kojibuild
384 ACTION: amend
386 Amend last git commit with current dist-git changes and (re)generate
387 the commit message from %changelog.
388 This simple action is equivalent to running
390 git commit -a --amend -m "$AUTOMAGIC_COMMIT_MESSAGE"
392 See AUTOMAGIC → commit message for more information about the generated
394 commit message.
395 ACTION: squash
397 Squash last git commit into previous one. The commit message of the
398 previous commit is used.
399 This simple action is a shortcut for
401 git reset --soft HEAD~
403 git commit --amend --no-edit
404 This is useful for squashing commits created by lower level actions
406 such as update-patches.
407 ACTION: get-sources
409 Download package source archive.
410 Currently, Source0 from .spec file is downloaded.
412 ACTION: info
414 Show information about RDO packaging.
415 Use this command to find out about:
417 · currently supported RDO OpenStack releases
419 · which distros are supported for each release
421 · what branch to build from
423 · what build system to build in
425 · supported packages
427 · various repositories tied to a package
429 · package maintainers
431 This command is a human interface to rdoinfo.
433 Releases/dists/branches overview:
435 rdopkg info
437 Detailed information about a package:
439 rdopkg info novaclient
441 Filter packages by maintainers:
443 rdopkg info maintainers:jruzicka
445 ACTION: info-tags-diff
447 Show rdoinfo tag changes.
448 rdopkg info-tags-diff RDOINFODIR
450 will show per-package new/changed tags in rdoinfo between HEAD~..HEAD.
452 For an existing or new package, a list of changed tags is returned
454 Example:
456 $ rdopkg info-tags-diff ~/.rdopkg/rdoinfo
458 openstack-changed ['newton-uc', 'newton']
459 openstack-new-pkg ['under-review']
460 This is an interface to rdopkg.actionmods.rdoinfo:tags_diff().
462 ACTION: findpkg
464 Find and show the single best matching package in rdoinfo.
465 This command produces the same output as rdopkg info but
467 · smart search is performed on package name, project name and
469 upstream URL
470 · only a single matching package is shown
472 Use -s/--strict to disable magic substring search and only match whole
474 fields.
475 This command is a human interface to distroinfo.query.find_package()
477 function.
478 Examples of usage:
480 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 ACTION: conf
488 Display rdopkg’s local configuration.
489 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 Store your per-user configuration in ~/.rdopkg/conf.d/*.py, or store
495 system-wide configuration in /etc/rdopkg.d/*.py.
496 ACTION: tag-patches
498 Tag the local -patches branch with the package’s Name-Version-Release.
499 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 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 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 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
518 Instead of requiring project config files or endless lists of command
519 line arguments, rdopkg tries to guess all the necessary variables.
520 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 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 · rhos-5.0-rhel-7-patches
533 · rhos-5.0-rhel-patches
535 · rhos-5.0-patches ←-- preferred for RHOSP
537 · rhos-patches
539 Use rdopkg pkgenv to check detected patches branch.
541 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 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 git config rdopkg.rhel-7.4.patches-branch rhel-7-patches
553 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 Version: 2014.2.3
561 Then rdopkg will use 2014.2.3 as the base. If instead your .spec file
563 has:
564 %global milestone rc2
566 Version: 2014.2.3
568 Then rdopkg will use 2014.2.3rc2 as the base.
570 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 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 # patches_base=+2
581 You can set an arbitrary git revision as a patches base:
583 # patches_base=1.2.3+2
585 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 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 For example, if you add the following comments in your package’s .spec
597 file:
598 # patches_base=10.2.5
600 # patches_ignore=DROP-IN-RPM
601 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 Note: these lines should be directly above any Patch000X lines in your
606 .spec file.
607 Release bumping
609 rdopkg fix and rdopkg patch bump the Release tag in .spec file.
610 By default, last numeric only part of Release is bumped:
612 1.1.1.a.b.c -> 1.1.2.a.b.c
614 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 -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 DLRN 0.date.hash and 0.1.date.hash formats are detected and default to
627 bumping 2nd Release part (-R 2).
628 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 All rdopkg actions that modify distgit use following format:
634 package-name-1.2.3-4
636 Changelog:
638 - Doom the World (rhbz#111111)
639 - Fix Impending Doom support
640 - Save the World (rhbz#222222)
641 Resolves: rhbz#111111
643 Resolves: rhbz#222222
644 Change-Id: deadbeedeadbeedeadbeedeadbeedeadbeedeadbee
645 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 protip: To (re)generate nice commit message after modifying .spec file,
651 use rdopkg amend (see ACTION: amend above).
652 For example, following %changelog entry:
654 %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 will generate following commit message:
661 package-name-0.5.0-1
663 Changelog:
665 - Update to upstream 0.5.0
666 - Fix evil Bug of Doom (rhbz#123456)
667 Resolves: rhbz#123456
669 rdoinfo
671 rdoinfo is a special utility repository with RDO metadata:
672 https://github.com/redhat-openstack/rdoinfo
674 rdopkg uses rdoinfo to
676 · detect release/dist from branch name
678 · check valid RDO updates
680 · query packages from RDO/distribution repos
682 and more.
684 You can view the rdoinfo metada using rdopkg info.
686
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
694 rdopkg is maintained by Jakub Ruzicka <jruzicka@redhat.com>.
695 Bugs are tracked as github Issues:
697 https://github.com/softwarefactory-project/rdopkg/issues
699 To report a new bug:
701 https://github.com/softwarefactory-project/rdopkg/issues/new
703 01/30/2020 RDOPKG(1)