fedora-infra / rpmautospec

Clone

#85 Docs: not yet supported use cases and misc polishing
Merged 4 years ago by pingou. Opened 4 years ago by nphilipp.
fedora-infra/ nphilipp/rpmautospec master--docs  into  master

file modified
+14 -14 
@@ -1,30 +1,30 @@ 
 

  .. _using-autochangelog:
 

  

- Using the ``%autochangelog`` macro
 

+ Using the ``%autochangelog`` Macro
 

  ==================================
 

  

- rpmautospec combines two sources of information to generate a changelog that
 

- is inserted in the spec file where the ``%autochangelog`` macro is set.
 

+ `rpmautospec` combines two sources of information to generate a changelog
 

+ which is inserted in the spec file where the ``%autochangelog`` macro is set.
 

  

  These two sources of information are:
 

  

- * A ``changelog`` file potentially present in the dist-git repository of
 

-   the package when it is built. If that file is present it is included
 

-   **as is** in the spec file (i.e. be careful how you format this file).
 

+ * An optional ``changelog`` file in the dist-git repository of the package. If
 

+   this file is present, it is included **as is** in the spec file (i.e. be
 

+   careful how you format this file).
 

  

  * The git history of the package between the most recent commit touching
 

-   the ``changelog`` file and the latest commit made to the package.
 

+   ``changelog`` and the latest commit made to the package.
 

  

  

- Some examples:
 

+ Some Examples:
 

  --------------
 

  

  .. _only commits example:
 

  

- Only commits
 

+ Only Commits
 

  ^^^^^^^^^^^^
 

  

- If a package has no ``changelog`` file, rpmautospec will only use the git
 

+ If a package has no ``changelog`` file, `rpmautospec` will only use the git
 

  history to generate the changelog.
 

  

  Thus if the history looks like:
 
@@ -64,10 +64,10 @@ 
 

  

  .. _commits and changelog example:
 

  

- Commits and changelog
 

+ Commits and Changelog
 

  ^^^^^^^^^^^^^^^^^^^^^
 

  

- If a package has a ``changelog`` file, rpmautospec will only generate entries
 

+ If a package has a ``changelog`` file, `rpmautospec` will only generate entries
 

  from the commits after its last change and then append its contents verbatim.
 

  

  So if the changelog file looks like:
 
@@ -92,8 +92,8 @@ 
 

      * Mon Jun 18 2018 Jane Smith <jane@smith.com> - 0.9-1
 

      - Initial import
 

  

- (Do you see the lack of use of ``-`` between the email and version-release
 

- in the entries from Foo Bar?)
 

+ (Note the lack ``-`` between the email and version-release in the entries from
 

+ "Foo Bar".)
 

  

  

  And the history looks like:

file modified
+19 -15 
@@ -1,20 +1,19 @@ 
 

  .. _using-autorel:
 

  

- Using the ``%autorel`` macro
 

+ Using the ``%autorel`` Macro
 

  ============================
 

  

- Fedora's `Versioning Guidelines`_ define the different element that can
 

- compose a release field as follow:
 

+ Fedora's `Versioning Guidelines`_ define the different elements of which a
 

+ release field can consist. They are as follows:
 

  

  ::
 

  

      <pkgrel>[.<extraver>][.<snapinfo>]%{?dist}[.<minorbump>]
 

  

- Where each element in square brackets indicates an optional item.
 

+ Each element in square brackets indicates an optional item.
 

  

- 

- The ``%autorel`` macro accepts therefore some parameters to allow the packagers
 

- to specify the different portions of the release field:
 

+ The ``%autorel`` macro accepts these parameters to allow packagers to specify
 

+ the different portions of the release field:
 

  

  * ``-h <hotfix>``: Designates a hotfix release, i.e. enables bumping the
 

    ``minorbump`` portion in order to not overrun EVRs in later Fedora versions.
 
@@ -24,12 +23,17 @@ 
 

  * ``-s <snapinfo>``: Allows specifying the ``snapinfo`` portion of the release.
 

  

  

- Some examples:
 

