PR#1990: doc: document the rpkg-util v3 problem - copr/copr

copr / copr

#1990 doc: document the rpkg-util v3 problem

Merged 3 years ago by msuchy. Opened 3 years ago by praiskup.

Unknown source docs-rpkg-util into main

doc: document the rpkg-util v3 problem

Pavel Raiskup • 3 years ago

3c6b88b

doc/rpkg_util_2_vs_3.rst

file added

+71

		`@@ -0,0 +1,71 @@`
		`+ :orphan:`
		`+`
		`+ .. _rpkg_util_v3:`
		`+`
		`+ The rpkg-util v2 vs v3 differences`
		`+ ==================================`
		`+`
		+ The major difference is that the ``auto_pack =`` configuration option was
		+ dropped in the ``rpkg`` utility, and namely that even the default behavior
		+ (``auto_pack = True``) was changed entirely (after a long period of feature
		`+ deprecation).`
		`+`
		`+ So, while for quite some time you've probably seen builds succeeding, and output`
		+ similar to the following one (in source RPM ``builder-live.log`` files)::
		`+`
		`+ ...`
		`+ Running: rpkg srpm --outdir /var/lib/copr-rpmbuild/results --spec /var/lib/copr-rpmbuild/workspace/workdir-p7s1qop1/copr-hello`
		`+ ...`
		`+ stdout: Wrote: /var/lib/copr-rpmbuild/results/example.spec`
		`+ Wrote: /var/lib/copr-rpmbuild/results/example-1.0.13.tar.gz`
		`+ setting SOURCE_DATE_EPOCH=1518912000`
		`+ Wrote: /var/lib/copr-rpmbuild/results/example-1.0.13-1.fc34.src.rpm`
		`+ stderr: auto-packing: This function is deprecated and will be removed in a future release.`
		`+`
		`+ Note the deprecation error output! But newly you see build failures, and output`
		`+ like::`
		`+`
		`+ ...`
		`+ Running: rpkg srpm --outdir /var/lib/copr-rpmbuild/results --spec /var/lib/copr-rpmbuild/workspace/workdir-49_sbnvg/copr-hello`
		`+ ...`
		`+ rc: 0`
		`+ stdout: Wrote: /var/lib/copr-rpmbuild/results/example.spec`
		`+ stderr: error: Bad source: /var/lib/copr-rpmbuild/results/example-1.0.13.tar.gz: No such file or directory`
		`+ Failed to execute command.`
		`+`
		`+ Output: ['example.spec']`
		`+`
		`+ Or even something like::`
		`+`
		`+ Running: rpkg srpm --outdir /var/lib/copr-rpmbuild/results --spec /var/lib/copr-rpmbuild/workspace/workdir-ffz7kky4/copr-hello`
		`+ ...`
		`+ rc: 1`
		`+ stdout: Wrote: /var/lib/copr-rpmbuild/results/example.spec`
		`+ stderr: error: Bad source: /var/lib/copr-rpmbuild/results/example-1.0.13.tar.gz: No such file or directory`
		`+`
		`+ Copr build error: error: Bad source: /var/lib/copr-rpmbuild/results/example-1.0.13.tar.gz: No such file or directory`
		`+`
		`+`
		`+ How am I supposed to fix this`
		`+ -----------------------------`
		`+`
		`+ First, if you build your package from a DistGit instance (e.g. from`
		+ ``src.fedoraproject.org``, ``git.centos.org``, etc.), you are encouraged to use
		+ the :ref:`Copr DistGit build method <dist-git method>`.
		`+`
		`+ If you build from a git forge (GitHub, GitLab, ...) and you see build failures`
		`+ like those above, the problem is most likely that your spec file is not using`
		+ the ``{{{ ... }}}`` templates, and you rely on the already removed ``auto_pack =
		+ True`` feature.
		`+`
		+ Please take a look at the `rpkg-util documentation`_, and perhaps get an
		+ inspiration from the `example commit`_ which makes the package compatible with
		`+ both rpkg-util v2 and v3.`
		`+`
		+ If for any reason you can not use the new `rpkg-util` syntax, take a look at the
		+ :ref:`other source methods<scm_ref>` Copr supports.
		`+`
		`+`
		+ .. _`rpkg-util documentation`: https://pagure.io/rpkg-util
		+ .. _`example commit`: https://pagure.io/copr/copr-hello/c/739ff9910ee8a9c76d7e97de2f6176106dc19a09?branch=rpkg-util
		+ .. _`DistGit`: https://github.com/release-engineering/dist-git

doc/user_documentation.rst

file modified

+23 -4

		`@@ -76,10 +76,15 @@`
		`The last optional thing to configure (except for common build configuration option) is the SRPM build method. There are four choices available:`
		`rpkg, tito, tito test, and make srpm:`

		`- rpkg: The default choice and the most versatile one. Apart from building packages from any Git or SVN repository,`
		- it also supports building directly from any `DistGit <https://clime.github.io/2017/05/20/DistGit-1.0.html>`_ repository.
		`- Note that rpkg (as well as tito) is not only a tool to generate SRPMs but, in fact, it is also a full-fledged package manager`
		- that you can use from your command-line to maintain your packages. You can read more about this tool `here <https://pagure.io/rpkg-util>`__.
		`+ rpkg: The default method. Apart from building packages from any Git or SVN`
		+ repository, it also supports building directly from `DistGit`_ repositories.
		`+ Note that rpkg (as well as tito below) is not only a tool to generate`
		`+ SRPMs but, in fact, it is also a full-fledged package manager`
		`+ that you can use from your command-line to maintain your (upstream) projects.`
		+ You can read more about this tool `here <https://pagure.io/rpkg-util>`__.
		`+ Note that starting from December 2021, Copr migrated to the rpkg-util v3,`
		+ and so :ref:`your spec files need to use the {{{ }}} templates to comply
		+ <rpkg_util_v3>`.

		`tito: is a robust RPM package manager with lots of features and if your project is managed with Tito, this is the tool you want to pick for SRPM generation (which is`
		`one of the many package manager's features). When this option is selected, the latest package GIT tag will be used to build an SRPM. Note that this utility has currently`
		`@@ -121,6 +126,8 @@`

		`Note that the other tools (tito and rpkg) are run in the specified Subdirectory as well.`

		+ .. _`dist-git method`:
		`+`
		`DistGit`
		`^^^^^^^`

		`@@ -631,6 +638,17 @@`
		the `non-cached host variant
		<http://copr-be.cloud.fedoraproject.org/results/>`_.

		+ .. _`Weird SCM build failure?`:
		`+`
		+ .. rubric:: Weird SCM build failure? :ref:`¶ <Weird SCM build failure?>`
		`+`
		+ It worked for me before, but I newly see the ``rpkg`` errors like::
		`+`
		`+ Running: rpkg srpm --outdir /var/lib/copr-rpmbuild/results ...`
		`+ Copr build error: error: Bad source: /var/lib/copr-rpmbuild/results/example-1.0.13.tar.gz: No such file or directory`
		`+`
		+ Please take a look at :ref:`rpkg_util_v3`.
		`+`

		.. _`I have a problem and I need to talk to a human.`:

		`@@ -638,3 +656,4 @@`

		We do not provide support per se, but try your luck here: :ref:`communication`

		+ .. _`DistGit`: https://clime.github.io/2017/05/20/DistGit-1.0.html