Documentation/contribution section

README.md

@@ -63,6 +63,8 @@ If you wish to contribute code, and you have not signed our Contributor Licence
 to do so when you open a Pull Request. For any questions about the CLA process, please refer to our
 [FAQ](https://cla.vmware.com/faq).
 
+For additional information about contributing, go to the [contribution documentation](contributrion/README.md)
+
 ## License
 
 This project is licensed under the APACHE-2 License.

contributing/README.md

@@ -0,0 +1,23 @@
+# Contributing
+
+Before you start contributing to the project, you should familiarize yourself with the [documentation](vmware.github.io/vmware-aria-operations-integration-sdk/),
+[issue tracker](https://github.com/vmware/vmware-aria-operations-integration-sdk/issues), [project structure](index.md),
+and basic functioning of every component.
+
+## Environment
+This project uses Python 3.9 - 3.12. All other dependencies can be installed via [poetry](https://python-poetry.org/), by
+running:
+
+```shell
+poetry install --only=dev
+```
+
+### Tests
+Every change you make should be accompanied by appropriate tests. TO learn more about running current tests,
+go to [Unit Tests](tests.md) documentation.
+
+## Submit Your Contribution
+Once you're confident in the changes, it's time to submit them. Create a pull request. Include a clear description of
+the changes in the pull request along with any issues resolved, if any. The changes will then be reviewed by the maintainers
+of the project. If there are any issues with your changes, one of the maintainers will give you feedback. You may need to make further changes based on
+this feedback before your contribution is accepted.

development/docker.md → contributing/docker.md

@@ -1,4 +1,4 @@
-# Server Development
+# Base Adapter Images
 * * *
 
 ### Images
@@ -35,11 +35,10 @@ docker build --no-cache java-client --tag base-adapter:java-0.3.0
 #### Tagging Convention
 Tags differentiate characteristics of the built image. Every image must have a _unique tag_, plus optional additional tags known as _stable tags_:
 
-!!! quote
-    Stable tags mean a developer, or a build system, can continue to pull a specific tag, which
-    continues to get updates. Stable doesn’t mean the contents are frozen. Rather, stable implies the image
-    should be stable for the intent of that version. To stay “stable”, it might be serviced to apply
-    patches or framework updates.([Steve Lasker](https://docs.microsoft.com/en-us/azure/container-registry/container-registry-image-tag-version#:~:text=Stable%20tags%20mean,or%20framework%20updates.)).
+> "Stable tags mean a developer, or a build system, can continue to pull a specific tag, which
+  continues to get updates. Stable doesn’t mean the contents are frozen. Rather, stable implies the image
+  should be stable for the intent of that version. To stay “stable”, it might be serviced to apply
+  patches or framework updates.([Steve Lasker](https://docs.microsoft.com/en-us/azure/container-registry/container-registry-image-tag-version#:~:text=Stable%20tags%20mean,or%20framework%20updates.))."
 
 ##### Unique Tag
 Each image should have a unique tag with the following format:
@@ -51,11 +50,11 @@ The language component of a tag specifies the main language supported by the gen
 Language is one of `python`,`java`, or `powershell`. If an unsupported language is desired, the base
 image `base-adapter:python` can be used as a starting point to install an additional
 language or runtime environment. The base image contains the HTTP server, which is required to serve
-calls from VMware Aria Operations and the user's adapter. It is also possible to start from a different 
+calls from VMware Aria Operations and the user's adapter. It is also possible to start from a different
 base image, but in this case an HTTP server that conforms to the collector API must be manually added.
 
 ###### Server Version
-The main component in the project is the HTTP Server defined by the VMware Aria Operations Collector API. 
+The main component in the project is the HTTP Server defined by the VMware Aria Operations Collector API.
 Therefore, the image version is based on the API version and follows [semantic versioning](https://semver.org/).
 
 
@@ -92,7 +91,7 @@ unique tag `python-0.3.0`.
 	docker tag base-adapter:python-0.3.0 base-adapter:python-latest
 	```
 
-## [Harbor](https://confluence.eng.vmware.com/display/HARBOR/Harbor)
+## [Harbor](https://goharbor.io/)
 
 ### What is it?
 Harbor is an open source container image registry that secures images
@@ -103,7 +102,7 @@ native compute platforms like Kubernetes and Docker.
 
 ### Why use it?
 Harbor is a VMware platform that allows full control of projects for internal or external distribution
-without the liabilities of an externally hosted solution like Dockerhub.
+without the liabilities of an externally hosted solution like Docker Hub.
 
 ### Pulling Images
 1. Make sure you have access to Harbor by logging in to the [vmware_aria_operations_integration_sdk](https://projects.registry.vmware.com/harbor/projects/46752/repositories) registry,

contributing/documentation.md

@@ -0,0 +1,42 @@
+# GitHub Pages Documentation
+
+This project uses [Github Pages](https://pages.github.com/) to host a static site. The static site uses
+HTML as opposed to markdown, so there is a broader range of possible customization. To generate the HTML in the static site,
+we use [MKDocs](https://www.mkdocs.org) alongside [Material](https://squidfunk.github.io/mkdocs-material),
+and [mkdocstrings-python](https://mkdocstrings.github.io/python/), which allows us to use markdown files to write our 
+site and also automate our release process using [GitHub Actions](https://github.com/features/actions).
+
+
+## MKDocs Project Structure
+
+The `mkdocs.yml` file located at the project's root defines the project's main configuration, which includes plugins,
+themes, and markdown extensions. All the documentation for the project's site is in the `docs` directory, the default
+entry point used by MKDocs.
+
+## Python Library Documentation
+
+To write the documentation of our [vmware-aria-operations-integration-sdk-lib](lib/python), we use 
+[mkdocstrings](https://mkdocstrings.github.io/python/), which allows us to auto-generate our code's documentation by 
+reading our code structure along with the docstrings throughout the code. By default, mkdocstrings uses 
+[Google-Style docstrings](https://google.github.io/styleguide/pyguide.html), so all of our docstrings follow them.
+
+## Development
+
+1. install all development dependencies in your local virtual environment:
+
+```
+poetry install --only=dev
+```
+
+2. Start the MKDocs development service to host a local site with hot-reload:
+
+```
+mkdocs serve
+```
+
+3. Voila! Ready to develop. Edit/create a file inside the `docs` folder and use regular markdown notation. The additional markdown can also be used as part of the Markdown extensions. References to the markdown extensions will be based on the extension, but most references come from Material's [reference page](https://squidfunk.github.io/mkdocs-material/reference/).
+
+
+4. Open a PR. Once the PR is merged, the action defined at .github/workflows/documentation.yml will trigger and re-generate the new site.
+
+

contributing/http_server.md

@@ -0,0 +1,96 @@
+# HTTP Server
+
+## Overview
+The base adapter image uses Debian as its base OS.
+
+The server inside the base adapter image was generated by using:
+- [OpenAPI-Spec](https://github.com/swagger-api/swagger-core/wiki) to define the API.
+- [swagger-codegen](https://github.com/swagger-api/swagger-codegen) to generate serrver stubs using the file defined with OpenAPI.
+- [Connexion framework](https://github.com/zalando/connexion) to map each of the endpoint specified in the OpenAPI file to map to our Python functions.
+
+## Requirements
+Python 3.9+
+
+## Regenerate the server
+To regenerate the server: 
+1.  If necessary, update the swagger API JSON file(s) in `vmware_aria_operations_integration_sdk/api`
+2.  Run the following command from the `images` directory:
+    ```shell
+    python3 update-base-python-adapter-server.py
+    ```
+    This script will combine both of the JSON files inside the 
+    `vmware_aria_operations_integration_sdk/api` and then generate a JSON file at 
+    `images/base-python-adapter/combined.json`. The script then runs a swagger container 
+    image that reads the combined JSON file, generates an HTTP server that implements
+    the API specification, and writes the code to the `base-python-adapter` directory.
+3.  Fix any conflicts that arise from the new server and the existing one. In particular:
+    *  `images/base-python-adapter/swagger_server/swagger/swagger.yaml` will need to be
+        updates to the `x-openapi-router-controller` for each path. The implementation 
+        for the api paths are in `images/base-python-adapter/swagger_server/controllers/controller.py`,
+        and as such the `x-openapi-router-controller` should be set to 
+       `swagger_server.controllers.controller`.
+4.  Any updates to the API that require changes in behavior or new behavior should be
+    implemented in the controller.
+
+## Testing the server using `mp-test`
+In many cases it is useful to test changes to the server using a test adapter and 
+`mp-test`. To do this follow these steps:
+1.  Create a new management pack project using `mp-init`.
+2.  Copy the `base-python-adapter` directory into the root project directory.
+3.  Modify the Dockerfile as follows:
+    ```dockerfile
+    FROM python:3.11.1-slim-bullseye
+
+    RUN mkdir -p /var/log/
+    RUN chmod 777 /var/log/
+
+    RUN useradd --create-home --shell /bin/bash vrops-adapter-user
+    USER vrops-adapter-user
+    WORKDIR /home/vrops-adapter-user/src/app
+
+    COPY base-python-adapter .
+    RUN pip3 install --no-cache-dir -r requirements.txt
+
+    # Start Original Adapter Dockerfile
+    COPY adapter_requirements.txt .
+    RUN pip3 install -r adapter_requirements.txt --upgrade
+    COPY commands.cfg .
+    COPY app app
+    # End Original Adapter Dockerfile
+
+    EXPOSE 8080
+    EXPOSE 443
+
+    ENTRYPOINT ["python3"]
+    CMD ["-m", "swagger_server"]
+    ```
+4.  The new server and/or base image can now be tested using `mp-test`. Changes in 
+    the project's `base-python-adapter` will take effect the next time `mp-test` is
+    run. If changes are make, they will need to be manually copied back to the SDK
+    project.
+
+## Testing the server locally
+To run the server outside a container/adapter, run the following from the root directory:
+
+```
+pip3 install -r requirements.txt
+python3 -m swagger_server
+```
+
+and open your browser to here:
+
+```
+http://localhost:8080/ui/
+```
+
+Your Swagger definition lives here:
+
+```
+http://localhost:8080/swagger.json
+```
+
+To launch the integration tests, use tox:
+```
+sudo pip install tox
+tox
+```

contributing/index.md

@@ -0,0 +1,13 @@
+# SDK Structure
+
+The SDK Git repository has the following layout:
+* `.github/workflows`: Defines the GitHub Actions for the project: Deploying the [GitHub Pages](documentation.md) site, running [tests](tests.md)/CI, and formatting.
+* `docs`: Sources for the [GitHub Pages](documentation.md) site.
+* `images`: Contains all the container images used by adapters, and [tools for generating and publishing the images](docker.md).
+* `images/base-python-adapter`: Sources for the base container image used by Python Adapters, including the [REST Server](http_server.md).
+* `images/java-adapter`: Sources for the base container image used by Java Adapters. Extends the `base-python-adapter` image.
+* `images/powershell-adapter`: Sources for the base container image used by Powershell Adapters. Extends the `base-python-adapter` image.
+* `lib/python`: Sources for the Python Adapter Library (`vmware-aria-operations-integration-sdk-lib`).
+* `samples`: Contains sample and template projects, for users to use, extend, or reference.
+* `tests`: [Unit tests](tests.md) for the SDK tools.
+* `vmware_aria_operations_integration_sdk`: Sources for the SDK tools (`mp-init`, `mp-test`, and `mp-build`).

contributing/tests.md

@@ -0,0 +1,30 @@
+# Unit Tests
+
+## Unit tests for the SDK Tools
+SDK Unit Tests are located in the `tests` directory.
+Tests are written for `pytest`, and can be manually started by running:
+```shell
+pytest -s tests
+```
+The SDK can run on Linux, macOS, and Windows, and as such the unit tests should
+work on each of these operating systems.
+
+There is a GitHub Action (`.github/workflows/aria-operations-integration-sdk.yaml`) 
+that runs these tests for each OS and each supported Python version on each Pull 
+Request.
+
+## Unit tests for the Python Adapter Library
+Python Adapter Library Unit Tests are located in the `lib/python/tests` directory.
+Tests are written for `pytest`, and can be manually started by running:
+```shell
+pytest -s lib/python/tests
+```
+The Python Adapter Library is designed to run on the base container image which is 
+based on Debian Linux. As such, the tests are only run on a Linux environment
+
+There is a GitHub Action (`.github/workflows/aria-operations-integration-sdk.yaml`)
+that runs these tests for Linux with each supported Python version on each Pull
+Request.
+
+
+