# 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*

[TOC]

## Ansible Podman collection release process

Resources:
* https://github.com/containers/ansible-podman-collections
* https://src.fedoraproject.org/rpms/ansible-collection-containers-podman
* [Fedora's Package Update Guide](https://docs.fedoraproject.org/en-US/package-maintainers/Package_Update_Guide/)
* [Koji page for `ansible-collection-containers-podman`](https://koji.fedoraproject.org/koji/packageinfo?packageID=33610)
* [Bodhi's page `Create New Update`](https://bodhi.fedoraproject.org/updates/new)

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](
https://src.fedoraproject.org/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`](
https://src.fedoraproject.org/rpms/ansible-collection-containers-podman/c/6dc5eb79a3aa082e062768993bed66675ff9d520?branch=rawhide):

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

and add changelog, sort of:

      +* Tue Jun 08 2021 Sagi Shnaidman <[e-mail]> - <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:
+ `fedpkg push`
+ `fedpkg build`
+ check [Koji's page for `ansible-collection-containers-podman`](
https://koji.fedoraproject.org/koji/packageinfo?packageID=33610) (optional)

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

+ `fedpkg switch-branch f36`
+ `git merge rawhide`
+ `fedpkg push`
+ `fedpkg build`
+ `fedpkg update` or use [Bodhi's page `Create New Update`](https://bodhi.fedoraproject.org/updates/new)

- Repeat previous steps for branch `epel9`.

5. Promote built RPM to RDO:
- Update `rdoinfo` repository to build package `ansible-collection-containers-podman` in RDO
for CentOS 8 and CentOS 9:
+ For CentOS8, edit `buildsys-tags/cloud8s-openstack-<openstack-current-branch>-candidate.yml`
and send patch to review. For example if current branch is Xena, then it is
`buildsys-tags/cloud8s-openstack-xena-candidate.yml`.

If package is there, just change version to latest, if not, add it as:

            - project: ansible-collection-containers-podman
              buildsys-tags:
                cloud8s-openstack-xena-candidate: ansible-collection-containers-podman-<version-tag>-1.el8

Example: https://review.rdoproject.org/r/c/rdoinfo/+/43850
+ For CentOS9, edit `SPECS/ansible-collection-containers-podman.spec` in repo
[`deps/ansible-collection-containers-podman`](
https://review.rdoproject.org/r/q/project:deps%252Fansible-collection-containers-podman) as described in
[Requirements management in RDO](https://www.rdoproject.org/documentation/requirements/).

Example: https://review.rdoproject.org/r/c/deps/ansible-collection-containers-podman/+/43849
- Update `rdoinfo` repository to import updated packages of `ansible-collection-containers-podman` into RDO
branches. Bump version of `ansible-collection-containers-podman` in all
`buildsys-tags/*-openstack-*-testing.yml` relevant files and send patch to review.

**NOTE:** Send separate patches for each RDO release because several jobs will run for each RDO release
which have to pass for a patch to pass Zuul CI gates. RDO folks apparently does not want to recheck all
if there is a single failing job hence submit one patch per file.

Examples:
+ [`buildsys-tags/cloud8s-openstack-wallaby-testing.yml`](https://review.rdoproject.org/r/c/rdoinfo/+/43852)
+ [`buildsys-tags/cloud8s-openstack-xena-testing.yml`](https://review.rdoproject.org/r/c/rdoinfo/+/43853)
+ [`buildsys-tags/cloud8s-openstack-yoga-testing.yml`](https://review.rdoproject.org/r/c/rdoinfo/+/43858)
+ [`buildsys-tags/cloud9s-openstack-wallaby-testing.yml`](https://review.rdoproject.org/r/c/rdoinfo/+/43856)
+ [`buildsys-tags/cloud9s-openstack-xena-testing.yml`](https://review.rdoproject.org/r/c/rdoinfo/+/43861)
+ [`buildsys-tags/cloud9s-openstack-yoga-testing.yml`](https://review.rdoproject.org/r/c/rdoinfo/+/43855)
+ [`buildsys-tags/cloud9s-openstack-zed-testing.yml`](https://review.rdoproject.org/r/c/rdoinfo/+/43854)

## Ansible OpenStack collection release process

Content has been migrated to [`docs/releasing.md` in Ansible OpenStack collection](
https://opendev.org/openstack/ansible-collections-openstack/src/branch/master/docs/releasing.md).

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

1. Submit PR to collection in its repo
* https://github.com/ansible-collections/community.general
* https://github.com/ansible-collections/ansible.posix
* https://github.com/ansible-collections/ansible.netcommon

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:
* [ansible-collection-ansible-netcommon.spec](https://src.fedoraproject.org/rpms/ansible-collection-ansible-netcommon/blob/rawhide/f/ansible-collection-ansible-netcommon.spec)
* [ansible-collection-ansible-posix.spec](https://src.fedoraproject.org/rpms/ansible-collection-ansible-posix/blob/rawhide/f/ansible-collection-ansible-posix.spec)
* [ansible-collection-community-general.spec](https://src.fedoraproject.org/rpms/ansible-collection-community-general/blob/rawhide/f/ansible-collection-community-general.spec)

5. Fork the RPM specs repo, for example press button `Fork` in the page os [netcommon](https://src.fedoraproject.org/rpms/ansible-collection-ansible-netcommon) repo to fork it to your space.
6. Clone it to your machine with `SSH://` transport. For example: `git clone ssh://[e-mail]/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
* *docs to read: [New package process for existing contributors](https://fedoraproject.org/wiki/Newpackageprocessforexistingcontributors)*

1. Create a spec for collection, usually it's customized copy of existing spec of any collection, for example of [community.general](https://src.fedoraproject.org/rpms/ansible-collection-community-general/blob/rawhide/f/ansible-collection-community-general.spec).
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`).
* For example, [patch to add SRPM and spec file](https://github.com/sshnaidm/ansible.utils/commit/2cfd6392c51192bf74e26635608b40525a14a3ca).
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

* Make sure you put the name of the package in the Review Summary field, along with a very brief summary of what it is
* Make sure that you put the URL paths for the SPEC file and the SRPM file in the Review Description
* Put a description of your package (usually, this can be the same thing as what you put in the spec %description) in Review Description
* The review process is described in detail here: [Package Review Guidelines](https://fedoraproject.org/wiki/Packaging:ReviewGuidelines)
* Examples: [Review Request: ansible-collections-openstack - Openstack Ansible collections for managing Openstack cloud](https://bugzilla.redhat.com/show_bug.cgi?id=1946258)
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 [e-mail]`
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](https://bodhi.fedoraproject.org/)
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

17. 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/

18. 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!