#96 Start documenting some of the peculiarities one can face while using rpmautospec
Merged 3 years ago by nphilipp. Opened 3 years ago by pingou.
fedora-infra/ pingou/rpmautospec doc_peculiarities  into  master

@@ -0,0 +1,7 @@ 

+ div.document {

+     width: 970px;

+ }

+ 

+ div.sphinxsidebar {

+     width: 250px;

+ }

file modified
+1 -2
@@ -48,5 +48,4 @@ 

  # Add any paths that contain custom static files (such as style sheets) here,

  # relative to this directory. They are copied after the builtin static files,

  # so a file named "default.css" will overwrite the builtin "default.css".

- # html_static_path = ["_static"]

- html_static_path = []

+ html_static_path = ["_static"]

file modified
+1
@@ -13,6 +13,7 @@ 

     opting-in

     autorel

     autochangelog

+    peculiarities

     install

     deploying

  

file added
+175
@@ -0,0 +1,175 @@ 

+ Peculiarities of `rpmautospec`

+ ==============================

+ 

+ `rpmautospec` has a few peculiarities that we are aware of. Some may get

+ fixed, others are considered negligible, but we still want to document them

+ here.

+ 

+ 

+ Changelog Order

+ ---------------

+ 

+ Build Order over Commit Date

+ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^

+ 

+ The changelog is generated from the commit logs in the order in which they

+ are encountered.

+ This means that depending on how your git tree is managed, with rebasing or

+ merge commits, you may end up with older commits showing in the history

+ after earlier ones. If both of these commits have been built (and therefore

+ tagged), they will show in the order they were built and not the order

+ they were committed.

+ 

+ For example:

+ 

+ ::

+ 

+     D: March 31st 2020     Update to 2.3.4

+     |

+     C: April 3rd 2020      Fix building on armv7 with gcc10

+     |

+     B: March 23rd 2020     Update to 1.5

+     |

+     A: March 20th 2019     Update to 1.0

+ 

+ 

+ The automatically generated changelog will look like:

+ 

+ ::

+ 

+     * Tue Mar 31 2020 Foo Bar <foo@bar.com> - 2.3.4-1

+     - Update to 2.3.4

+ 

+     * Fri Apr 03 2020 John Doe <john@doe.com> - 1.5-2

+     - Fix building for armv7 with gcc10

+ 

+     * Mon Mar 23 2020 Foo Bar <foo@bar.com> - 1.5-1

+     - Update to 1.5

+ 

+     * Wed Mar 20 2019 Jane Smith <jane@smith.com> - 1.0-1

+     - Update to 1.0

+ 

+ 

+ Multiple Builds From a Given Commit

+ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

+ 

+ With `rpmautospec`, a commit can be rebuilt multiple times for the same

+ Fedora release. It will always get a newer release, so this works fine.

+ 

+ However, this means that we can "downgrade" a build to an older commit

+ without doing a ``git revert`` as long as the ``Version`` does not change

+ between the two commits.

+ 

+ Say we have the following situation:

+ 

+ ::

+ 

+     B: April 4th 2020     Add patch to fix unicode error

+     |

+     A: April 1st 2020     Update to 1.2

+ 

+ 

+ On April 1st, we built ``1.2-1`` and on April 4th ``1.2-2``. Now if there

+ are multiple people working on the package and one of them had not updated

+ their git repository since April 3rd and happens to trigger a build while

+ still being on commit A, the outcome will be a ``1.2-3`` build, without the

+ patch added in commit B.

+ 

+ If this happens, there will be two builds for commit A: ``1.2-1`` and

+ ``1.2-3``. `rpmautospec` will consider the highest build when generating

+ the changelog, which will therefore look like:

+ 

+ ::

+ 

+ 

+     * Sat Apr 04 2020 Foo Bar <foo@bar.com> - 1.2-2

+     - Add patch to fix unicode error

+ 

+     * Wed Apr 01 2020 John Doe <john@doe.com> - 1.2-3

+     - Update to 1.2

+ 

+ 

+ Old Packages Without ``changelog`` File

+ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

+ 

+ If you opt in for an old package, remove the content of its `%changelog`

+ section and do not include it in a ``changelog`` file, you will have to

+ manually tag the old builds of this package.

+ 

+ You can easily do this with the `rpmautospec` CLI::

+ 

+     rpmautospec tag-package --tag-all-builds /path/to/distgit/clone

+ 

+ The reason behind this is that to save time when building the SRPM, the