+ .. warning::
 

+     To date, only the normal release cadence is fully implemented. Please don't use the hotfix or
 

+     pre-release parameters yet, attempting to build such packages will fail.
 

+ 

+ 

+ Some Examples:
 

  --------------
 

  

  .. _simple example:
 

  

- The simple case
 

+ The Simple Case
 

  ^^^^^^^^^^^^^^^
 

  

  .. include:: examples/test-autorel.spec
 
@@ -44,7 +48,7 @@ 
 

  

  .. _hotfix example:
 

  

- The hotfix case
 

+ The Hotfix Case
 

  ^^^^^^^^^^^^^^^
 

  

  .. include:: examples/test-autorel-hotfix.spec
 
@@ -59,8 +63,8 @@ 
 

  

  .. _prerelease example:
 

  

- The prerelease case
 

- ^^^^^^^^^^^^^^^^^^^
 

+ The Pre-Release Case
 

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

  

  .. include:: examples/test-autorel-prerelease.spec
 

     :literal:
 
@@ -74,7 +78,7 @@ 
 

  

  .. _extraver case:
 

  

- The extraver case
 

+ The Extraver Case
 

  ^^^^^^^^^^^^^^^^^
 

  

  .. include:: examples/test-autorel-extraver.spec
 
@@ -89,7 +93,7 @@ 
 

  

  .. _snapshot case:
 

  

- The snapshot case
 

+ The Snapshot Case
 

  ^^^^^^^^^^^^^^^^^
 

  

  .. include:: examples/test-autorel-snapshot.spec
 
@@ -104,7 +108,7 @@ 
 

  

  .. _snapshot_and_extraver case:
 

  

- The snapshot and extraver case
 

+ The Snapshot and Extraver case
 

  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

  

  .. include:: examples/test-autorel-extraver-snapshot.spec

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

  # 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 = ["_static"]
 

+ html_static_path = []

file modified
+20 -21 
@@ -1,33 +1,32 @@ 
 

- Deploying rpmautospec
 

- =====================
 

+ Deploying `rpmautospec`
 

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

  

- As of April 2020, rpmautospec has been deployed in staging but there is still
 

- some work to be done or checked before it can be deployed in production.
 

- This page aims at documenting what remains to be done before rpmautospec can
 

- be deployed in production.
 

+ As of April 2020, `rpmautospec` has been deployed in the Fedora staging
 

+ infrastructure but there is still some work to be done or checked before it
 

+ can be deployed in production. This section aims at documenting what remains
 

+ to be done before `rpmautospec` can be deployed in production.
 

  

- * rpmautospec relies on a new API endpoint allowing to add git tags to a project
 

-   remotely that was added on pagure 5.9.
 

-   So before rpmautospec can be deployed in production, pagure on dist-git must
 

-   be upgraded to 5.9 or higher.
 

+ * `rpmautospec` relies on a new API endpoint allowing to add git tags to a
 

+   project remotely which was added in Pagure 5.9. So before `rpmautospec` can
 

+   be deployed in production, Pagure on dist-git must be upgraded to 5.9 or
 

+   higher.
 

  

- * rpmautospec uses an API token to act on pagure on dist-git via its API.
 

-   So before rpmautospec can be deployed in production, an API token for pagure
 

-   on dist-git must be created with the ACL ``tag_project`` and associated to the
 

+ * `rpmautospec` uses an API token for authentication in Pagure. So before
 

+   `rpmautospec` can be deployed in production, an API token for Pagure on
 

+   dist-git must be created with the ACL ``tag_project`` and associated to the
 

    ``releng`` user.
 

  

- * rpmautospec uses two koji plugins that are currently only installed in koji
 

-   in staging.
 

-   So before rpmautospec can be deployed in production the following files must
 

-   be adjusted for production:
 

+ * `rpmautospec` uses two Koji plugins that are currently only installed in the
 

+   Koji staging instance. So before `rpmautospec` can be deployed in
 

+   production, the following files must be adjusted in Ansible for production:
 

