Skip to content

Contributing to the Strata Cloud Manager Ansible Collection

Thank you for your interest in contributing to the Palo Alto Networks Strata Cloud Manager Ansible Collection. This guide provides information on how to contribute to this project effectively.

Getting Started

Setting Up Your Development Environment

  1. Fork and Clone the Repository:
git clone https://github.com/YOUR-USERNAME/pan-scm-ansible.git
cd pan-scm-ansible
  1. Install Development Dependencies:
poetry install
poetry run pre-commit install
  1. Create a Branch:
git checkout -b feature/your-feature-name

Development Workflow

Building and Testing

We provide a comprehensive Makefile with various commands to help you develop, test, and validate your contributions:

# Install dependencies
make setup

# Run linting
make lint

# Format code
make format

# Run tests
make test

# Build documentation
make docs

Code Style and Guidelines

The codebase follows these conventions:

  • Python: Follow PEP 8 guidelines with a maximum line length of 100 characters
  • Imports: Sort using isort with black profile
  • Formatting: Use double quotes for strings and 4 spaces for indentation
  • Documentation: Include docstrings with Args and Returns sections for functions
  • Error Handling: Use try/except blocks with specific exceptions

Creating New Modules

When adding a new module:

  1. Create Module File:

  2. Create a new file in pan_scm_ansible/plugins/modules/

  3. Follow the structure of existing modules

  4. Documentation:

  5. Add DOCUMENTATION, EXAMPLES, and RETURN variables

  6. Create a corresponding Markdown file in docs/collection/modules/

  7. Tests:

  8. Create test playbooks in the tests/ directory

Pull Request Process

  1. Ensure Code Quality:

  2. Run make lint-format to ensure your code passes all linting checks

  3. Run make test to validate functionality

  4. Update Documentation:

  5. Ensure module documentation is complete

  6. Update README.md if necessary

  7. If adding new features, update relevant docs

  8. Submit Pull Request:

  9. Create a PR against the main branch

  10. Follow the PR template

  11. Provide a clear description of your changes

  12. Code Review:

  13. Respond to reviewer feedback

  14. Make requested changes and push updates

Commit Guidelines

We follow the Conventional Commits standard:

  • feat: for new features
  • fix: for bug fixes
  • docs: for documentation changes
  • test: for test additions or modifications
  • refactor: for code refactoring
  • chore: for routine tasks, maintenance, etc.

Example:

feat: add support for address groups

Implement address_group module for managing static and dynamic address groups
in Strata Cloud Manager. Add corresponding documentation and tests.

Reporting Issues

If you find a bug or have a feature request:

  1. Check if the issue already exists in the GitHub Issues
  2. If not, create a new issue with:
  3. Clear description
  4. Steps to reproduce (for bugs)
  5. Expected behavior
  6. Actual behavior
  7. Version information

Development Best Practices

  1. Keep Changes Focused:

  2. Each PR should address a single concern

  3. Avoid combining unrelated changes

  4. Test Coverage:

  5. Write tests for new functionality

  6. Ensure existing tests pass

  7. Documentation:

  8. Update documentation to reflect changes

  9. Include examples for new features

  10. Backward Compatibility:

  11. Maintain backward compatibility when possible

  12. Document breaking changes clearly

Thank you for contributing to the Strata Cloud Manager Ansible Collection!