Skip to content
This repository has been archived by the owner on Jun 10, 2024. It is now read-only.

RelEng: ReleaseProcess

Jump to bottom
Toshio Kuratomi edited this page Apr 23, 2019 · 95 revisions

Table of Contents (Last Generated August 27, 2018)

Permissions and Accounts Required

Access to post to the following Google groups:

Access to post to the following Ansible Slack channels:

  • #core_internal (private channel)
  • #core_network
  • #ship_it
  • #testing

Access to post to the following Red Hat distribution lists:

  • ansible-releases (are there even any restrictions on this?)

Access to change the channel topic on freenode channels:

  • #ansible

Accounts on:

  • Twitter
  • freenode

Credentials for:

During the Development Stage

  • Add links to all of the items on the roadmap for the release.
    • This lets others see the status of each feature
    • Can link to proposal, PR, issue, project board depending on the feature

Alpha 1

  • Check in with developers whether features are merged
  • Remove features that are going to be punted from the roadmap for the release.

Starting a new release branch

  • Usually around beta 1

  • Create branch stable-X.Y from devel

    • git checkout -b stable-2.8

  • in new branch lib/ansible/release.py:

    • verify __codename__ is set to the selected codename for the release
    • __version__ should be right as it is updated by the release scripts. When we branch after alpha1, it should be 'X.Y.0a1.post0'. If we branch before alpha1 it should be 'X.Y.0.dev0'

  • in new branch docs/docsite/_themes/sphinx_rtd_theme/layout.html:

    • update DocSiteProduct-CurrentVersion to X.Y

  • After pushing the stable-X.Y branch, Ping a github admin (@mattclay, @jctanner, @jimi-c, @jmckerr) to protect the stable branches.

  • Open a PR against devel with the following changes:

    • lib/ansible/release.py:
      • set __version__ to X.$(Y+1).0.dev0 (If we're releasing 2.6, __version__ in devel should be '2.7.0.dev0'
      • set __codename__ to the selected codename for the next release
    • Delete everything under changelogs/fragments. This allows the next release to accumulate its changelog fragments without duplication, since the fragments are sorted into releases by tags that aren't applied to devel). Then create a stub changelog fragment for the new branch as changelogs/fragments/vX.Y+1.0-initial-commit.yaml with just an empty dict ({})
    • Delete any generated changelogs from any “in place” releases under changelogs/CHANGELOG-*.rst.
    • Delete changelogs/.changes.yaml which keeps state information for the changelog tool to know what releases a fragment was added for.
    • Create a new blank porting guide and move it into place: 
       hacking/porting_guide.py --version X.Y+1
 mv porting-guide-X.Y+1.rst docs/docsite/rst/porting_guides/porting_guide_X.Y+1.rst
 git add docs/docsite/rst/porting_guides/porting_guide_X.Y+1.rst
    • The PR bumping version in devel will also cause some of our checks to fail. You'll need to create a PR to fix those as well:
      • Error E103 (example: lib/ansible/modules/cloud/amazon/_ec2_ami_find.py:0:0: E103 Did not find a call to removed_module()) means that the module needs to be replaced with a removed_module() stub (so ansible-doc and documentation can say the module has been removed).
        • Change the status in ANSIBLE_METADATA to removed.
        • Replace the remaining code with: 
              from ansible.module_utils.common.removed import removed_module


    if __name__ == '__main__':
        removed_module(removed_in='2.9')
        • Removed modules also need to be skipped for ansible-doc tests. Add them to test/sanity/ansible-doc/skip.txt
        • Add the removed modules to the porting-guide-X.Y.rst that you created above (Modules removed section)
        • You may also have to touch up previous porting guides which linked to the removed modules. The docs no longer exist so they can no longer be links
      • Error E322 (example: test/sanity/validate-modules/ignore.txt:1:1: A102 Remove since "lib/ansible/modules/cloud/amazon/_ec2_ami_find.py" passes "E322" test). If this refers to a module which is being turned into a removed_module() stub, simply remove it from the specified ignore.txt as it no longer has meaning.

  • in Launchpad under the "ansible" account Click "Create a new PPA" and add one for 'ansible-X.Y' (Consult your secret credentials for account credentials)

  • Alert @qe in #testing that the stable-X.Y branch needs to be added to jenkins for tower testing.

    • There is also a point person for tower<=>ansible core integration per release. These are listed in #testing's topic.

  • Fix changelog path in porting guide like this 2.7 example

  • Update the Jenkins Nightly RPM job to include the new stable branch.

Reporting Recurring Cleanups

This procedure is to discover cleanups that need to be performed every release and get them assigned to Core Team members for fixing every release. Currently reported cleanups are:

  • deprecated features in code
  • deprecated features in config
  • bundled libraries that need updating

Steps:

  • Remove ansible-deprecated-version from test/sanity/pylint/config/default
  • Remove deprecated-config.py from test/sanity/code-smell/skip.txt
  • Remove update-bundled.py from test/sanity/code-smell/skip.txt
  • Submit a pull request with this change
  • Once CI has completed, if there are any cleanups to be performed, CI should fail and give a list of those failures. You can wait for the bot to comment providing this list.
  • Create issues for all scheduled code deprecations. This can be done using the hacking/create_deprecated_issues.py script (This script does not work for deprecated-config currently).
    • Create a file with the ansible-deprecated-version issues discovered by pylint in the pylint standard output.
    • Execute python hacking/create_deprecated_issues.py deprecated.txt
      • If you want to automatically add these issues to a project for the next release, you will need to edit hacking/create_deprecated_issues.py to indicate the IDs of the project and column.
  • Create issues for deprecated-config
  • Create issues for update-bundled

Protecting the stable branches

Note: This is a github admin job.

After pushing the stable-X.Y branch add branch protections in GitHub to match the existing stable-* branches. The protections are:

  • Protect this branch - Disables force-pushes to this branch and prevents it from being deleted.
  • Include administrators - Enforce all configured restrictions for administrators.
  • There's a github group that needs to be given access to all branches @mattclay to fill out what this is.

Ongoing lead up to release

  • Review and merge backport PRs against the stable-X.Y branch
  • If this is an rc-less release (minor releases as opposed to major releases), stop merging backport PRs several days before release (Monday is good last merge day for a release on a Thursday), so that Tower has a chance to test.
  • Ping the tower liaison in the #testing slack channel once you're done merging so they can be sure to test before the next rc/final release.

Release procedure

Release pre-check

Make release (2.5)

  • from stable-X.Y (devel for alpha release) checkout root: checkout stable-X.Y from ansible/ansible remote
  • edit lib/ansible/release.py to current version
    • Alpha releases: X.Y.0a1
    • Beta releases: X.Y.0b1
    • Release candidates: X.Y.0rc1
    • Final: X.Y.0
  • changelogs
    • create changelogs/fragments/vX.Y.Z_catchup.yaml, scan commits for missing changelog entries, add them (only needed for stable-2.5 for reno)
    • create changelogs/fragments/vX.Y.Z(pre-release identifier)_summary.yaml, include porting guide, release date, any other notes. Sample release summary:
release_summary: |
   | Release Date: 2018-05-17
   | `Porting Guide <https://docs.ansible.com/ansible/devel/porting_guides.html>`__
  • If you ever have to rename a changelog fragment, be sure that you also modify it in changelogs/.changes.yaml

Changelogs for 2.5

# stage all release changes:
git commit -m "temp release vX.Y.Z commit"
git tag vX.Y.Z
make changelog_reno
# Tweak any changelog fragments causing formatting/parsing issues in the RST, amend release commit if necessary. Make sure to delete and recreate the tag after making changes and then run reno again.
# validate changelogs/CHANGELOG-vX.Y.rst in Github ("create new file", call it "bla.rst", paste in rst, sanity-check in preview)
git tag -d vX.Y.Z
git add changelogs/CHANGELOG-vX.Y.rst
git commit --amend -m "New release vX.Y.Z"
push release to stable-X.Y

Make release (2.6+)

  • From stable-X.Y (devel for alpha release) checkout root: 
    checkout stable-X.Y from ansible/ansible remote
  • Make sure you’re using the checked out version of ansible: 
    source hacking/env-setup
  • Change to the release directory 
    cd packaging/release
  • Make the release: 
    make release version={version}
    Where the version is:
    • Alpha releases: X.Y.0a1
    • Beta releases: X.Y.0b1
    • Release candidates: X.Y.0rc1
    • Final: X.Y.0
  • Push the release if you are satisfied with the changes from the previous step: 
    git push

Builds

  • Wait for the Shippable build of the stable branch to pass before continuing: https://app.shippable.com/github/ansible/ansible/dashboard

  • Run Ansible Release Jenkins job

    • Jenkins: Ansible Release
      • GIT_SHA == release SHA
      • PUBLISH release (or preview if it’s a preview)
      • MAJOR_MINOR X.Y portion of the release
      • LATEST checked if X.Y is the current major release, else not
    • Hit Build

  • If X.Y is current major release:

    • Do not do this for pre-releases!!
    • Once DEB build has finished, visit https://launchpad.net/~ansible/+archive/ubuntu/ansible-X.Y/+packages (logged in as [email protected]), poll for completed build status
    • Once all Launchpad package builds have green checkboxes (can take anywhere from 15m to several hours), click "Copy packages" in upper right corner, select current X.Y.Z packages, select Destination PPA as ansible, Destination series as "The same series", Copy options as "Copy existing binaries", then hit "Copy Packages"

NOTE: You don’t need to wait for the docs to be published unless they will be referenced in the release announcements and are new or have changed since the last release. For a new X.Y.0 release you will likely want to wait, but probably not for a X.Y.1+ release.

Publish release (2.5)

  • Once packaged releases are verified working 
    git tag -a vX.Y.Z -m "New release vX.Y.Z"
git push --tags
  • Once released switch the version back so we can differentiate a dev release from a normal release: 
    in stable-X.Y lib/ansible/release.py:
set __version__ to 'X.Y.Z.post0' (stable release)
set __version__ to 'X.Y.Z[a/b/rc]N.post0' (a/b/rc release)

Publish release (2.6+)

  • Once packaged releases are verified working, publish (tag) the release: 
    make publish
  • Push the release if you are satisfied with the changes from the previous step: 
    git push --follow-tags

Job cleanup

  • If this is a new major release (X.Y.0) remove the now unsupported stable branch from the Jenkins Nightly RPM job.
  • Alert tower @qe in #testing that the branch is EOL and doesn't need to be tested anymore.

Notifications

Ad hoc note: Toshio, for 2.8.0rc1, remember to include an apology for including gce deprecations after beta1: https://github.com/ansible/ansible/pull/55534/files

Google Groups (mailing lists)

Internal email

  • Beta and beyond: [email protected]
    • You can use the template from above and add a line to say that this is an upstream/community release.

Twitter

  • RC and beyond (mention @ansible for marketing ReTweet)
  • Final + servicing: Use the script in hacking/release-announcement.py

NOTE: Copying a tweet such as the one above from the Twitter UI may result in additional space(s) being added after the URL.

Freenode

Ansible Slack

  • All: #core_internal
  • Beta and beyond: #core_network
  • rc and beyond: @kaete in #marketing Include the link to the tweet
  • Final + servicing: #ship_it

Notification Sample Content

Short form (Twitter, IRC, etc)

@ansible 2.5.3 has been released! Get it on PyPI: pip install ansible==2.5.3, https://releases.ansible.com/ansible/, the Ansible PPA on Launchpad, or GitHub. Happy automating!

Long form (email, ML, Google Groups, etc)

Hi all- we're happy to announce that the general release of Ansible 2.7.7 and Ansible 2.6.13 are now available! 


How do you get it?
------------------

$ pip install ansible==2.6.13 --user
or
$ pip install ansible==2.7.7 --user

The tar.gz of the release can be found here:

* 2.7.7
  https://releases.ansible.com/ansible/ansible-2.7.7.tar.gz
  SHA256: 
* 2.6.13
  https://releases.ansible.com/ansible/ansible-2.6.13.tar.gz
  SHA256: 

What's new in 2.7.7 and 2.6.13?
-------------------------------

These releases are maintenance releases containing numerous bugfixes. The full changelog is at:

* 2.7.7
   https://github.com/ansible/ansible/blob/stable-2.7/changelogs/CHANGELOG-v2.7.rst
* 2.6.13
  https://github.com/ansible/ansible/blob/stable-2.6/changelogs/CHANGELOG-v2.6.rst


What's the schedule for future maintenance releases?
----------------------------------------------------

Future maintenance releases will occur approximately every 3 weeks.  So expect the next one around February 28th.


We've published a porting guide at https://docs.ansible.com/ansible/devel/porting_guides/porting_guide_2.7.html to help migrate your content to 2.7. If you discover any errors, or if you see any regressions from playbooks which work on 2.7.6 and prior, please open a GitHub issue, and be sure to mention you're using 2.7.7.

Thanks!

-Toshio Kuratomi

This Wiki is used for quick notes, not for support or documentation.

(ARchived) Working groups

Working groups are now in the Ansible forum

Ansible project:
Community, Contributor Experience, Docs, News, Outreach, RelEng, Testing

Cloud:
AWS, Azure, CloudStack, Container, DigitalOcean, Docker, hcloud, Kubernetes, Linode, OpenStack, oVirt, Virt, VMware

Networking:
ACI, AVI, F5, Meraki, Network, NXOS

Ansible Developer Tools:
Ansible-developer-tools

Software:
Crypto, Foreman, GDrive, GitLab, Grafana, IPA, JBoss, MongoDB, MySQL, PostgreSQL, RabbitMQ, Zabbix

System:
AIX, BSD, HP-UX, macOS, Remote Management, Solaris, Windows

Security:
Security-Automation, Lockdown

Tooling:
AWX, Galaxy, Molecule

Communities

Modules:
unarchive, xml

Plugins:
httpapi

Wiki

Roles, Communication, Reviewing, Checklist, TODO

Clone this wiki locally