+ 

      - roles/koji_hub/tasks/main.yml
 

      - roles/koji_hub/templates/rpmautospec.conf
 

      - roles/koji_hub/templates/hub.conf.j2
 

      - roles/koji_builder/tasks/main.yml
 

      - roles/koji_builder/templates/kojid.conf
 

  

- * rpmautospec currently does not support the hotfix workflow documented in
 

-   :ref:`using-autorel`.
 

-   So before rpmautospec can be deployed in production, its should be improved
 

-   to support this use-case.
 

+ * `rpmautospec` currently does not support the hotfix or pre-release cadences documented in
 

+   :ref:`using-autorel`. So before `rpmautospec` is deployed in production,
 

+   these use cases should be fully implemented.

file modified
+4 -4 
@@ -1,8 +1,8 @@ 
 

- Welcome to rpmautospec's documentation!
 

- =======================================
 

+ Welcome to the documentation of `rpmautospec`!
 

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

  

- rpmautospec is the program and library used to automatically generate
 

- the release and changelog fields in RPM spec files that chose to use it.
 

+ `rpmautospec` is a program and library used to automatically generate the
 

+ release and changelog fields in RPM spec files opting to use it.
 

  

  

  .. toctree::

file modified
+25 -22 
@@ -1,36 +1,38 @@ 
 

- Installing rpmautospec
 

- ======================
 

+ Installing `rpmautospec`
 

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

  

- rpmautospec is composed of a few elements:
 

- - a python library (which includes a small CLI tool)
 

- - a koji-hub plugin
 

- - a koji-builders plugin
 

+ `rpmautospec` consists of these components:
 

+ - a Python library (which includes a small CLI tool)
 

+ - a plugin for the Koji hub
 

+ - a plugin for Koji builders
 

  

- Each needs to be correctly installed and configured for rpmautospec to work
 

+ Each needs to be correctly installed and configured for `rpmautospec` to work
 

  properly.
 

  

- .. Note: This document relies on the premise that koji-hub runs on python2
 

-          while the builders are running in python3.
 

+ .. note:
 

+     This document relies on the premise that the Koji hub runs on Python 2
 

+     while the builders run on Python 3.
 

  

  

- Installing the python library
 

+ Installing the Python Library
 

  -----------------------------
 

  

- The python library is handled via a traditional ``setup.py`` file. It can
 

+ The Python library is handled via a traditional ``setup.py`` file. It can
 

  therefore be installed simply by doing:
 

  

- `` python setup.py install``.
 

+ ``python setup.py install``.
 

  

- .. warning: that the library is python3 only except for a sub-package:
 

+ .. warning:
 

+     The library works only with Python 3 except for one sub-package:
 

      ``rpmautospec.py2compat``.
 

  

  

- Installing the koji-hub plugin
 

+ Installing the Koji Hub Plugin
 

  ------------------------------
 

  

- The koji plugin ``rpmautospec_hub`` is meant to be installed on the koji hub
 

- in: ``/usr/lib/koji-hub-plugins/``.
 

- It is python2 compatible and requires the package ``rpmautospec.py2compat``.
 

+ The Koji plugin ``rpmautospec_hub`` is meant to be installed on the Koji hub
 

+ in: ``/usr/lib/koji-hub-plugins/``. It is compatible with Python 2 and
 

+ requires the package ``rpmautospec.py2compat``.
 

  

  This plugin also requires a configuration file at:
 

  ``/etc/koji-hub/plugins/rpmautospec.conf``
 
@@ -39,14 +41,15 @@ 
 

  ``koji_plugins/rpmautospec.conf``
 

  

  The plugin can then be enabled by adding: ``rpmautospec_hub`` in the line
 

- ``Plugins`` in the ``/etc/koji-hub/hub.conf`` configuration file for koji hub.
 

+ ``Plugins`` in the ``/etc/koji-hub/hub.conf`` configuration file for the Koji
 

+ hub.
 

  

  

- Installing the koji-builders plugin
 

+ Installing the Koji Builders Plugin
 

  -----------------------------------
 

  

