Need for expanded guide for contributing.

[paultaiton]

SUMMARY

The current contributing guide is very basic and could use some elaboration to help onboard new contributors and ease the burden. I'm willing to draft the new guide, but I want to solicit some feedback before I put in the effort.

My current rough outline:
Detail the python linting standards that should be used.

Explain how to set up environment to run ansible-test integration azure_rm_module to validate locally before submitting PR.

Recommendations for new module design, specifically how the individual modules inherit from module_utils/azure_rm_common.py AzureRMModuleBase class, and instantiate shared management clients by 'property' decorated methods.

@haiyuazhang , @Fred-sun ,
The big question I know I need to ask is around python linting. Which lint software are you guys using while reviewing PRs? I have not had any issues since I started using pycodestyle, but if there's a more specific recommendation from you I'll use it. The current adjustments I've been making are to set max-line-length to 160 characters, ignore 'import not at top of file' errors, and warnings about "line break before binary operator". I'd appreciate confirmation on these as well as any other recommendations on linter tunables, as well as any other feedback you have before I start.

ISSUE TYPE

• Documentation Report

COMPONENT NAME

CONTRIBUTING.md

ANSIBLE VERSION

N/A

[paultaiton]

@l3ender
I know you have a particular interest in this effort as well.

[Fred-sun]

@paultaiton We are testing, mainly Sanity testing and functional testing, you may refer to the link below, thank you!

https://docs.ansible.com/ansible/latest/dev_guide/testing_sanity.html
https://docs.ansible.com/ansible/latest/user_guide/playbooks_checkmode.html
https://docs.ansible.com/ansible/latest/dev_guide/testing/sanity/index.html

[Fred-sun]

@paultaiton Usually we need to install some dependency files for the current environment, you can refer to "requirements-azure.txt" and "sanity-requirements-azure.txt". You can refer to the documentation --
https://docs.ansible.com/ansible/latest/dev_guide/testing_sanity.html

[l3ender]

@Fred-sun I believe the goal of this issue is to add documentation for this repo/collection's standards for linting, as well as how integration tests can be run for this collection. I've looked through the Ansible doc to try and figure out how to run tests in this repo and have not been able to do so until very recently (from much struggle and the advice in #450 (comment)). The best I've come up with so far is to do the following:

In this repo's root directory:

1. Build and install current branch:

   rm *.tar.gz
   ansible-galaxy collection build . --force
   ansible-galaxy collection install *.tar.gz --force

2. Create testing directory for running test:

   mkdir testing

3. Add a sample playbook which references the module I want to test. Save as testing/sandbox.yml.

   ---
   - name: Run test suite for module
     hosts: localhost
     connection: local
     vars:
       resource_group: my-test-rg
     tasks:
       - name: create prerequisite resource group
         azure.azcollection.azure_rm_resourcegroup:
           name: "{{ resource_group }}"
           location: eastus
       - include: ../tests/integration/targets/azure_rm_appgateway/tasks/main.yml

4. Copy required files to testing directory:

   cp tests/integration/targets/azure_rm_appgateway/files/cert* testing/

5. Run playbook to test module:

   ansible-playbook testing/sandbox.yml

It's taken quite a bit of time and effort of working in this repo before I came up with above. I know it doesn't cover running the whole test suite, but I think it would be helpful to add as documentation (along with the aforementioned linting guidelines). I'm happy to do so; can we reopen this issue and I will create a PR?

cc @paultaiton

[Fred-sun]

@l3ender This will provide more guidance for the execution of relevant tests. You are welcome to provide PR and I will push it forward. Thank you very much!

[paultaiton]

Hey guys,

I apologize for the delay in submitting a PR for this issue. I do still intend on doing so, however my time has been taken up with my job and personal issues.

@l3ender
Rough outline to make use of the built in ansible-test command for azcollection you have to

1. set up a service principal in your Azure subscription that has Owner role (or something less depending on your test) to two resource groups that is recomended be created solely for the purpose of Ansible testing.

2. copy file "cloud-config-azure.ini.template" to "~/.ansible/collections/ansible_collections/azure/azcollection/tests/integration/cloud-config-azure.ini" from the "./ansible_test/config/" directory in your python site library or venv. This is highly dependent on your system, but for me it was /home/paul/azure-ansible-test/.venv/lib64/python3.9/site-packages/ansible_test/config/cloud-config-azure.ini.template

3. edit the file with your SP details. For it to work for me I deleted everything except

[default]
AZURE_CLIENT_ID: 00000000-0000-0000-0000-000000000000
AZURE_SECRET: 00000000-0000-0000-0000-000000000000
AZURE_SUBSCRIPTION_ID: 00000000-0000-0000-0000-000000000000
AZURE_TENANT: 00000000-0000-0000-0000-000000000000

RESOURCE_GROUP:  ansibletesta
RESOURCE_GROUP_SECONDARY: ansibletestb

That should let you run the integration tests. for example in my storage account PR I edited "azcollection/tests/integration/targets/azure_rm_storageaccount" until the test cases covered whatever was missed and needed fixing, and ran
ansible-test integration azure_rm_storageaccount --allow-destructive -v
after my code changes until it was successful.

[l3ender]

@paultaiton I followed your steps but keep running into the following error. Do you know how to resolve?

-> ansible-test integration azure_rm_storageaccount -v
ERROR: Cannot run integration tests without "roles/test/" or "tests/integration/targets/".

I'm working a PR that takes all the notes in this issue and will submit it as soon as I get my problems resolved. :)

[paultaiton]

@paultaiton I followed your steps but keep running into the following error. Do you know how to resolve?

-> ansible-test integration azure_rm_storageaccount -v
ERROR: Cannot run integration tests without "roles/test/" or "tests/integration/targets/".

I'm working a PR that takes all the notes in this issue and will submit it as soon as I get my problems resolved. :)

When you're executing the tests, is your shell's pwd the collection directory?

[paul@devbox azcollection]$ pwd
/home/paul/.ansible/collections/ansible_collections/azure/azcollection
[paul@devbox azcollection]$ ls -ld tests/integration/targets/
drwx------ 1 paul paul 3358 Apr 27 16:05 tests/integration/targets/

[l3ender]

Yes, I am installing the collection to a staging directory and then cd to it to execute tests.

# from repo root dir:

ansible-galaxy collection build .
ansible-galaxy collection install azure-azcollection-*.tar.gz -p tests/staging
cd tests/staging/ansible_collections/azure/azcollection/

[paultaiton]

Other than that I don't have any idea.

I made a dedicated VM that I only use for azcollection development, and I cloned the repo directly into ~/.ansible/collections/ansible_collections/azure/ . Other than that I'm doing everything with the default configuration, and it just works for me.

[l3ender]

Turns out I was being bit by ansible/ansible#68499. I've resolved my issue and updated the PR appropriately.