Merge pull request #111 from muvaf/readmeupdates

docs: add contribution guide and edit outdated parts of README

CODE_OF_CONDUCT.md

@@ -1,3 +1,3 @@
 ## Code of Conduct
 
-Upjet is under [the Apache 2.0 license](LICENSE) with [notice](LEGAL_NOTICE).
+Upjet is under [the Apache 2.0 license](LICENSE) with [notice](NOTICE).

CONTRIBUTING.md

@@ -0,0 +1,110 @@
+# Contributing to Upjet
+
+Welcome, and thank you for considering contributing to Upjet. We encourage
+you to help out by raising issues, improving documentation, fixing bugs, or
+adding new features
+
+If you're interested in contributing please start by reading this document. If
+you have any questions at all, or don't know where to start, please reach out to
+us on [Slack]. Please also take a look at our [code of conduct], which details
+how contributors are expected to conduct themselves.
+
+## Contributing Code
+
+To contribute bug fixes or features to Upjet:
+
+1. Communicate your intent.
+1. Make your changes.
+1. Test your changes.
+1. Update documentation and examples where appropriate.
+1. Open a Pull Request (PR).
+
+Communicating your intent lets the Upjet maintainers know that you intend
+to contribute, and how. This sets you up for success - you can avoid duplicating
+an effort that may already be underway, adding a feature that may be rejected,
+or heading down a path that you would be steered away from at review time. The
+best way to communicate your intent is via a detailed GitHub issue. Take a look
+first to see if there's already an issue relating to the thing you'd like to
+contribute. If there isn't, please raise a new one! Let us know what you'd like
+to work on, and why. The Upjet maintainers can't always triage new issues
+immediately, but we encourage you to bring them to our attention via [Slack].
+
+Be sure to practice [good git commit hygiene] as you make your changes. All but
+the smallest changes should be broken up into a few commits that tell a story.
+Use your git commits to provide context for the folks who will review PR, and
+the folks who will be spelunking the codebase in the months and years to come.
+Ensure each of your commits is signed-off in compliance with the [Developer
+Certificate of Origin] by using `git commit -s` and follow the CLA instructions.
+The Upjet project highly values readable, idiomatic Go code. Familiarise
+yourself with the [Coding Style] and try to preempt any comments your reviewers
+would otherwise leave. Run `make reviewable` to lint your change.
+
+All Upjet code must be covered by tests. Upjet does not use Ginkgo tests and
+will request changes to any PR that uses Ginkgo or any third party testing
+library, per the common Go [test review comments]. Upjet encourages the use
+of table driven unit tests.
+
+Note that when opening a PR your reviewer will expect you to detail how you've
+tested your work. For all but the smallest changes some manual testing is
+encouraged in addition to unit tests.
+
+All Upjet documentation is under revision control; see the [docs] directory
+of this repository. Any change that introduces new behaviour or changes existing
+behaviour must include updates to any relevant documentation. Please keep
+documentation changes in distinct commits.
+
+Once your change is written, tested, and documented the final step is to have it
+reviewed! You'll be presented with a template and a small checklist when you
+open a PR. Please read the template and fill out the checklist. Please make all
+requested changes in subsequent commits. This allows your reviewers to see what
+has changed as you address their comments. Be mindful of  your commit history as
+you do this - avoid commit messages like "Address review feedback" if possible.
+If doing so is difficult a good alternative is to rewrite your commit history to
+clean them up after your PR is approved but before it is merged.
+
+In summary, please:
+
+* Discuss your change in a GitHub issue before you start.
+* Use your Git commit messages to communicate your intent to your reviewers.
+* Sign-off on all Git commits by running `git commit -s`
+* Add or update tests for all changes.
+* Preempt [Coding Style] review comments.
+* Update all relevant documentation.
+* Don't force push to address review feedback. Your commits should tell a story.
+* If necessary, tidy up your git commit history once your PR is approved.
+
+Thank you for reading through our contributing guide! We appreciate you taking
+the time to ensure your contributions are high quality and easy for our
+community to review and accept. Please don't hesitate to [reach out to
+us][Slack] if you have any questions about contributing!
+
+## Establishing a Development Environment
+
+Upjet is a set of Go packages that is imported by providers. When you make a
+change in Upjet, the best way to test it is to use a `replace` statement in the
+`go.mod` file of the provider to use your local version as shown below.
+
+```
+replace github.com/upbound/upjet => ../upjet
+```
+
+Once you complete your change, make sure to run `make reviewable` before opening
+your PR.
+
+In most cases, it's helpful to open the PR in your provider repositories to
+show the usage and impact of your change and refer it in your Upjet PR
+description. In order for this to work, you'll need to `replace` the Upjet used
+in your provider to point to a certain commit in your branch of the provider that
+you opened a PR for.
+
+```
+replace github.com/upbound/upjet => github.com/<your user name>/upjet <hash of the last commit from your branch>
+```
+
+[Slack]: https://crossplane.slack.com/archives/C01TRKD4623
+[code of conduct]: https://github.com/cncf/foundation/blob/master/code-of-conduct.md
+[good git commit hygiene]: https://www.futurelearn.com/info/blog/telling-stories-with-your-git-history
+[Developer Certificate of Origin]: https://github.com/apps/dco
+[test review comments]: https://github.com/golang/go/wiki/TestComments
+[docs]: docs/
+[Coding Style]: https://github.com/crossplane/crossplane/blob/master/CONTRIBUTING.md#coding-style

