Skip to content
Permalink
master
Go to file
12 contributors

Users who have contributed to this file

@jctanner @pilou- @mkrizek @dharmabumstead @dagwieers @samdoran @gundalow @techtonik @mattclay @kbreit @flowerysong @Akasurde
274 lines (207 sloc) 23 KB

Ansibullbot Help

Making progress in resolving issues for modules depends upon your interaction! Please be sure to respond to requests or additional information as needed.

If at any time you think this bot is misbehaving (not for test failures), please leave a comment containing the keyword bot_broken and an Ansible staff member will intervene.

Table of contents

Overview

The Ansibull Triage Bot serves many functions:

  • Responds quickly to issue and pull request submitters to thank them;
  • Identifies the maintainers responsible for reviewing pull requests for any files affected;
  • Tracks the current status of pull requests;
  • Pings responsible parties to remind them of any actions that they may be responsible for;
  • Provides maintainers with the ability to move pull requests through our workflow;
  • Identifies issues and pull requests abandoned by their authors so that we can close them;
  • Identifies modules abandoned by their maintainers so that we can find new maintainers;
  • Automatically labels issues and pull requests based on keywords or affected files.

For issue submitters

Please note that if you have a question about how to use this feature or module with Ansible, that's probably something you should ask on the ansible-project mailing list, rather than submitting a bug report. For more details, please see I’ve Got A Question.

If the feature/module maintainer or ansibullbot needs further information, please respond to the request, so that you can help the devs to help you!

The bot requires a minimal subset of information from the issue template:

  • issue type
  • component name
  • ansible version
  • summary

If any of those items are missing or empty, ansibullbot will keep the issue in a needs_info state until the data is provided in the issue's description. The bot is expecting an issue description styled after the default issue template, so please use that whenever possible.

Expect the bot to do a few things:

  1. Add common labels such as needs_triage, bug_report, feature_idea, etc.

    These labels are determined by templated data in the description. Please fill out the templates as accurately as possible so that the appropriate labels are used.

  2. Notify and assign the maintainer(s) of the relevant file(s) or module(s).

    Notifications will happen via a comment with the @NAME syntax. If you know of other interested parties, feel free to ping them in a comment or in your issue description.

If you are not sure who the issue is waiting on, please use the bot_status command.

For pull request submitters

Expect the bot to do a few things:

  1. All of the items described in the for issue submitters section.

  2. Add labels indicating the status of the pull request.

Please prefix your pull request's title with WIP if you are not yet finished making changes. This will tell the bot to ignore the needs_rebase and shipit workflows until you remove it from the title.

If you are finished committing to your pull request or have made changes due to a request, please use the ready_for_review command.

If you are not sure who the pull request is waiting on, please use the bot_status command.

When will your pull request be merged?

ℹ️ Approve pull request status is ignored, shipit command is used by maintainer to approve a pull request. The bot automatically adds a shipit label to the pull request when the required number of shipit commands has been reached.

The bot will label a pull request with shipit when at least two [shipit] commands are issued, the following rules describe how shipit commands are count:

  • shipit issued by a module maintainer or a maintainer of a module in the same namespace or a core team member are always taken in account
  • when the submitter is a module maintainer or a maintainer of a module in the same namespace or a core team member, their shipit is automatically counted
  • shipit issued by anyone else is taken in account when both conditions are met:
    • at least one module maintainer or a maintainer of a module in the same namespace or a core team member has approved the pull request with a shipit command
    • at least three people which aren't maintainer nor core team member have approved the pull request using the shipit

New Modules

Once the pull request labeled with shipit, the module will be merged once a member of the Ansible organization has reviewed it and decided to include it.

ℹ️ If you are a maintainer of a module in the same namespace, only one shipit is required.

Existing Modules

Module's have metadata with a supported_by field per the metadata proposal.