+ `rpmautospec` Koji plugin will only tag the latest build in every Fedora

+ release, but the changelog generation code uses these git tags to associate

+ commits with specific release, and if the tags corresponding to old builds are

+ missing, you will end up with changelog entry referring about an ``Update to

+ 1.2`` while having a version-release like: ``1.3-1`` (corresponding to the

+ last tag available).

+ 

+ 

+ Scratch Builds

+ --------------

+ 

+ In Fedora, we have two ways to do scratch builds today:

+ 

+ - ``fedpkg build --scratch``: This basically does a regular build from a git

+   reference but with ``scratch=True``. These builds will work just fine with

+   `rpmautospec` as the spec file will be updated in the ``buildSRPMFromSCM``

+   task, just as for regular builds.

+ 

+ - ``fedpkg scratch-build --srpm``, which generates an SRPM locally and uploads

+   it to Koji for it to be rebuilt and be built into binary RPMS. This approach

+   will not work with `rpmautospec` currently. To make this approach work with

+   `rpmautospec`, you will need to process the spec file locally before

+   uploading the SRPM. You can do so by simply calling::

+ 

+     rpmautospec process-distgit /path/to/distgit/clone [dist-tag]

+ 

+ 

+ ``fedpkg`` Output

+ -----------------

+ 

+ Warnings and Errors when Building

+ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

+ 

+ You may run into the following warnings/errors when doing a ``fedpkg build``:

+ 

+ ::

+ 

+     warning: line 5: Possible unexpanded macro in: Release:        %autorel

+     warning: line 26: Possible unexpanded macro in: Requires:       libeconf(x86-64) = 0.3.3-%autorel

+     error: %changelog entries must start with *

+ 

+ This is because the ``%autorel`` and ``%autochangelog`` RPM macros aren't

+ defined in your system. To fix this, simply install the

+ ``rpmautospec-rpm-macros`` package:

+ 

+ ::

+ 

+     sudo dnf install rpmautospec-rpm-macros

+ 

+ Release and Changelog Differ Between Local Build and Koji

+ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

+ 

+ If you have installed the ``rpmautospec-rpm-macros`` package as described

+ above and run ``fedpkg build``, you'll notice that the release is always

+ ``-1`` (or a variant, depending on the flags used with ``%autorel``) and that

+ the changelog is just one entry without useful information, even though build

+ in Koji would have a sequential release number and a full changelog.

+ 

+ This is because ``fedpkg build`` uses the placeholder RPM macros from

+ ``rpmautospec-rpm-macros`` to keep tools such as ``rpmbuild`` or ``fedpkg

+ local`` working.

+ 

+ If you want to see how the correct release and changelog would look like, you

+ can call the ``rpmautospec`` CLI tool. Run ``rpmautospec --help`` for more

+ information.

+ 

+ Alternatively, you can manually override the value of the ``autorel`` macro

+ for ``rpmbuild`` or ``fedpkg``, e.g.::

+ 

+     fedpkg local --define "autorel(e:s:hp) 4%{?dist}"

+ 

+     rpmbuild --define "autorel(e:s:hp) 4%{?dist}" -ba somepackage.spec

Signed-off-by: Pierre-Yves Chibon pingou@pingoured.fr

rebased onto 1ed48c8fc91482d7c016077418129a73fdd84798

3 years ago

1 new commit added

  • Add our own custom.css file so we can customize a little bit how it looks
3 years ago

Build succeeded.

1 new commit added

  • Document the state of the integration between rpmautospec and scratch builds
3 years ago

Build succeeded.

rebased onto 021280058db09b2a01702ec21688f4991bca1827

3 years ago

Note that this doesn't currently work as is, but we should figure out how to make it work or how to adjust the doc :)

Build succeeded.

5 new commits added

  • Document unexpected behavior if old git tags are missing and no 'changelog' file is present
  • Start documenting the peculiarities one can face when using rpmautospec with fedpkg
  • Document the state of the integration between rpmautospec and scratch builds
  • Add our own custom.css file so we can customize a little bit how it looks
  • Start documenting some of the peculiarities one can face while using rpmautospec
3 years ago

Build succeeded.

rebased onto f1d0d5450f25bc15ba9db25178b325f1be51aa8b

3 years ago

Metadata Update from @nphilipp:
- Request assigned

3 years ago

Pushed my suggested changes as a "review commit".

rebased onto 20d2971

3 years ago

Pull-Request has been merged by nphilipp

3 years ago

Build succeeded.