Merge pull request #1061 from jananivMS/docs-cleanup

Cleanup docs structure and add open source checklist requirements

CONTRIBUTING.md

@@ -0,0 +1,61 @@
+# Contributing Guidelines
+
+The Azure Service Operator project accepts contributions via GitHub pull requests. This document outlines the process to help get your contribution accepted.
+
+Please see also the [Azure Service Operator Developer Guide](docs/community/developer-guide.md).
+
+## Contributor License Agreements
+
+We'd love to accept your patches! Before we can take them, we have to jump a
+couple of legal hurdles.
+
+The [Microsoft CLA](https://cla.microsoft.com/) must be signed by all contributors. Please fill out either the individual or corporate Contributor License Agreement (CLA). Once you are CLA'ed, we'll be able to accept your pull requests.
+
+***NOTE***: Only original source code from you and other people that have
+signed the CLA can be accepted into the repository.
+
+## Support Channels
+
+This is an open source project and as such no formal support is available. However, like all good open source projects we do offer "best effort" support through github issues.
+
+GitHub issues can be filed here - https://github.com/Azure/azure-service-operator/issues
+
+Before opening a new issue or submitting a new pull request, it's helpful to search the project - it's likely that another user has already reported the issue you're facing, or it's a known issue that we're already aware of.
+
+## Issues
+
+Issues are used as the primary method for tracking anything to do with the Azure Service Operator project.
+
+### Issue Lifecycle
+
+The issue lifecycle is mainly driven by the core maintainers, but is good information for those contributing to the project. All issue types follow the same general lifecycle. Differences are noted below.
+1. Issue creation
+2. Triage
+    - The maintainer in charge of triaging will apply the proper labels for the issue. This includes labels for priority, type, and metadata. If additional
+    labels are needed in the future, we will add them.
+    - (If needed) Clean up the title to succinctly and clearly state the issue. Also ensure that proposals are prefaced with "Proposal".
+3. Discussion
+    - "Feature" and "Bug" issues should be connected to the PR that resolves it.
+    - Whoever is working on a "Feature" or "Bug" issue (whether a maintainer or someone from the community), should either assign the issue to themself or make a comment in the issue saying that they are taking it.
+    - "Proposal" and "Question" issues should stay open until resolved or if they have not been active for more than 30 days. This will help keep the issue queue to a manageable size and reduce noise. Should the issue need to stay open, the `keep open` label can be added.
+4. Issue closure
+
+## How to Contribute a Patch
+
+1. If you haven't already done so, sign a Contributor License Agreement (see details above).
+2. Fork the desired repo, develop and test your code changes.
+3. Submit a pull request.
+
+## Reporting Security Issues
+
+Microsoft takes the security of our software products and services seriously, which includes all source code repositories managed through our GitHub organizations, including this one.
+
+If you believe you have found a security vulnerability in this repository that meets Microsoft's [Microsoft's definition of a security vulnerability](https://docs.microsoft.com/en-us/previous-versions/tn-archive/cc751383(v=technet.10)), please report it to us as described below.
+
+**Please do not report security vulnerabilities through public GitHub issues.**
+
+Instead, please report them to the Microsoft Security Response Center (MSRC) at [https://msrc.microsoft.com/create-report](https://msrc.microsoft.com/create-report).
+
+We prefer all communications to be in English.
+
+Microsoft follows the principle of [Coordinated Vulnerability Disclosure](https://www.microsoft.com/en-us/msrc/cvd).

README.md

@@ -2,15 +2,11 @@
 
 [![Build Status](https://dev.azure.com/azure/azure-service-operator/_apis/build/status/Azure.azure-service-operator?branchName=master)](https://dev.azure.com/azure/azure-service-operator/_build/latest?definitionId=36&branchName=master)
 
-> This project is experimental. Expect the API to change. It is not recommended for production environments.
+> This project is experimental. The API is expected to change (while adhering to semantic versioning). It is not recommended for production environments.
 
-## Introduction
+The Azure Service Operator helps you provision Azure resources and connect your applications to them from within Kubernetes.
 
-An Operator is an application-specific controller that extends the Kubernetes API to create, configure, and manage instances of complex stateful applications on behalf of a Kubernetes user. It builds upon the basic Kubernetes resource and controller concepts but includes domain or application-specific knowledge to automate common tasks.
-
-(For more details about operators, we recommend [Introducing Operators: Putting Operational Knowledge into Software](https://coreos.com/blog/introducing-operators.html)).
-
-This repository contains the resources and code to provision and deprovision different Azure services using a Kubernetes operator.
+## Overview
 
 The Azure Operator comprises of:
 
@@ -21,46 +17,46 @@ The project was built using [Kubebuilder](https://book.kubebuilder.io/).
 
 For more details on the control flow of the Azure Service operator, refer to the link below
 
-[Azure Service Operator control flow](/docs/controlflow.md)
-
-## Install the operator
-
-This project maintains [releases of the Azure Service Operator](https://github.com/Azure/azure-service-operator/releases) that you can deploy via a [configurable Helm chart](./charts/azure-service-operator).
+[Azure Service Operator control flow](/docs/design/controlflow.md)
 
 ## Azure Services supported
 
-1. [Resource Group](/docs/resourcegroup/resourcegroup.md)
-2. [EventHub](/docs/eventhub/eventhub.md)
-3. [Azure SQL](/docs/azuresql/azuresql.md)
-4. [Azure Database for PostgreSQL](/docs/postgresql/postgresql.md)
-5. [Azure Database for MySQL](/docs/mysql/mysql.md)
-6. [Azure Keyvault](/docs/keyvault/keyvault.md)
-7. [Azure Rediscache](/docs/rediscache/rediscache.md)
-8. [Storage Account](/docs/storage/storageaccount.md)
-9. [Blob container](/docs/storage/blobcontainer.md)
-10. [Virtual Network](/docs/virtualnetwork/virtualnetwork.md)
-11. [Application Insights](/docs/appinsights/appinsights.md)
-12. [API Management](/docs/apimgmt/apimgmt.md)
-13. [Cosmos DB](/docs/cosmosdb/cosmosdb.md)
+- [Resource Group](/docs/services/resourcegroup/resourcegroup.md)
+- [EventHub](/docs/services/eventhub/eventhub.md)
+- [Azure SQL](/docs/services/azuresql/azuresql.md)
+- [Azure Database for PostgreSQL](/docs/services/postgresql/postgresql.md)
+- [Azure Database for MySQL](/docs/services/mysql/mysql.md)
+- [Azure Keyvault](/docs/services/keyvault/keyvault.md)
+- [Azure Rediscache](/docs/services/rediscache/rediscache.md)
+- [Storage Account](/docs/services/storage/storageaccount.md)
+- [Blob container](/docs/services/storage/blobcontainer.md)
+- [Virtual Network](/docs/services/virtualnetwork/virtualnetwork.md)
+- [Application Insights](/docs/services/appinsights/appinsights.md)
+- [API Management](/docs/services/apimgmt/apimgmt.md)
+- [Cosmos DB](/docs/services/cosmosdb/cosmosdb.md)
+- [Virtual Machine](/docs/services/virtualmachine/virtualmachine.md)
+- [Virtual Machine Scale Set](/docs/services/vmscaleset/vmscaleset.md)
 
-For more information on deploying, troubleshooting & deleting resources, refer to [this](/docs/customresource.md) link
+## Getting started
 
-## Building the operators
+This project maintains [releases of the Azure Service Operator](https://github.com/Azure/azure-service-operator/releases) that you can deploy via a [configurable Helm chart](/charts/azure-service-operator).
 
-You can also build, test, and run the operator from source by [following these instructions](/docs/contents.md).
+For detailed instructions on getting started, go [here](docs/howto/contents.md).
+
+Please see the [FAQ][docs/faq.md] for answers to commonly asked questions about the Azure Service Operator
 
 ## Contributing
 
-This project welcomes contributions and suggestions.  Most contributions require you to agree to a
-Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
-the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.
+The [contribution guide][contribution-guide] covers everything you need to know about how you can contribute to Azure Service Operators. The [developer guide][developer-guide] will help you onboard as a developer.
+
+## Support
+
+Azure Service Operator is an open source project that is [**not** covered by the Microsoft Azure support policy](https://support.microsoft.com/en-us/help/2941892/support-for-linux-and-open-source-technology-in-azure). [Please search open issues here](https://github.com/Azure/azure-service-operator/issues), and if your issue isn't already represented please [open a new one](https://github.com/Azure/azure-service-operator/issues/new/choose). The Azure Service Operator project maintainers will respond to the best of their abilities.
 
-When you submit a pull request, a CLA bot will automatically determine whether you need to provide
-a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions
-provided by the bot. You will only need to do this once across all repos using our CLA.
+## Code of conduct
 
-For more specific information on the GIT workflow and guidelines to follow, check [here](docs/contributionguidelines.md).
+This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information, see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq) or contact [[email protected]](mailto:[email protected]) with any additional questions or comments.
 
-This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
-For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
-contact [[email protected]](mailto:[email protected]) with any additional questions or comments.
+[contribution-guide]: CONTRIBUTING.md
+[developer-guide]: docs/howto/contents.md
+[FAQ]: docs/faq.md

docs/faq.md

@@ -0,0 +1,15 @@
+# Azure Service Operator FAQ
+
+This page provides help with the most common questions about Azure Service Operators
+
+### Do I have to order the creation of resources through the operator? For instance, do I need to first create the EventHub namespace before creating the EventHub?
+No, you can issue the creation of all resources at the same time. The operator will take care of waiting and requeing the requests until the parent resource is ready and all resources will eventually be ready.
+
+### If I need to add a new field to the spec of an existing CRD, do I need to increment the version of the CRD?
+Yes, we follow semantic versioning to preserve backward compatibility. Please follow Kubebuilder's versioning [mechanism](https://book.kubebuilder.io/multiversion-tutorial/conversion-concepts.html) for this.
+
+### Is there a guide that talks about how to develop an operator for a new Azure service?
+There is a step-by-step guide that walks you through this process [here](/howto/newoperatorguide.md)
+
+### Are there any sample apps that demonstrate how to utilize the Azure Service Operators?
+We have some samples that illustrate how to use Azure Service Operators along with your application [here](https://github.com/Azure-Samples/azure-service-operator-samples). The samples also show how to utilize post-deployment-secrets from the Azure Service Operator.

docs/contents.md → docs/howto/contents.md

@@ -1,6 +1,6 @@
 # Azure Service Operator Documentation
 
-## Contents
+## Getting Started
 
 1. [Prereqs](prereqs.md)
     Find the list of tools and dependencies needed to develop and deploy the Azure Service Operator here.

docs/deploy.md → docs/howto/deploy.md

@@ -1,6 +1,10 @@
-# Building and deploying the Azure Service Operator
+# Deploying the Azure Service Operator
 
-## Build the operator
+The easiest way to deploy the Azure Service Operator is to use Helm charts. Follow instructions [here] (helmdeploy.md)
+
+## Building and deploying the Azure Service Operator from source
+
+### Build the operator
 
 1. Clone the repository.
 
@@ -10,16 +14,16 @@
     export GO111MODULE=on
     ```
 
-3. Log into Docker Hub and then Build the image and push it to Docker Hub.
+3. Log in to your container registry, set the IMG env var, and then build and push the image.
 
     ```shell
     docker login
-    IMG=<dockerhubusername>/<imagename>:<tag> make build-and-push
+    IMG=<container_registry>/<username>/<image_name>:<tag> make build-and-push
     ```
 
-## Deploy the operator
+### Deploy the operator
 
-**Note** You should already have a Kuberenetes cluster prerequisites [here](prereqs.md) for information on creating a Kubernetes cluster.
+**Note** You should already have a Kubernetes cluster. See prerequisites [here](prereqs.md) for information on creating a Kubernetes cluster.
 
 1. Set up the Cluster