forked from pulumi/examples
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add guidelines and README template for contributing to examples (pulu…
…mi#391) * Guidelines for contributing to the examples repo Signed-off-by: bermudezmt <[email protected]> * Fix casing Signed-off-by: bermudezmt <[email protected]> * Update CONTRIBUTING.md
- Loading branch information
1 parent
a4f8547
commit 69521c8
Showing
2 changed files
with
164 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,71 @@ | ||
# Contributing to Pulumi Examples | ||
|
||
Pulumi welcomes contributions from the community and is excited to continue building out its collection of examples and tutorials that showcase the power of modern infrastructure as code. This guide is intended to | ||
help your contribution get published quickly. | ||
|
||
## Pulumi terminology | ||
|
||
For a list of Pulumi terms used throughout our documentation site, see the [Glossary page](https://www.pulumi.com/docs/reference/glossary/). | ||
|
||
## Example folder structure | ||
|
||
The folder structure for each example includes a two-part prefix, `<cloud>-<language>` (to indicate which `<cloud>` and `<language>` it pertains to), and a brief descriptive name with hyphens in between the words. | ||
|
||
The cloud prefix can be one of: | ||
|
||
- `aws` for [Amazon Web Services](https://github.com/pulumi/pulumi-aws) | ||
- `azure` for [Microsoft Azure](https://github.com/pulumi/pulumi-azure) | ||
- `gcp` for [Google Cloud Platform](https://github.com/pulumi/pulumi-gcp) | ||
- `kubernetes` for [Kubernetes](https://github.com/pulumi/pulumi-kubernetes), | ||
- `digitalocean` for [DigitalOcean](https://github.com/pulumi/pulumi-digitalocean/) | ||
- `f5bigip` for [F5's BIG-IP](https://github.com/pulumi/pulumi-f5bigip/) | ||
- `cloud` for [Pulumi's cross-cloud programming framework](https://github.com/pulumi/pulumi-cloud), which is currently in preview | ||
- Any [cloud provider](https://www.pulumi.com/docs/reference/pkg/#cloud-providers) with a dedicated Pulumi package | ||
|
||
The language prefix can be one of: | ||
- `ts` for TypeScript | ||
- `js` for JavaScript | ||
- `py` for Python | ||
- `go` for Golang | ||
|
||
If you would like to add an example in a different language, see the FAQ section for [adding support for your favorite language](https://www.pulumi.com/docs/troubleshooting/faq/#how-can-i-add-support-for-my-favorite-language). | ||
|
||
Each folder contains files related to your [Pulumi project](https://www.pulumi.com/docs/intro/concepts/project/), a README, an optional directory for your sample application (`www` for example), and an optional `images` directory if you're including images in your example. | ||
|
||
``` | ||
|____README.md | ||
|____www | ||
|____images | ||
| |____deploy.gif | ||
| |____deploy.cast | ||
|____Pulumi.yaml | ||
|____package.json | ||
|____tsconfig.json | ||
|____index.ts | ||
``` | ||
|
||
## Style | ||
|
||
We are big fans of DigitalOcean's [technical writing guidelines](https://www.digitalocean.com/community/tutorials/digitalocean-s-technical-writing-guidelines#style) and highly encourage you to follow their style recommendations. | ||
|
||
### README structure | ||
|
||
Each example should include a README to give the readers a good walkthrough. It should comprise of the following sections: | ||
|
||
- Title | ||
- ["Deploy with Pulumi" button](https://www.pulumi.com/docs/intro/console/extensions/pulumi-button/) (Optional) | ||
- Overview paragraph | ||
- Prerequisites | ||
- Deploy the App | ||
- Step 1 — Doing the First Thing | ||
- Step 2 — Doing the Next Thing | ||
… | ||
- Step n — Doing the Last Thing | ||
- Clean Up | ||
- Summary | ||
- Next Steps (Optional) | ||
|
||
See our [example README template](example-readme-template.md.txt) for detailed explanations on each section. | ||
|
||
> The contribution guidelines have been authored in September 2019 and are subject to further refinements and tweaks. Examples prior to September 2019 do not necessarily conform to these guidelines. | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,93 @@ | ||
<!-- | ||
Use this template as a quick starting point when writing a README for your Pulumi example. To start, copy this file to your example folder and rename it to `README.md`. Once you've reviewed the template, delete the comments and begin writing your accompanying README for your example Pulumi application. | ||
|
||
Use GitHub's "Preview Changes" to make sure everything is formatted correctly in Markdown. | ||
|
||
Readers should be able to follow your example from beginning to end. Please be sure to list all prerequisites, and test your guide from start to finish. Cut and paste commands from the README into your terminal to make sure there aren't typos or inaccuracies. If you find yourself executing a command that isn't in the README, make sure to add it so the readers end up with a complete tutorial. | ||
--> | ||
|
||
|
||
# [App Description] using [Service or Tool] | ||
|
||
<!-- Use Title Case for all Titles --> | ||
<!-- All of the examples are transformed into tutorials on https://www.pulumi.com/docs/tutorials/ and are sorted by cloud and language. There is no need to include the cloud provider name or the language in the title. | ||
|
||
<!-- Our articles have a specific structure. Learn more at CONTRIBUTING.md --> | ||
|
||
Introductory paragraph about the example that explains what problem it solves and why the reader should care. If possible, include use cases. | ||
|
||
In this tutorial, we will [configure/set up/build/deploy] [some thing]... | ||
|
||
When you're finished, you'll be able to... | ||
|
||
## Prerequisites | ||
|
||
<!-- The Prerequisites section includes an ordered list of required installation and configuration steps before the reader can deploy the Pulumi example. --> | ||
|
||
1. [Install Pulumi](https://www.pulumi.com/docs/reference/install/) | ||
1. Configure [cloud] <!-- We have setup pages for our popular cloud providers at https://www.pulumi.com/docs/reference/clouds/<cloud-provider>/setup/ --> | ||
1. Install [language runtime] <!-- We have setup pages for our supported language runtimes at https://www.pulumi.com/docs/intro/languages/<language>/ --> | ||
1. (Optional) List any other accounts needed, such as Twitter, Slack, or other services. | ||
|
||
<!-- Example: | ||
1. [Install Pulumi](https://www.pulumi.com/docs/reference/install/) | ||
2. [Configure your AWS Credentials](https://www.pulumi.com/docs/reference/clouds/aws/setup/) | ||
3. [Install Node.js](https://www.pulumi.com/docs/intro/languages/nodejs/) | ||
--> | ||
|
||
## Deploying the App | ||
|
||
### Step 1: Create a directory and cd into it | ||
|
||
For Pulumi examples, we typically start by creating a directory and changing into it. Then, we create a new Pulumi project from a template. For example, `azure-javascript`. | ||
|
||
First.... | ||
|
||
Next... | ||
|
||
Finally... | ||
|
||
![Alt text for screen readers](/path/to/img.png) | ||
|
||
<!-- | ||
If showing a command, explain the command first by talking about what it does. Then show the command and its output. If the output is too long, you can clip it with `...` and only show the relevant parts. If your README includes images, make sure to include an alt text. | ||
|
||
Now transition to the next step by telling the reader what's next. If you're adding to a file, make sure to clearly explain that. | ||
--> | ||
|
||
|
||
### Step 2: Sentence case | ||
Another introduction | ||
|
||
Your content | ||
|
||
Transition to the next step. | ||
|
||
### Step 3 | ||
|
||
Another introduction | ||
|
||
Your content | ||
|
||
Transition to the next step. | ||
|
||
## Clean Up | ||
|
||
<!--We generally ask the reader to run `pulumi destroy` and tear down the resources to avoid incurring any costs. --> | ||
|
||
|
||
## Summary | ||
|
||
In this article you [configured/set up/built/deployed] [something]. Now you can.... | ||
|
||
<!-- Give a quick recap of what the readers have learned and optionally provide places for further exploration. --> | ||
|
||
## Next Steps | ||
|
||
<!-- Optionally include an unordered list of relevant Pulumi tutorials. --> | ||
|
||
<!-- Example: | ||
- [Create a load-balanced, hosted NGINX container service](https://www.pulumi.com/docs/tutorials/aws/ecs-fargate/) | ||
- [Create an EC2-based WebServer and associated infrastructure](https://www.pulumi.com/docs/tutorials/aws/ec2-webserver/) | ||
--> | ||
|