Skip to content

Contributing

Jump to bottom
Michael Richardson edited this page May 10, 2021 · 2 revisions

Thank you for taking the time to contribute to this repository!

If you need basic guidance on how to use GitHub (or even a refresher), GitHub makes some nice guides available:

Understanding these concepts will be important when contributing to this project:

Setting up your environment

Requirements

  • Python 3.6.8 (recommended to install using pyenv)
  • pipenv

Setup

$ cd ~/src

This collection assumes it is in the directory structure ansible_collections/paloaltonetworks/panos, so create that directory, and check out your fork of the repository:

$ mkdir -p ansible_collections/paloaltonetworks
$ cd ansible_collections/paloaltonetworks
$ git checkout git@github.com:<your username>/pan-os-ansible.git panos

Ansible looks for collections in ~/.ansible/collections/ansible_collections by default. Symlink the your local checkout directory in here, making it available at paloaltonetworks.panos:

$ mkdir -p ~/.ansible/collections/ansible_collections/paloaltonetworks
$ cd ~/.ansible/collections/ansible_collections/paloaltonetworks
$ ln -s ~/src/ansible_collections/paloaltonetworks/panos panos

Alternatively, adding a custom directory to the collections path can be done using the Ansible COLLECTIONS_PATHS config setting, either by setting collection_path in the [defaults] section of your ansible.cfg file, or by the ANSIBLE_COLLECTION_PATH environment variable.

This project uses pipenv to manage virtual environments and track dependencies. You can use it to create a virtual environment for you, and install all required libraries for development:

$ cd ~/src/ansible_collections/paloaltonetworks/panos
$ pipenv install --dev

To keep your fork up to date, set up a remote tracking branch to track changes made to the upstream project. Now you can fetch any changes, and merge them into your develop branch:

$ git remote add upstream https://github.com/PaloAltoNetworks/pan-os-ansible.git
$ git fetch upstream
$ git checkout develop
$ git merge upstream/develop

Each time you do this, you should run pipenv sync --dev to make sure your local virtual environment is updated with any new libraries used by the project.

Finally, create a topic branch in your local repository to store your work. Give it a meaningful name that describes what you're working on:

$ git checkout -b my_new_feature

You're now ready to work on your feature!

Required Checks

GitHub Actions runs the following tests when opening a pull request, and code must pass these at a minimum before being merged. You can test locally before opening a pull request with the following commands (or make tests to run them all at once):

  • make check-format - Code is formatted using black, imports are sorted using isort.
  • make units - Code passes unit tests.
  • make sanity - Code passes Ansible sanity tests.
  • make ansible-lint - Included roles pass ansible-lint.

Commit your changes and push to GitHub

Once you're done, commit your changes, then push them up to your fork on GitHub:

$ git add -A
$ git commit
$ git push origin my_new_feature

Open a pull request

To get your code merged into the main repository, you need to open a pull request.

A maintainer will work with you to talk through your proposed changes and get them merged.

Thank you for contributing!

Clone this wiki locally