How to Contribute to Project
This project is used as the automation test suite for guest OS validation on vSphere, implemented with playbooks based on Ansible infrastructure and Ansible collections. So that setting up the development environment of this project need to install an Ansible control node firstly. For more information on how to install Ansible, please refer to this Ansible doc.
Below sample steps on how to setup the environment from scratch are executed in Ubuntu 22.04.1 live server virtual machine, which is used as the Ansible control node or development host. Please adjust the commands according to the OS type or version you are using.
- Make sure 'Python 3.9 or newer' is installed, e.g.,
$ python3 -V
Python 3.10.6
- Install 'pip' if it’s not installed.
$ sudo apt-get install python3-pip
- Install 'ansible-core', we recommend always use the latest ansible-core, and latest version of required Ansible collections.
$ python3 -m pip install --user ansible-core
- Check 'ansible-core' is installed, if 'ansible' command is not found, add it’s installation directory to the PATH, e.g. ''/home/test/.local/bin'.
$ ansible --version
ansible [core 2.14.1]
config file = None
configured module search path = ['/home/test/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules']
ansible python module location = /home/test/.local/lib/python3.10/site-packages/ansible
ansible collection location = /home/test/.ansible/collections:/usr/share/ansible/collections
executable location = /home/test/.local/bin/ansible
python version = 3.10.6 (main, Nov 2 2022, 18:53:38) [GCC 11.3.0] (/usr/bin/python3)
jinja version = 3.0.3
libyaml = True
Along with each release of this project, we also publish a docker image, which contains dependencies and the released source code of this project based on Photon OS. You can launch this docker image in a container to do testing or developing. Below sample steps on how to setup development environment in a container are executed in Ubuntu 22.04.1 live server virtual machine. Please adjust the commands according to the OS type and version you are using.
- Make sure 'docker' is installed.
$ sudo snap install docker
$ sudo docker version
- Pull the latest docker image of this project to local machine.
$ sudo docker pull projects.registry.vmware.com/gos_cert/ansible-vsphere-gos-validation:latest
- Start a container with this docker image.
$ sudo docker run -it --privileged projects.registry.vmware.com/gos_cert/ansible-vsphere-gos-validation:latest
This started container can be used as the Ansible control node or development host, you can continue to execute the steps in following part Contribute Changes in this started container. Step 1 in Make Changes part is not needed.
There are 3 ways to fork a repository, please refer to this github doc. Below example is creating a new fork from web browser.
- Login to github with your user account from web browser.
- Go to project ansible-vsphere-gos-validation page, click 'Fork' to get a copy of this repository as below.
- Login to the development host, open terminal and set your account's default identity.
$ git config --global user.email "[email protected]"
$ git config --global user.name "Your Name"
- Clone the forked repository to your development host locally, please refer to this doc, prepare your personal access token or use other authentication method to be used for git.
$ git clone https://github.com/YOUR_NAME/ansible-vsphere-gos-validation.git
- A new directory 'ansible-vsphere-gos-validation' is created and contains the source files, go to this directory, add upstream repository to your forked repository.
$ git remote add upstream https://github.com/vmware/ansible-vsphere-gos-validation.git
- Check the remote repository settings.
$ git remote -v
origin https://github.com/YOUR_NAME/ansible-vsphere-gos-validation.git (fetch)
origin https://github.com/YOUR_NAME/ansible-vsphere-gos-validation.git (push)
upstream https://github.com/vmware/ansible-vsphere-gos-validation.git (fetch)
upstream https://github.com/vmware/ansible-vsphere-gos-validation.git (push)
- Go to project directory, e.g., '/home/test/ansible-vsphere-gos-validation/', install dependent Python packages and Ansible collections using requirements files.
$ pip install -r requirements.txt
$ ansible-galaxy install -r requirements.yml
- Get the current branch status.
$ git branch
* main
- Create a new development branch and checkout it, do the changes based on this branch instead of 'main' branch.
$ git checkout -b <branch name>
Switched to a new branch <branch name>
- Make changes to the latest source code to fix issues or add new features. Then do testing on your changes.
- After testing passed, execute below commands to submit your changes. When Git prompts you for your password, enter your personal access token if you are using this authentication method.
# show changed files
$ git status
# add changed file to commit
$ git add <file>
# create a new commit
$ git commit -s -m 'commit description'
# submit the commits
$ git push origin <branch name>
- After you push the commits, in an opened web browser, go to Pull requests page to create a new merge request with your commits. Click 'New pull request' button as below:
- Input and select the development branch in your repository as the compared one as below. Improve the name of pull request, if there is corresponding issue to fix in the 'Issues' page, input 'Fixes #issue_number', describe how you fix this issue and the testing result.
- After your pull request created, we'll review the code change and run regression testing with this change if required. When testing passed and comments on the code change are resolved, the reviewer will approve and merge this pull request to the main branch.
- Change logs in each release.
- Common tasks for Linux/Windows VM Configuration or ESXi configuration.
- Configuration files for guest OS automatic installation.
- Guide for test case development.