Cloud Docs Home > F5 Ansible Index

About upstreaming

Upstreaming refers to opening a PR with the Ansible core product.

F5’s goal with this repository is to serve as an incubator for modules to mature. Eventually, the modules here should find their way to the upstream Ansible product (core or extras).

Incubating modules

Modules in incubation follow the same naming convention as those you would find in the Ansible product. Incubation modules are easy to distinguish, because their filenames do not include a leading underscore.

You can obtain incubation modules only by using the installation steps outlined here: Install unstable F5 Modules.

An incubating module may or may not work at any point in time.

Note

Just because a module is incubation does not mean that it is unstable. Many modules remain in the incubator because the community has not expressed enough interest in them.

A module in incubation should have an associated Issue in Github so that everyone can track its progress and so that others do not repeat work.

Qualifications for upstreaming

A module is in a mature state after it has met all of the established standards.

When the module meets these requirements, F5 will request Ansible to include the module.

Ansible releases

After F5 upstreams a module, a period of time will pass before it becomes part of the core Ansible product.

That release schedule is in the ROADMAP files near the top of each file.

Depending on which version is currently stable, upstreamed modules will be part of the next major stable release.

For example, if 2.3 is the current stable version and F5 upstreamed a module to core, the module would not appear as part of pip install ansible until version 2.4 releases.

You can get the modules before that point in time, but you must do so manually. The link to the stable modules is here.

How to upstream a module

A summary of the upstreaming process is below. Only one person needs to upstreaming things.

Complete GitHub template

Ansible provides an Issue template that you receive when you create a new PR in GitHub. You should fill out the various fields, making sure to include the following information in one of the “Summary”, “Description”, or related fields.

Here is an example:

PR Title:
Adds the bigip_user module to Ansible

Summary:
This patch adds the bigip_user module to Ansible to support managing
users on an F5 BIG-IP.

Additional Info:
Unit tests provided. Integration tests are here:

* https://github.com/F5Networks/f5-ansible/blob/devel/test/integration/bigip_user.yaml
* https://github.com/F5Networks/f5-ansible/tree/devel/test/integration/targets/bigip_user/tasks

When you include this extra information, it shows your due diligence in writing and testing the module. It helps assure the Ansible maintainers, and F5 customers, that you wrote the code has well.

Attend the upstream meeting

Generally speaking the upstreaming window is open each week, around the times of the Networking meeting. Here is the Networking team’s schedule.

During that time, you must comment on the Ansible Networking Group’s issue tracker for new PRs, which is here:

The Networking team will address your PRs at their weekly meeting, which Ansible expects you to attend.

The meeting is on IRC at the below location:

  • Server: irc.freenode.net
  • Channel: #ansible-devel