Skip to content

Commit

Permalink
Add guidelines and README template for contributing to examples (pulu…
Browse files Browse the repository at this point in the history
…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
bermudezmt committed Sep 16, 2019
1 parent a4f8547 commit 69521c8
Show file tree
Hide file tree
Showing 2 changed files with 164 additions and 0 deletions.
71 changes: 71 additions & 0 deletions CONTRIBUTING.md
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.
93 changes: 93 additions & 0 deletions example-readme-template.md.txt
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/)
-->

0 comments on commit 69521c8

Please sign in to comment.