README.md

@@ -1,23 +1,25 @@
 # Upjet - Generate Crossplane Providers from any Terraform Provider
+<div align="center">
+
+![CI](https://github.com/upbound/upjet/workflows/CI/badge.svg) [![GitHub release](https://img.shields.io/github/release/upbound/upjet/all.svg?style=flat-square)](https://github.com/upbound/upjet/releases) [![Go Report Card](https://goreportcard.com/badge/github.com/upbound/upjet)](https://goreportcard.com/report/github.com/upbound/upjet) [![Slack](https://slack.crossplane.io/badge.svg)](https://crossplane.slack.com/archives/C01TRKD4623) [![Twitter Follow](https://img.shields.io/twitter/follow/upbound_io.svg?style=social&label=Follow)](https://twitter.com/intent/follow?screen_name=upbound_io&user_id=788180534543339520)
+
+</div>
 
 Upjet is a code generator framework that allows developers to build code
 generation pipelines that can generate Crossplane controllers. Developers can
 start building their code generation pipeline targeting specific Terraform Providers
 by importing Upjet and wiring all generators together, customizing the whole
 pipeline in the process.
 
-See [design document][design-doc] for more details.
-
-Feel free to test the following Crossplane providers built using Upjet:
+Here is some Crossplane providers built using Upjet:
 
-* [Provider AWS](https://github.com/upbound/provider-aws/releases)
-* [Provider Azure](https://github.com/upbound/provider-azure/releases)
-* [Provider GCP](https://github.com/upbound/provider-gcp/releases)
+* [Provider AWS](https://github.com/upbound/provider-aws)
+* [Provider Azure](https://github.com/upbound/provider-azure)
+* [Provider GCP](https://github.com/upbound/provider-gcp)
 
-## Generating a New Provider Using Upjet
+## Getting Started
 
-Please see [this guide](docs/generating-a-provider.md) for detailed steps on how
-to generate a Crossplane provider based on an existing Terraform provider.
+You can get started by following the guides in [docs](docs/README.md) directory!
 
 ## Report a Bug
 
@@ -34,38 +36,14 @@ Please use the following to reach members of the community:
 * Twitter: [@crossplane_io](https://twitter.com/crossplane_io)
 * Email: [[email protected]](mailto:[email protected])
 
-## Governance and Owners
-
-upjet is governed solely by Upbound Inc.
-
 ## Prior Art
 
-There are many projects in infrastructure space that builds on top of Terraform.
-Each of the projects have their own limitations, additional features and different
-license restrictions.
-
-* [Crossplane: Terraform Provider Runtime](https://github.com/crossplane/crossplane/blob/e2d7278/design/design-doc-terraform-provider-runtime.md)
-* [Crossplane: provider-terraform](https://github.com/crossplane-contrib/provider-terraform)
-* [Hashicorp Terraform Cloud Operator](https://github.com/hashicorp/terraform-k8s)
-* [Rancher Terraform Controller](https://github.com/rancher/terraform-controller)
-* [OAM Terraform Controller](https://github.com/oam-dev/terraform-controller)
-* [Kubeform](https://github.com/kubeform/kubeform)
-* [Terraform Operator](https://github.com/isaaguilar/terraform-operator)
-
-
-## Contributing
-
-* [Generating a Provider](docs/generating-a-provider.md)
-* [Configuring a Resource](docs/configuring-a-resource.md)
-* [Reference Generation](docs/reference-generation.md)
-* [New v1beta1 Resources](docs/new-v1beta1-resource.md)
-* [Moving Resources to v1beta1](docs/moving-resources-to-v1beta1.md)
-* [Testing Instructions](docs/testing-instructions.md)
-* [Testing Resources by Using Uptest](docs/testing-resources-by-using-uptest.md)
+Upjet originates from the [Terrajet][terrajet] project. See the original 
+[design document][terrajet-design-doc].
 
 ## Licensing
 
-All rights of upjet belongs to Upbound Inc.
+Provider AWS is under [the Apache 2.0 license](LICENSE) with [notice](NOTICE).
 
-[design-doc]: https://github.com/crossplane/crossplane/blob/master/design/design-doc-terrajet.md
-[provider-template]: https://github.com/crossplane/provider-template
+[terrajet-design-doc]: https://github.com/crossplane/crossplane/blob/master/design/design-doc-terrajet.md
+[terrajet]: https://github.com/crossplane/terrajet

docs/README.md

@@ -0,0 +1,35 @@
+# Using Upjet
+
+Upjet consists of three main pieces:
+* Framework to build a code generator pipeline.
+* Generic reconciler implementation used by all generated `CustomResourceDefinition`s.
+* A scraper to extract documentation for all generated `CustomResourceDefinition`s.
+
+The usual flow of development of a new provider is as following:
+1. Create a provider by following the guide [here][generate-a-provider].
+2. Follow the guide [here][new-v1beta1] to add a `CustomResourceDefinition` for
+   every resource in the given Terraform provider.
+
+In most cases, the two guides above would be enough for you to get up and running
+with a provider.
+
+The guides below are longer forms for when you get stuck and want a deeper
+understanding:
+* Description of all configuration knobs can be found [here][full-guide].
+* Detailed explanation of how to use Uptest to test your resources can be found
+  [here][uptest-guide].
+  * You can find a troubleshooting guide [here][testing-instructions] that can
+    be useful to debug a failed test.
+* References are inferred from the generated examples with a best effort manner.
+  Details about the process can be found [here][reference-generation].
+
+Feel free to ask your questions by opening an issue, starting a discussion or
+shooting a message on [Slack]!
+
+[generate-a-provider]: generating-a-provider.md
+[new-v1beta1]: add-new-resource-short.md
+[full-guide]: add-new-resource-long.md
+[uptest-guide]: testing-resources-by-using-uptest.md
+[testing-instructions]: testing-instructions.md
+[reference-generation]: reference-generation.md
+[Slack]: https://crossplane.slack.com/archives/C01TRKD4623

docs/configuring-a-resource.md → docs/add-new-resource-long.md

@@ -363,7 +363,7 @@ Crossplane stores sensitive information of a managed resource in a Kubernetes
 secret, together with some additional fields that would help consumption of the
 resource, a.k.a. [connection details].
 
-In Upjet, we already [handle sensitive fields] that are marked as sensitive
+In Upjet, we already handle sensitive fields that are marked as sensitive
 in Terraform schema and no further action required for them. Upjet will
 properly hide these fields from CRD spec and status by converting to a secret
 reference or storing in connection details secret respectively. However, we
@@ -690,7 +690,6 @@ So, an interface must be passed to the related configuration field for adding in
 [iam_access_key]: https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_access_key#argument-reference
 [kms key]: https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ebs_volume#kms_key_id
 [connection details]: https://crossplane.io/docs/v1.7/concepts/managed-resources.html#connection-details
-[handle sensitive fields]: https://github.com/crossplane/terrajet/pull/77
 [id]: https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_access_key#id
 [secret]: https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_access_key#secret
 [`external.Observe`]: https://github.com/upbound/upjet/blob/874bb6ad5cff9741241fb790a3a5d71166900860/pkg/controller/external.go#L149

docs/generating-a-provider.md

@@ -9,7 +9,7 @@ be quite similar for any other Terraform provider.
 ## Generate
 
 1. Generate a GitHub repository for the Crossplane provider by hitting the
-   "**Use this template**" button in [provider-jet-template] repository.
+   "**Use this template**" button in [upjet-provider-template] repository.
 2. Clone the repository to your local and `cd` into the repository directory.
    Fetch the [upbound/build] submodule by running the following:
 
@@ -49,7 +49,7 @@ be quite similar for any other Terraform provider.
    variables are used to build the provider plugin binary.
 
 
-5. Implement `ProviderConfig` logic. In `provider-jet-template`, there is already
+5. Implement `ProviderConfig` logic. In `upjet-provider-template`, there is already
    a boilerplate code in file `internal/clients/${ProviderNameLower}.go` which
    takes care of properly fetching secret data referenced from `ProviderConfig`
    resource.
@@ -183,7 +183,7 @@ be quite similar for any other Terraform provider.
    ```
 
    **_To learn more about custom resource configurations (in step 7), please see
-   the [Configuring a Resource](/docs/configuring-a-resource.md) document._**
+   the [Configuring a Resource](/docs/add-new-resource-long.md) document._**
 
 
 8. Now we can generate our Upjet Provider:
@@ -235,7 +235,7 @@ Now let's test our generated resources.
    ```
 
    Create example for `repository` resource, which will use
-   `provider-jet-template` repo as template for the repository
+   `upjet-provider-template` repo as template for the repository
    to be created:
 
    ```bash
@@ -250,7 +250,7 @@ Now let's test our generated resources.
        visibility: public
        template:
          - owner: crossplane-contrib
-           repository: provider-jet-template
+           repository: upjet-provider-template
      providerConfigRef:
        name: default
    EOF
@@ -339,13 +339,11 @@ Now let's test our generated resources.
    plane.
 
 
-[comment]: <> (References)
-
 [Terraform GitHub provider]: https://registry.terraform.io/providers/integrations/github/latest/docs
-[provider-jet-template]: https://github.com/crossplane-contrib/provider-jet-template
+[upjet-provider-template]: https://github.com/upbound/upjet-provider-template
 [upbound/build]: https://github.com/upbound/build
 [Terraform documentation for provider configuration]: https://registry.terraform.io/providers/integrations/github/latest/docs#argument-reference
 [github_repository]: https://registry.terraform.io/providers/integrations/github/latest/docs/resources/repository
 [github_branch]: https://registry.terraform.io/providers/integrations/github/latest/docs/resources/branch
-[this line in controller Dockerfile]: https://github.com/crossplane-contrib/provider-jet-template/blob/d9a793dd8a304f09bb2e9694c47c1bade1b6b057/cluster/images/provider-jet-template-controller/Dockerfile#L18-L25
+[this line in controller Dockerfile]: https://github.com/upbound/upjet-provider-template/blob/main/cluster/images/official-provider-template-controller/Dockerfile#L18-L26
 [terraform-plugin-sdk]: https://github.com/hashicorp/terraform-plugin-sdk