- The koji plugin ``rpmautospec_builder`` is meant to be installed on all the
 

- koji builders running the ``buildSRPMFromSCM`` task in:
 

+ The Koji plugin ``rpmautospec_builder`` is meant to be installed on all the
 

+ Koji builders running the ``buildSRPMFromSCM`` task in:
 

  ``/usr/lib/koji-builder-plugins/``.
 

  

  This plugin also requires a configuration file at:
 
@@ -56,5 +59,5 @@ 
 

  ``koji_plugins/rpmautospec.conf``
 

  

  The plugin then can be enabled by adding: ``rpmautospec_builder`` in the line
 

- ``plugins`` in the ``/etc/kojid/kojid.conf`` configuration file for the koji
 

+ ``plugins`` in the ``/etc/kojid/kojid.conf`` configuration file for the Koji
 

  builders.

file modified
+7 -14 
@@ -1,19 +1,13 @@ 
 

- Opting into using rpmautospec
 

- =============================
 

+ Opting into using `rpmautospec`
 

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

  

- To opt into using rpmautospec you need to use the two macros as explained here
 

- below:
 

+ To opt into using `rpmautospec` you need to use the two macros as explained
 

+ here below:
 

  

  Use the ``%autorel`` macro
 

  --------------------------
 

  

- Basically, you need to replace in your spec file the line:
 

- 

- ::
 

- 

-    Release:     ...{%dist}
 

- 

- for example:
 

+ Basically, in the spec file you replace the manually set release, e.g.:

I think I would replace e.g. by something like as follow

Nevermind, now that I see the change in the full page, it's good as is.

 
  

  ::
 

  
@@ -35,9 +29,8 @@ 
 

  For new packages
 

  ^^^^^^^^^^^^^^^^
 

  

- If you are using this macro from a brand-new package that has no git
 

- history, you can simply put at the end of your spec file the following two
 

- lines:
 

+ If you use this macro in a brand-new package without git history, you can
 

+ simply put the following two lines at the end of your spec file:
 

  

  ::

file modified
+20 -20 
@@ -1,39 +1,39 @@ 
 

- rpmautospec's principle
 

- =======================
 

+ The Principle of `rpmautospec`
 

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

  

- The goal of rpmautospec it to relieve packagers from the burden of manually
 

+ The goal of `rpmautospec` it to relieve packagers from the burden of manually
 

  updating the ``Release`` and ``%changelog`` fields in RPM spec files.
 

  

+ The way it works in Koji is that just after the git repository has been
 

+ cloned, a dedicated plugin is run to preprocess the spec file:
 

  

- The way it works in koji is:
 

+ * The plugin checks if the packager has opted in, and if not, stops right
 

+   here. All following steps are only run if the packager has opted in.
 

  

- * Just after the git repo has been cloned, a dedicated koji plugin calls
 

-   the ``rpmautospec`` library.
 

+ * The plugin consults available information about the latest NEVRs built for
 

+   this package and tags them in the git repository.
 

  

- * The library checks if the packager has opted in, if the packager has
 

-   not opted in, the plugin stops there.
 

+ * The plugin then installs and calls ``rpmautospec`` in the chroot.
 

  

- * If the packager has opted in, the plugin consults available information about
 

-   the latest NEVRs built for this package.
 

+ * Using the list tags of built NEVRs as well as the information provided by
 

+   the packager in the spec file, `rpmautospec` then computes the next best
 

+   release number for the package.
 

  

- * Using the list of the lastest NEVR built as well as the information provided
 

-   by the packager in the spec file, the library the computes the next best
 

-   release number for the package
 

- 

- * The plugin prepends a suitably defined ``%autorel`` macro to the top of the
 

-   spec file, freezing the computed value of the release number thus allowing
 

+ * It prepends a suitably defined ``%autorel`` macro to the top of the spec
 

+   file, freezing the computed value of the release number and thus allowing
 

    reproducible builds.
 

  

- * Then the library generates the changelog of the package from the contents of
 

-   the ``changelog`` file, if present, and the git commit logs after it was
 

