Skip to main content

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​

  1. 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

  2. Make Your Changes: Create your feature branch and make changes. Ensure your code passes all tests and linting checks.

  3. Commit Your Changes: Use a clear and descriptive commit message.

    git commit -m "Add feature: your feature description"

  4. Push to Your Fork: Push your changes to your fork on GitHub.

    git push origin your-feature-branch

  5. Create a Pull Request: Go to the pan-scm-cli repository and create a new pull request from your feature branch.

  6. 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 Docusaurus. Documentation pages live under docs-site/docs/ and the navigation is defined in docs-site/sidebars.ts.

Preview documentation changes locally:

make docs-serve
# or, directly:
cd docs-site && npm install && npm start
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:

  1. Follow existing patterns in the appropriate command module under src/scm_cli/commands/
  2. Use the error handling decorator — apply @handle_command_errors("operation description") after @app.command() instead of writing manual try/except blocks (see below)
  3. Add Pydantic validators in utils/validators.py if needed
  4. Register the command in main.py
  5. Add tests in tests/
  6. 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.