How to release fix in Ansible collection

tags: Documentation Ansible

The story here is related to latest changes in TripleO and Ansible. Since we started to use Ansible collections as RPMs, this document is going to describe the process of fix release from submitting it to collection repository till OSP release

Ansible Podman collection release process

Resources:

Guide:

  1. Fork ansible-podman-collections repository from: https://github.com/containers/ansible-podman-collections

  2. Create a fix and pull request to original repository. Wait for CI and ask for review and merge. (In this collection mostly for @sshnaidm)

  3. After merge start a releasing process by releasing to Galaxy:

    • create an entry of changelog in changelogs/changelog.yaml
    • run antsibull-changelog release command (install antsibull tool before)
    • check changelogs/changelog.yaml file and generated changelog in CHANGELOG.rst and fix if need
      • (optional) generate documentation with command ./build_docs.sh <your_path_to>/ansible-podman-collections/docs from contrib folder
    • change version in galaxy.yaml file to the new one.
    • if everything is ok, commit and merge changes in changelog or/and docs
    • git tag <version_tag> where <version_tag> is tag of the new version - for example 2.3.4
    • push tags to upstream - git push upstream <version_tag>
    • wait until check and release jobs finish and check in galaxy that new version is uploaded: https://galaxy.ansible.com/containers/podman

  4. Build and release RPM in Fedora (which will be imported to RDO later)

    • install all required tools, mainly fedpkg

    • create a space for work if no such: mkdir fedora-scm

    • fork Fedora repository rpms/ansible-collection-containers-podman.

      NOTE: If you are not in admins, then you will need to make a PR, otherwise you can just commit directly to repo.

    • clone original or your forked repo such as https://src.fedoraproject.org/fork/sshnaidm/rpms/ansible-collection-containers-podman with fedpkg clone rpms/ansible-collection-containers-podman (or for PRs: fedpkg clone forks/sshnaidm/rpms/ansible-collection-containers-podman where instead of sshnaidm your username)

    • cd ansible-collection-containers-podman and check that you are on branch rawhide, if not run fedpkg switch-branch rawhide

    • Retrieve new sources from github: wget https://github.com/containers/ansible-podman-collections/archive/<version_tag>.tar.gz where <version_tag> is a new version, like 2.4.1

      Or run spectool -g *spec after you changed the spec file:

    • Bump version in *.spec file as in this example for 1.9.4:

      ​​​​​​+Version:        <version-tag>
​​​​​​+Release:        1%{?dist}

      and add changelog, sort of:

      ​​​​​​+* Tue Jun 08 2021 Sagi Shnaidman <sshnaidm@redhat.com> - <version-tag>-1
​​​​​​+- Bump to <version-tag>-1

    • Upload sources you downloaded before: fedpkg new-sources <version-tag>.tar.gz

    • fedpkg mockbuild to check building (optional)

    • Verify and commit code:

      • fedpkg diff
      • fedpkg lint (to check linters on RPM)
      • fedpkg commit with message like "Bump to <version-tag>"

    • Push changes for rawhide and let Koji build the package:

    • Repeat for older branches, e.g. Fedora 36:

    • Repeat previous steps for branch epel9.

  5. Promote built RPM to RDO:

Ansible OpenStack collection release process

Content has been migrated to docs/releasing.md in Ansible OpenStack collection.

Ansible community.general, ansible.posix and ansible.netcommon collections release process

  1. Submit PR to collection in its repo

  2. Test PR with upstream or RDO job.

    • In upstream run a job and set PR in commit message with "github: " keyword: For example use this commit message to test PR 215 from ansible.posix: 
      ​​​​​​DNM test PR with our jobs
​​​​​​
​​​​​​This patch is for test.
​​​​​​github: https://github.com/ansible-collections/ansible.posix/pull/215
​​​​​​
​​​​​​Change-ID: ......
      Same can be used in testproject of RDO CI or whenever else.

  3. If test passed and your're satisfied with its results, wait until PR is merged and collection is released. (TBD)

  4. Submit a patch to updated RPM with a new version:

  5. Fork the RPM specs repo, for example press button Fork in the page os netcommon repo to fork it to your space.

  6. Clone it to your machine with SSH:// transport. For example: git clone ssh://sshnaidm@pkgs.fedoraproject.org/forks/sshnaidm/rpms/ansible-collection-ansible-netcommon.git

  7. Update spec file and add changelog.

  8. Get the new sources tarball: spectool -g *spec

  9. Upload the tarball to sources: fedpkg new-sources ./path/to/tar.gz. Look at sources that it has right tarball.

  10. Commit changes to spec and sources: git commit -asm "Update ....."

  11. Check your PR in CI, look at line "Fedora CI - scratch build" in your PR web page and go this link to see Koji build.

  12. After build in Koji succeeded and RPM update patch was merged, update the rdoinfo with a new package version. Submit a patch to rdoinfo, for example: https://review.rdoproject.org/r/c/rdoinfo/+/34314/1/buildsys-tags/cloud8s-openstack-xena-candidate.yml

