github templates and docs (#168)

CONTRIBUTING.md

@@ -0,0 +1,14 @@
+> This article is not a detailed guide on how to create a pull request (PR). See [here](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests) to learn more about how to work with pull requests on GitHub.
+
+The purpose of this article is to illustrate the main checklists you must go through before a PR will be considered for inclusion in Microsoft.AVS.Management. 
+
+These are the following checks we'll normally put in place:
+
+0. **Accept contributor agreement**
+1. **Create an issue**
+   Except for small changes, alwats create an issue 1st to discuss the propsal before opening a PR. 
+2. **Create Documentation**
+   Every new function **must** have standard PowerShell documentation. If you modify a function and add a parameter, it **must** have associated documentation markup.
+3. **Adhere to [PowerShell style guidelines](https://learn.microsoft.com/en-us/powershell/scripting/developer/cmdlet/required-development-guidelines?view=powershell-7.3) and [AVS Scripting guidelines](docs/README.md)**
+   Format and test your code.
+4. **Do NOT modify repository policies**

SUPPORT.md

@@ -1,13 +1,3 @@
-# TODO: The maintainer of this repo has not yet edited this file
-
-**REPO OWNER**: Do you want Customer Service & Support (CSS) support for this product/project?
-
-- **No CSS support:** Fill out this template with information about how to file issues and get help.
-- **Yes CSS support:** Fill out an intake form at [aka.ms/spot](https://aka.ms/spot). CSS will work with/help you to determine next steps. More details also available at [aka.ms/onboardsupport](https://aka.ms/onboardsupport).
-- **Not sure?** Fill out a SPOT intake as though the answer were "Yes". CSS will help you decide.
-
-*Then remove this first heading from this SUPPORT.MD file before publishing your repo.*
-
 # Support
 
 ## How to file issues and get help  
@@ -16,10 +6,8 @@ This project uses GitHub Issues to track bugs and feature requests. Please searc
 issues before filing new issues to avoid duplicates.  For new issues, file your bug or 
 feature request as a new Issue.
 
-For help and questions about using this project, please **REPO MAINTAINER: INSERT INSTRUCTIONS HERE 
-FOR HOW TO ENGAGE REPO OWNERS OR COMMUNITY FOR HELP. COULD BE A STACK OVERFLOW TAG OR OTHER
-CHANNEL. WHERE WILL YOU HELP PEOPLE?**.
+For help and questions about using this project, please work with your AVS contact.
 
 ## Microsoft Support Policy  
 
-Support for this **PROJECT or PRODUCT** is limited to the resources listed above.
+Support for this repository is limited to the resources listed above.

docs/README.md

@@ -32,7 +32,7 @@ AVS will expose some standard runtime options via PowerShell variables.  See bel
 | `SFTP_Sessions` | Dictionary of hostname to [Lazy](https://docs.microsoft.com/en-us/dotnet/api/system.lazy-1?view=netcore-2.1) instance of [posh-ssh sftp session](https://github.com/darkoperator/Posh-SSH/blob/master/docs/New-SFTPSession.md) | `New-SFTPItem -ItemType Directory -Path "/tmp/zzz" -SFTPSession $SSH_Sessions[esx.hostname.fqdn].Value`. Another key to the dictionary is `"VC"` for SFTP to vCenter
 
 > <b>Persistent secrets</b>: 
-The secrets are kept in a Keyvault, they are isolated on package name basis, shared across all versions of your package and made available for each of your package scripts. Delete a secrets by setting a property to an empty string or `$null`.
+The secrets are kept in a Keyvault, they are isolated on package name basis, shared across all versions of your package and made available for each of your package scripts. Delete secrets by setting the hastable entry to an empty string or `$null`.
 
 The script shall assume the directory it is executed in is temporary and can use it as needed, assuming 25GB is available.  This environment including any files will be torn down after the script execution.
 
@@ -62,7 +62,7 @@ A Module should not attempt to login to vCenter with the AVS provided `cloudadmi
 
 ## Never elevate privileges for cloudadmins
 
-A Module should not attempt to elevate privileges for the AVS provided `cloudadmins` role.  Scripts that attempt to do this will not be allowed to run against an AVS Private Cloud. Elevating privileges for cloudadmin could have unintended consequences by giving elevated access to anyone using cloudadmin.  The script is already logged in with administrator privileges and does not require elevating `cloudadmins` role.
+A Module should not attempt to elevate privileges for the AVS provided `cloudadmins` role.  Scripts that attempt to do this will not be allowed to run against an AVS Private Cloud. Elevating privileges for cloudadmin could have unintended consequences by giving elevated access to anyone using cloudadmin. The script is already logged in with administrator privileges and does not require elevating `cloudadmins` role.
 
 ## Never use cloudadmin as the user for any installed software
 
@@ -111,7 +111,8 @@ The script execution pipeline supports following PowerShell streams:
 - Warning
 - Error
 
-Use the stream appropriate for the purpose, suppress outputs with `Out-Null` for information that doesn't not help with the installation or troubleshooting.
+Use the stream appropriate for the purpose, suppress outputs with `Out-Null` for information that doesn't not help with the installation or troubleshooting. 
+Be aware that content of these streams is always stored as strings. Objects emitted into these streams should either be primitives (strings, ints, etc), of type `HashTable` or be explicitly converted to string by your script, otherwise they may fail to deserialize and won't be captured.
 
 Use `-ErrorAction Stop` or equivalent means to terminate with an error and indicate the final status to the user.
 

pull_request_template.md

@@ -0,0 +1,14 @@
+This PR closes #
+
+The changes in this PR are as follows:
+
+* ...
+* ...
+* ...
+
+I have read the [contributor guidelines](CONTRIBUTING.md) and have completed the following:
+
+* [ ] **Formatted the code** using VSCode default formatter for PowerShell.
+* [ ] **Tested the code** end-to-end against an SDDC.
+* [ ] **Documented the functions** using standard PowerShell markup and applied `AVSAttribute` to newly exported functions.
+