+ * Then `rpmautospec` generates the changelog of the package from the contents
 

+   of the ``changelog`` file, if present, and the git commit logs after it was
 

    changed last.
 

  

- * The plugin then replaces the ``%autochangelog`` macro with the generated
 

-   changelog.
 

+ * Finally, `rpmautospec` replaces the ``%autochangelog`` macro with the
 

+   generated changelog.
 

  

  At this point, the spec file has the release macro defined at its top and
 

  a changelog defined at its bottom, it is a fully functional spec file that
 

  is passed onto the rest of the "build SRPM" process.
 

+ 

  The resulting SRPM can be reproducibly built, locally or in another build
 

  system. Note that none of the changes made to the spec file are committed back
 

  to the git repository.

file modified
+3 -3 
@@ -19,9 +19,9 @@ 
 

  autorel_macro_path = os.path.join(__here__, "etc", "autorel-macro.txt")
 

  autorel_template = """## START: Set by rpmautospec
 

  %define _autorel_normal_cadence {autorel_normal}%{{?_autorel_extraver}}%{{?_autorel_snapinfo}}%{{?dist}}
 

- %define _autorel_hotfix_cadence %nil
 

- %define _autorel_prerel_cadence %nil
 

- %define _autorel_prerel_hotfix_cadence %nil
 

+ %define _autorel_hotfix_cadence Sorry, the hotfix cadence isn't implemented yet.
 

+ %define _autorel_prerel_cadence Sorry, the pre-release cadence isn't implemented yet.
 

+ %define _autorel_prerel_hotfix_cadence Sorry, the hotfix, pre-release cadences aren't implemented yet.
 

  ## END: Set by rpmautospec
 

  """  # noqa: E501

no initial comment

Build failed.

Metadata Update from @pingou:
- Request assigned
4 years ago

This is likely better english but I find it harder to read ^_^

I guess this is what black is unhappy with, misses a space after the #

must be adjusted in Ansible for production?

I think I would replace e.g. by something like as follow

Considering how we've changed things recently, we may want to rework this section in the future, but this can be done in another PR

Nevermind, now that I see the change in the full page, it's good as is.

Yeah this didn't improve it. No need to pack it all into one sentence: "Fedora's Versioning Guidelines_ define the different elements of which a release field can consist. They are as follows:"

Oops. :blush:

Good call. :100:

rebased onto f940240dfefe79589429ce799f69d02de7ef9cc6
4 years ago

We could just replace the `rpmautospec` library with plain `rpmautospec.`

4 new commits added

  • Rework a little bit the documentation on how rpmautospec works in koji
  • Small suggestion form pingou -- to squash
  • Polish up documentation
  • Warn about not yet supported use cases
4 years ago

We could just replace the rpmautospec library with plain rpmautospec.

That's what I did in addition to mentioning we're installing it in the chroot :)

Build succeeded.

rebased onto edaa0fb
4 years ago

2 new commits added

  • Polish up documentation
  • Warn about not yet supported use cases
4 years ago

:thumbsup: for me

hm isn't it always necessary?

Build succeeded.

2 new commits added

  • Polish up documentation
  • Warn about not yet supported use cases
4 years ago

Zuul already finished 2 of its 3 tasks and we're not touching the spec file so this shouldn't impact the RPM.

So :thumbsup: for me, let's get this in :)

Pull-Request has been merged by pingou
4 years ago

Build succeeded.
Changes Summary 9
+14 -14
file changed
doc/autochangelog.rst
+19 -15
file changed
doc/autorel.rst
+2 -1
file changed
doc/conf.py
+20 -21
file changed
doc/deploying.rst
+4 -4
file changed
doc/index.rst
+25 -22
file changed
doc/install.rst
+7 -14
file changed
doc/opting-in.rst
+20 -20
file changed
doc/principle.rst
+3 -3
file changed
rpmautospec/process_distgit.py
Powered by Pagure 5.13.3
Documentation • File an Issue • About • SSH Hostkey/Fingerprint
© Red Hat, Inc. and others.