How to create a new package

Sometimes we'll need to add a new collection or new dependency for existing collection. The process of adding another package is like following:

Add package to Fedora RPMs

  1. Create a spec for collection, usually it's customized copy of existing spec of any collection, for example of community.general.

  2. Run rpmbuild -ba /path/to/spec/file and check there are no errors and source RPM is built (usually in ~/rpmbuild/SRPMS/)

  3. Upload your SRPM and SPEC files onto the internet somewhere, for example in your Github in gist. Get a direct link to file (raw).

  4. Try to build it in Koji: koji build --scratch f33 /home/sshnaidm/rpmbuild/SRPMS/your_collection_SRPM_file.src.rpm Remember the file should be SRPM (source RPM). Watch the build and ensure it succeeds.

  5. Make sure you have a Bugzilla account at bugzilla.redhat.com. Fill out this form: https://bugzilla.redhat.com/bugzilla/enter_bug.cgi?product=Fedora&format=fedora-review

  6. After a bugzilla review request is approved, let's create a repo:

    fedpkg request-repo PACKAGE-NAME BUGZILLA-TICKET-NUMBER

    For example: fedpkg request-repo ansible-collection-ansible-utils 1979543

    If we need more than rawhide branch, then request for a branch: fedpkg request-branch --repo PACKAGE-NAME BRANCH

    For example: fedpkg request-branch --repo ansible-collection-ansible-utils f34

    The pull requests should be tracked in https://pagure.io

  7. When your "Issues" are approved on https://pagure.io run somewhere to clone the package: fedpkg clone PACKAGE-NAME for example: fedpkg clone ansible-collection-ansible-utils

  8. Make sure you're logged in with Fedora Kerberos: kinit username@FEDORAPROJECT.ORG

  9. Import the approved SRPM (from point 2): fedpkg import ~/rpmbuild/SRPMS/...src.rpm

  10. Commit sources and spec by git commit -m "Initial import (#nnnnnn)." (where nnnnnn is your Bugzilla package review bug number) - for example git commit -m "Initial import (#1979543)."

  11. Push it with fedpkg push or git push.

  12. Build it with fedpkg build.

  13. In case you have other branches:

    • switch to branch: fedpkg switch-branch BRANCH for example fedpkg switch-branch f34
    • Merge commit from main branch rawhide from point 12: git merge rawhide
    • Push fedpkg push
    • Build fedpkg build
    • In case you want the package be updated in released (non rawhide) branches run:
      • fedpkg update
      • In the commit message make sure: 
        ​​​​​​​​​​type=newpackage
​​​​​​​​​​bugs=1979543  # your BZ number
​​​​​​​​​​display_name=<your package name>
      • Track your package moving from testing to stable in web UI: https://bodhi.fedoraproject.org/updates/ or in your Dashboard

  14. Add package to RDO: create a patch to rdoinfo repository, which adds the package to deps.yml and candidate file of current branch (current master). For example cloud8s-openstack-xena-candidate.yml for Xena branch.

    Example of patch: https://review.rdoproject.org/r/c/rdoinfo/+/34445

  15. After it's built successfully for candidate add patch for rdoinfo to build it in testing, for example in branch xena it will be cloud8s-openstack-xena-testing file.

    Example of patch: https://review.rdoproject.org/r/c/rdoinfo/+/34513

  16. Check that package is built and present in repo, for Ansible collections it will be master deps repository, like: https://trunk.rdoproject.org/centos8-master/deps/latest/noarch/

  17. Close the Bugzilla ticket.

    You should close it with resolution NEXTRELEASE or RAWHIDE, depending on where you built the package. The resolution field will appear after you set the status field to CLOSED.

++++ Done!

Select a repo