Contributing¶

Contributions to pan-scm-cli are welcome and appreciated. Whether you are fixing a bug, adding a feature, improving documentation, or providing suggestions, every contribution is valuable.

Getting Started¶

Before you begin, make sure you have a GitHub account and are familiar with Git and GitHub workflows. If you are new to these tools, check out GitHub's Help pages.

Setting Up Your Environment¶

Fork and Clone¶

$ git clone https://github.com/YOUR_USERNAME/pan-scm-cli.git
$ cd pan-scm-cli

Install Dependencies¶

The project uses Poetry for dependency management:

poetry install

Create a Branch¶

Create a branch for your changes:

git checkout -b your-feature-branch

Contributing Guidelines¶

Code Style¶

The project follows PEP 8 standards for Python code. Refer to the style guides in the .claude/ directory for project-specific conventions:

.claude/STYLE_GUIDE.md for command modules and general standards
.claude/SDK_CLIENT_STYLE_GUIDE.md for SDK client patterns
.claude/VALIDATORS_STYLE_GUIDE.md for validator patterns

Pull Request Process¶

Update Your Fork: Sync your fork with the upstream repository before making changes.

git remote add upstream https://github.com/cdot65/pan-scm-cli.git
git fetch upstream
git checkout main
git merge upstream/main

Make Your Changes: Create your feature branch and make changes. Ensure your code passes all tests and linting checks.
Commit Your Changes: Use a clear and descriptive commit message.
```
git commit -m "Add feature: your feature description"
```
Push to Your Fork: Push your changes to your fork on GitHub.
```
git push origin your-feature-branch
```
Create a Pull Request: Go to the pan-scm-cli repository and create a new pull request from your feature branch.
Address Review Feedback: Respond to any feedback and make necessary changes.

Running Tests¶

The project uses pytest for testing:

poetry run pytest

Run a specific test:

poetry run pytest tests/test_specific.py::test_name

Running Quality Checks¶

Run all quality checks before submitting a pull request:

make quality

This runs linting, formatting, type checking, and tests.

Documentation¶

If you are adding or modifying functionality, update the documentation to reflect the changes. The project uses MkDocs with the Material theme.

Preview documentation changes locally:

poetry run mkdocs serve

Tip

Follow the documentation style guide in .claude/skills/docs-style/SKILL.md when writing or modifying documentation pages.

Adding New Commands¶

When adding new CLI commands:

Follow existing patterns in the appropriate command module under src/scm_cli/commands/
Use the error handling decorator — apply @handle_command_errors("operation description") after @app.command() instead of writing manual try/except blocks (see below)
Add Pydantic validators in utils/validators.py if needed
Register the command in main.py
Add tests in tests/
Document the command with examples in docs/cli/

Error Handling¶

All command functions use the @handle_command_errors decorator from utils/decorators.py for consistent error handling. The decorator catches exceptions, prints a formatted error message to stderr, and exits with code 1.

from ..utils.decorators import handle_command_errors

@set_app.command("my-resource")
@handle_command_errors("creating my resource")
def set_my_resource(
    folder: str = FOLDER_OPTION,
    name: str = NAME_OPTION,
):
    """Create or update a resource."""
    # No try/except needed — the decorator handles it
    result = scm_client.create_my_resource(folder=folder, name=name)
    typer.echo(f"Created resource: {result['name']}")

The operation string should be a lowercase present participle describing the action (e.g., "deleting address", "loading zones", "backing up security rules"). Error output follows the format: Error <operation>: <details>.

Note

Inner try/except blocks (e.g., per-item error handling inside bulk load loops) should still be written manually — the decorator only replaces the outermost error handler.

Bug Reports and Feature Requests¶

If you find a bug or have a feature request, create an issue on the GitHub repository using the provided templates.

Code of Conduct¶

This project adheres to a Code of Conduct. By participating, you are expected to uphold this code.