ℹ️ If you have changes to other files in the pull request, the supported_by property is ignored because the Ansible core team must approve those changes. When other changes are line deletions in ansible/test/*/*.txt files, the supported_by property isn't ignored.

ℹ️ if the pull request has more than one committer, then number of commits must be equal to number of authors and lower than 11.

The possible values of supported_by are:

core

Members of the Ansible Core Team typically do all the maintenance on this module, so only they can approve changes. Expect reviews to take longer than most other modules because of the volume the core team has on a daily basis.

certified

These modules are developed and maintained by the community, but the Ansible core team needs to approve changes. Once the pull request is labeled with shipit, the core team will be alerted to review.

community

These modules are also developed, maintained and supported by the community. If you are a module maintainer, a maintainer of a module in the same namespace, or a core team member use the shipit command to approve the pull request. The bot will wait for the pull request being labeled with shipit, then automerge.

ℹ️ If you are maintainer of the module or maintainer of a module in the same namespace, only one shipit is required.

network

Members of the Ansible Network Team typically do all the maintenance on this module, so only they can approve changes.

Non-module changes

The ansible core team approves these pull requests and it may take some time for them to get to your request.

For community maintainers

ℹ️ Approve pull request status is ignored, shipit command must be used in order to approve a pull request.

Thanks in advance for taking a look at issues and pull requests and for your ongoing maintenance. If you are unable to troubleshoot or review this issue/pull request with the information provided, please ping the submitter of the issue in a comment to let them know.

How to disable notifications

If you wish to stop receiving notifications from Ansibullbot to issues and pull requests you need to add your github name into the ignored key under plugin you are no longer insterested in in the BOTMETA.yml file and send a pull request against the ansible/ansible repository. See an example below:

...
$modules/cloud/amazon/:
  ignored: erydo seiffert simplesteph nadirollo tedder joshsouza defionscode
  maintainers: $team_aws
...

If the plugin was migrated to a collection you also need to add an ignore entry into BOTMETA.yml in the collection repository as well.

For anyone else

Reactions help us determine how many people are interested in a pull request or have run across a similar bug. Please leave a +1 reaction (👍) if that applies to you. Any additional details you can provide, such as your usecase, environment, steps to reproduce, or workarounds you have found, can help out with resolving issues or getting pull requests merged.

Commands

To streamline the maintenance process, we've added some commands to Ansibullbot that you can use to help direct the work flow. Using the automation is simply a matter of adding one of the following commands in your comments:

Command Scope Allowed Description
bot_broken issues pull requests anyone Use this command if you think the bot is misbehaving (not for test failures), and an Ansible staff member will investigate.
bot_skip issues pull requests staff Ansible staff members use this to have the bot skip triaging an issue.
bot_status pull requests submitters maintainers Use this command if you would like the bot to comment with some helpful metadata about the issue.
needs_info issues pull requests maintainers past committers Use this command if you need more information from the submitter. We will notify the submitter and apply the needs_info label.
!needs_info issues pull requests maintainers past committers If you do not need any more information and just need time to work the issue, leave a comment that contains the command !needs_info and the needs_info label will be replaced with waiting_on_maintainer.
needs_revision pull requests maintainers Use this command if you would like the submitter to make changes.
!needs_revision pull requests maintainers If you want to clear the needs_revision label, use this command.
needs_rebase pull requests maintainers Use this command if the submitters branch is out of date. The bot should automatically apply this label, so you may never need to use it.
!needs_rebase pull requests maintainers Clear the needs_rebase label.
notabug issues maintainers If you believe this is not a bug, please leave a comment stating notabug, along with any additional information as to why it is not, and we will close this issue.
bug_resolved issues maintainers If you believe this issue is resolved, please leave a comment stating bug_resolved, and we will close this issue.
resolved_by_pr issues maintainers If you believe this issue has been resolved by a pull request, please leave a comment stating resolved_by_pr followed by the pull request number.
wontfix issues maintainers If this is a bug that you can't or won't fix, please leave a comment including the word wontfix, along with an explanation for why it won't be fixed.
needs_contributor issues maintainers If this bug or feature request is something that you want implemented but do not have the time or expertise to do, comment with needs_contributor, and the issue will be put into a waiting_on_contributor state.
duplicate_of issues maintainers If this bug or feature request is a duplicate of another issue, comment with duplicate_of followed by the issue number that it duplicates, and the issue will be closed.
close_me issues maintainers If the issue can be closed for a reason you will specify in the comment, use this command.
ready_for_review pull requests submitters If you are finished making commits to your pull request or have made changes due to a request, please use this command to trigger a review from the maintainer(s).
shipit pull requests maintainers If you approve the code in this pull request, use this command to have it merged. Note that Github Approve pull request status is ignored. Nonetheless shipit in review summary of commented or approved review is taken in account. In place of shipit, +1 and LGTM can be used too. Note that these commands must not be surrounded by any character, spaces excepted.
+label issues pull requests staff maintainers Add a whitelisted label. See When to use label commands.
-label issues pull requests staff maintainers Remove a whitelisted label. See When to use label commands.
rebuild_merge pull requests staff Allow core team members to trigger CI, then the pull request is automatically merged if CI results are successful.
/rebuild pull requests anyone Allows anyone to re-trigger CI.
/rebuild_failed pull requests anyone Allows anyone to re-trigger CI only on failed jobs [this is usually much faster than /rebuild].
!component issues anyone Set, append or remove a file from the matched components. To set, use !component =lib/ansible/foo/bar. To add, use !component +lib/ansible/foo/bar. To remove, use !component -lib/ansible/foo/bar.
!waffling all maintainers Disable waffling detection on a label. To use !waffling <labelname> on a separate line in a comment.

Labels

The bot adds many labels on issues and pull requests.

Label Scope Prevent automerge Description
automerge pull requests no Identify pull requests automatically merged by the bot.
backport pull requests yes Added to pull requests which don't target devel branch.
bot_broken pull requests yes Allow to identify pull requests for which bot_broken had been used.
bug issues pull requests no Added to issues or pull requests reporting/fixing bugs.
c:name issues pull requests no Categorize issues or pull requests by their relevant source code files.
ci_verified pull requests yes Identify pull requests for which CI failed. A pull request must successfully pass CI in order to be merged.
committer_review pull requests no In order to be merged, these pull requests must follow the certified review workflow.
community_review pull requests no In order to be merged, these pull requests must follow the community review workflow.
core_review pull requests no In order to be merged, these pull requests must follow the core review workflow.
docs issues pull requests no Identify issues or pull requests related to documentation.
docsite_pr pull requests no Identify pull requests created through documentation's "Edit on GitHub" link
easyfix issue or pull requests no Identify easy entrance point for people who are looking to start contributing.
feature issues pull requests no Added to issues or pull requests requesting/adding new features.
filament pull requests no Identify pull requests related to Ansible Lightbulb project.
merge_commit pull requests no Added to pull requests containing at least one merge commit. Pull requests must not contain merge commit.
module pull requests no Identify pull requests updating existing modules.
needs_ci pull requests no Identify pull requests for which CI status is missing. When a pull request is closed and reopened or when new commits are updated, the CI is triggered again.
needs_collection_redirect issue or pull requests no Collection Migration Docs
needs_info issues yes Identify issues for which reviewer requested further information.
needs_maintainer pull requests no Ansibullbot is unable to identify authors or maintainers of the related module. Check author field format in DOCUMENTATION block.
needs_rebase pull requests yes Pull requests which are out of sync with ansible/ansible's devel branch. Please review the rebase guide for further information.
needs_revision pull requests yes Used for pull request which fail continuous integration tests or if a maintainer has requested a review/revision of the code. This label can be cleared by fixing any failed tests or by commenting ready_for_review.
needs_template issues pull requests no Label added when description is incomplete. See issue templates or pull request template.
needs_triage issues pull requests no This label will be added if your issue is being labeled for the first time. We (ansible staff and maintainers) use this label to find issues that need a human first touch. We'll remove it once we've given the issue a quick look for any labeling problems or missing data.
needs_verified issues no This label implies a maintainer needs to check if the issue can be reproduced in the latest version.
new_module pull requests yes Identify pull requests adding new module.
owner_pr pull requests no Identify pull requests made by module maintainers.
shipit pull requests no Identify pull requests for which the required number of shipit has been reached. For community reviewed pull requests, if automerge workflow applies, then pull request should be automatically merged. For all other cases, merge should be performed by a core team members. If your pull request gets no comment and becomes tagged with stale_review, you can add it to the IRC core team meeting agenda to receive more comments.
stale_ci pull requests yes Added when the last CI result is older than one week. When a pull request is closed and reopened, the CI is triggered again. In some case, the bot will automatically trigger the CI when a pull request is labeled with both shipit and stale_ci.
stale_review pull requests no Added when submitter made some updates after a reviewer requested some changes, if the submitter updates are older than seven days and the reviewer didn't update their review.
test pull requests no Identify pull requests related to tests.
waiting_on_contributor  issues pull requests no The feature or fix would be accepted, but there are no plans to actively work on it.
WIP pull requests yes Identify pull requests which are not ready (from the submitter point of view) to be merged.

Some labels are used to categorize issues and pull requests:

  • Pull requests related to test:

    • test
  • Namespace labels:

    • aci
    • avi
    • aws
    • azure
    • cloud
    • cloudstack
    • digital_ocean
    • docker
    • f5
    • gce
    • infoblox
    • jboss
    • meraki
    • netapp
    • networking
    • nxos
    • openstack
    • ovirt
    • ucs
    • vmware
    • windows
  • Module labels:

    • m:unarchive
    • m:xml

When to use label commands

The +label and -label commands are restricted to a subset of available labels and are not meant to replace the other bot commands:

  • affects_X.Y -- indicates that the issue is relevant to a particular ansible major.minor version.
  • c:... -- these labels categorize issues or pull requests by their relevant source code files.
  • easyfix -- indicates that the issue an easy entrance point for people who are looking to start contributing.
  • m:... -- these labels categorize issues or pull requests by their module name.
  • module -- classifies the issue as a module related issue.
  • needs_triage -- a human being still needs to validate the issue is properly labeled and has all the information required.
  • test and namespace labels

How to use label commands

To use the commands, please type the command and label on one line each in a comment. Example:

-label needs_triage
+label cloud
+label gce
You can’t perform that action at this time.