Contributing to Ansible

docs.ansible.com/ansible/devel/community

Who am I?

  - name: John Barker
    aliases: gundalow
    title: Principal Software Engineer
    org: Ansible, by Red Hat
    start_date: 2016
    roles:
      - community
      - core
    freenode: gundalow
    github: gundalow
    twitter: the_gundalow
    email: gundalow@redhat.com

THE ANSIBLE COMMUNITY

The humans who get involved, even once, make us stronger

We will cover:

  1. Scale and skill set - what you can bring
  2. Opportunities to help
  3. Issue & PR workflow
  4. How to review PRs
  5. How to join the conversation and shape the future

docs.ansible.com/ansible/devel/community

Myth #1: I can’t contribute because I’m not a programmer.

  • Can’t code (in Python)? No problem!
  • Module docs are YAML - You know YAML
  • Testing changes doesn't (necessarily) require you to understand how it works
  • Bug reports & confirm fixes

Myth #2: I'm brand new to Ansible, I can't contribute

  • Think you have no knowledge to share? Think again!
  • New users can tell us how well the documentation is working
  • Provide feedback test, review, report bugs
  • If you’re new to Ansible, you have fresh eyes - keep us honest

Myth #3: I don't know Git or GitHub

  • Scared of source control? Fear not!
  • docs.ansible.com - "Edit on GitHub"
  • You can directly from GitHub.com - demo later
  • Worst case you make a mess of your PR - Ansibullbot will guide you

Myth #4: Writing tests is difficult

  • Integration tests are just Playbooks
  • Extending a test case is generally fairly straight forward
  • Gives us confidence to merge PRs
  • Help us stop regressions

Myth #5: I need to make a commitment to stay around and support what I've done

  • Drive-by contributions are welcome
    • Clarifies documentation
    • Fixes a bug
    • Add a test case.
  • When adding new modules we look for some ongoing support

Myths: Proof

Scaling: The power of Community

  • The philosophical perspective, collectively we know everything
  • Some of us know lots of things
  • Some of us know very little
  • Collectively we know everything
  • Allows you to set direction

Scaling: The power of Community

Community is the force multiplier.

You are the community.

Scaling: Core Teams remit

  • The Ansible Core Team focus on the Engine and main modules
  • Core: 300 modules
  • Community: 2000 modules
  • Reviewing Community issues & PRs are the communities responsibility

Pause for questions

GitHub Issues and PRs

GitHub Issues and PRs

  • GitHub Issues/PRs or it never happened
  • Issues
    • Bug reports and feature ideas - Details
    • Discussion before implementation starts
  • Pull Requests (PRs)
    • Improve a one thing: Fix a bug/feature
    • Always use feature branches
  • If you know the fix, just create a PR
  • HELP: lab.github.com, guides.github.com

Ansible's Development Process

  1. Triage
  2. Cycle: Fix tests, get reviews, address review comments
  3. Merged
  4. Backport bug fixes [optional]

Development Process: PR Life Cycle Demo

Pause for questions

Who am I?

  - name: Alicia Cozine
    title: Lead Technical Writer
    org: Ansible, by Red Hat
    start_date: 2018
    roles:
      - docs
      - core
      - community
    freenode: acozine
    github: acozine
    email: acozine@redhat.com

Documentation Demo

docs.ansible.com/ansible/devel/community/documentation_contributions.html

github.com/ansible/community/wiki/Docs Docs Working Group

Pause for questions

Development Process: Finding Issues & PRs

Development Process: Aims of reviews

  • We need confidence before code can be merged
  • We need user feedback to tell us if this is right
  • PR Backlog size due to lack of review - WG & Big PR Review Day 2019-02-21
  • Anyone can help with this

Development Process: Types of review

Whatever your skill set, you can help with at least one of these:

  1. Functional review
  2. Documentation reviews
  3. Code reviews

Reviews #1: Functional Reviews

  • Does it work?
  • Address a use case you have?
  • Does it break any edge/use case you have?
  • Is the interface clear

Reviews #2: Documentation Reviews

  • Are the docs clear, is there any ambiguity?
  • Do the examples work?
  • Is there any missing knowledge?
  • Feedback from newer user is really important

Reviews #3: Code Reviews

  • Best use of existing APIs
  • Following the "the Ansible way" (variable names, etc.)
  • Honor Ansible's coding guidelines?
  • Follow the CRUD principles (Create, Read, Update, Delete)?

Development Process: How to review

  • Three part review:
    1. Is the idea behind the contribution sound?
    2. Is the contribution architected correctly?
    3. Is the contribution polished?
  • Be mindful:
    • Go above and beyond to promote a collaborative and respectful community
    • "Would this be clearer if..." - invites discussion
    • Avoid bikeshedding. Ansible's coding guidelines is enforced by CI.

Working Groups: List

  • General: Community, Core, Documentation, Testing
  • Cloud Providers and VMs: AWS, Azure, Docker, Linode, VMware
  • Network
  • Operating Systems: AIX, BSD, HP-UX, Linux, Solaris, Windows
  • Related projects: ansible-lint, AWX (Tower), Galaxy, Molecule
  • Plus many more...
  • Full list: github.com/ansible/community/wiki

Working Groups: Purpose

Are you willing to help advance the thing that is obviously stuck and needs people united in order to get unstuck

  • Focused effort on a specific topic
  • Help build communities
  • Allows people closer to the technology to set direction
  • Make Ansible do what you want, solve your challenges
  • Empowers

Working Groups: How?

  • Mix of skill sets required
  • Maybe spread across the globe
  • Communicate via GitHub Issues/PRs/Wiki
  • May have a dedicated IRC channel
  • May have IRC Meetings (recorded)
  • No regular commitment required
  • I can help you set this up

Recap

Thank You!