started contribution guide (ampproject#2281)

* started contribution guide * Addressed Matthias's comments * addressed comments
getzaymo · Jun 7, 2019 · d5f82ea · d5f82ea
1 parent 1e45f61
commit d5f82ea
Show file tree

Hide file tree

Showing 3 changed files with 279 additions and 8 deletions.
diff --git a/README.md b/README.md
@@ -2,11 +2,23 @@
 
 [![Build Status](https://travis-ci.org/ampproject/docs.svg?branch=future)](https://travis-ci.org/ampproject/docs)
 
-This repository is meant to work towards the relaunch of the official website
-of [ampproject.org](https://www.ampproject.org/) until we reach a progress
-that makes a merge over to the original repository beneficial.
+The official homepage of the AMP Project.
 
-## Requirements
+## Contributing
+
+We welcome contributons to amp.dev.
+
+* **Bug reports and feature requests:** something missing or not working on https://amp.dev? Please file an issue [here](https://github.com/ampproject/docs/issues/new).
+* **Documentation & Guides:** see [this guide](./contributing/documentation.md) for more information on how to contribute documentation to amp.dev.
+* **Code samples & demos:** see [this guide](./contributing/samples.md) for more information on how to contribute sample code to amp.dev.
+
+**Note:** fixing spelling mistakes and other small changes are often easiest by directly editing a file on Github.
+
+<img width="669" alt="Inline editing on Github" src="https://user-images.githubusercontent.com/380472/59018008-2d8f5580-8845-11e9-8160-e2890e2c7944.png">
+
+## Setup
+
+### Requirements
 
 1.  Install the LTS version of [NodeJS](https://nodejs.org). An easy way to do so is with `nvm`. (Mac and Linux: [here](https://github.com/creationix/nvm), Windows: [here](https://github.com/coreybutler/nvm-windows))
     ```sh
@@ -23,7 +35,8 @@ that makes a merge over to the original repository beneficial.
     $ npm install
     ```
 
-## Develop
+### Develop
+
 If it's your first time working on amp.dev it is recommended to bootstrap your local environment. To do so make sure you have setup a valid [GitHub access token](https://github.com/settings/tokens) in an environment variable named `AMP_DOC_TOKEN` like:
 
 ```sh
@@ -49,8 +62,6 @@ This command prints a lot to the shell and will most probably end on `Server rea
 #### Documents
 Made changes to a lot of Grow documents at once and not quite sure if all references are still valid? You can run `npm run lint:grow` to pick up broken ones.
 
-Also see MAINTENANCE.md for a more detailed explanation of the various frontmatter keys used throughout the project.
-
 #### Samples
 Building the samples creates a lot of individual files per sample. In order to still have a quick startup time for development only changed samples are rebuilt. To freshly build *all* samples you can run `gulp develop --clean-samples`.
 

diff --git a/MAINTENANCE.md → contributing/documentation.md b/MAINTENANCE.md → contributing/documentation.md
@@ -1,4 +1,5 @@
-# Maintenance
+# Writing documentation and guides
+
 This document holds all the information that is relevant to maintain and contribute the content for each if its packages.
 
 ## Collections

diff --git a/contributing/samples.md b/contributing/samples.md
@@ -0,0 +1,259 @@
+## Creating a new sample
+
+Samples live in `examples/source`. Pick one of the existing category folders. 
+
+If your sample can live in a single html file, create a new `*.html` in  one of the sample category folders:
+
+```shell
+$ vim examples/source/1.components/amp-awesome.html
+```
+
+If your sample requires a custom backend API, create a new folder which is going to contain both, your sample html file, which must be named `index.html` and your api implementation `api.js`.
+
+```shell
+$ mkdir examples/source/1.components/amp-awesome
+$ vim examples/source/1.components/amp-awesome/index.html
+$ vim examples/source/1.components/amp-awesome/api.js
+```
+
+If your sample, does not fit into one of the existing categories, please [create an issue](https://github.com/ampproject/docs/issues/new) first and ask for feedback.
+
+[Here is a sample template](https://gist.github.com/sebastianbenz/45d3dae499f35dedb65e01546356ff7a) you can use to get started. 
+
+## Frontmatter
+
+Samples can define additional metadata (such as author name or supported AMP formats) via a YAML frontmatter. Here is a template to get you started:
+
+```
+<!---
+- author: your-github-user-name
+- formats
+  - websites
+--->
+```
+
+**Note the triple dash `<!---`!**. Also make sure to list all supported formats (websites,ads,email,stories).
+
+You must list all the supported AMP formats for your sample. If your sample is specific AMP format, define that single format.
+
+```
+- formats
+  - email
+```
+
+Please list all experimental components that your sample uses:
+
+```
+experiments:
+  - amp-autocomplete
+```
+
+Other supported flags are:
+
+```yaml
+- formats # [default: websites,ads,email,stories]:
+  - websites
+  - ads
+  - email
+  - stories
+- validAmp # [default: true]
+  - true
+  - false
+- draft # [default: true]
+  - true
+  - false
+- tags # [default: '']
+  - ads-analytics
+  - dynamic-content
+  - layout
+  - media
+  - presentation
+  - social
+  - personalization
+```
+
+## Writing the sample
+
+Add documentation to your sample's code by wrapping text in HTML comments:
+
+```html
+<!-- Look! Images in AMP. -->
+<amp-img src="img/image1.jpg" width="200" height="100" layout="responsive"></amp-img>
+```
+
+This works for elements in the header as well:
+
+```html
+<head>
+  <!-- Import the amp-youtube component -->
+  <script async custom-element="amp-youtube" src="https://cdn.ampproject.org/v0/amp-youtube-0.1.js"></script>
+  ...
+</head>
+```
+
+Every HTML comment creates a separate example section spanning the following HTML element.
+
+```html
+<!-- This comment spans the whole following section including the two images -->
+<section>
+  <amp-img src="img/image1.jpg" width="200" height="100" layout="responsive"></amp-img>
+  <amp-img src="img/image2.jpg" width="200" height="100" layout="responsive"></amp-img>
+</section>
+```
+
+Nesting comments are not supported:
+
+```html
+<!-- A comment -->
+<div>
+  <!-- This does not work because the parent div has already a comment -->
+  <amp-img src="img/image1.jpg" width="200" height="100" layout="responsive"></amp-img>
+</div>
+<div>
+  <!-- Commenting inside nested tags works though -->
+  <amp-img src="img/image1.jpg" width="200" height="100" layout="responsive"></amp-img>
+</div>
+```
+
+If your comment spans multiple elements, wrap these in an single `div` without any attributes. The enclosing `div` tag will be hidden in source code listings:
+
+```html
+<!-- The enclosing `div` will be hidden in source code listings. -->
+<div>
+  <button on="tap:my-lightbox" role="button" tabindex="0">Open lightbox</button>
+  <amp-lightbox id="my-lightbox" layout="nodisplay">
+    <h1>Hello World!</h1>
+  </amp-lightbox>
+</div>
+```
+
+#### Sample Styling
+
+Sometimes it's good to add a little bit more styling to a sample (e.g. to separate a button from an input field). To make sure that all samples have a consistent styling, please use the following CSS variables to style specific elements in your sample:
+
+```
+:root {
+  --color-primary: #005AF0;
+  --color-secondary: #00DCC0;
+  --color-text-light: #fff;
+  --color-text-dark: #000;
+  --color-error: #B00020;
+  --color-bg-light: #FAFAFC;
+
+  --space-1: .5rem;  /* 8px */
+  --space-2: 1rem;   /* 16px */
+  --space-3: 1.5rem; /* 24px */
+  --space-4: 2rem;   /* 32px */
+
+  --box-shadow-1: 0 1px 1px 0 rgba(0,0,0,.14), 0 1px 1px -1px rgba(0,0,0,.14), 0 1px 5px 0 rgba(0,0,0,.12);
+}
+```
+
+You can use them to style your samples like this:
+
+```
+.button {
+  margin: var(--space-2);
+  padding: var(--space-1);
+  background-color: var(--color-primary);
+  color: var(--color-text-light);
+}
+```
+
+Only add the ones that you need to the sample. These CSS variable declarations will be added automatically to your sample, if you use `gulp create ...` to create the sample.
+
+**Colors**
+
+<img width="743" alt="screenshot 2018-11-30 at 00 22 57" src="https://user-images.githubusercontent.com/380472/49258635-6aae0180-f436-11e8-8ca0-2210fd4c0a96.png">
+
+**Spaces**
+
+<img width="643" alt="screenshot 2018-11-30 at 00 23 08" src="https://user-images.githubusercontent.com/380472/49258634-6aae0180-f436-11e8-9716-50c69970c113.png">
+
+#### Formatting
+
+You can use [markdown](https://help.github.com/articles/github-flavored-markdown/) to format your documentation:
+
+```html
+<!--
+  A simple [responsive](https://www.ampproject.org/docs/guides/responsive/control_layout.html)
+  image - *width* and *height* are used to determine the aspect ratio.
+-->
+<amp-img src="img/image1.jpg" width="200" height="100" layout="responsive"></amp-img>
+```
+
+#### Notes, Warnings & Tips
+
+There's a special markup available for callouts:
+
+```
+[tip type="default|important|note|read-on"]
+Tip!
+[/tip]
+```
+
+For example:
+
+```
+[tip type="important"]
+Warning! This might go wrong.
+[/tip]
+```
+
+#### Hints
+
+If you'd like to add additional information about a single element inside a section, use the `<!--~ hint syntax ~-->`:
+
+```html
+<!-- A comment about the form. -->
+<form method="post"
+  action-xhr="https://example.com/subscribe"
+  target="_top">
+  <fieldset>
+    <input type="text" name="username">
+
+    <!--~ Addition explanation about the hidden field. ~-->
+    <input type="hidden" name="id" value="abc">
+  </fieldset>
+</form>
+```
+
+This will make the `<input>` element clickable, with the additional explanation appearing on click.
+
+### Adding backend functionality
+
+Before writing your own API endpoint, please take a look at the [existing generic API endpoints](https://github.com/ampproject/docs/tree/future/examples/api), maybe you can re-use one of them.
+
+Sample specific backend endpoints live in a JS file inside the sample folder. They are implemented via [Express routing](https://expressjs.com/en/guide/routing.html). You can address your API endpoints relative to your sample location, e.g. `<amp-list src="you-api-route' ...>`.
+
+Here is a template to get you started. 
+
+```
+/**
+ * Copyright 2019 The AMP HTML Authors. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS-IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+'use strict';
+
+const express = require('express');
+
+// eslint-disable-next-line new-cap
+const examples = express.Router();
+
+examples.get('/echo', (request, response) => {
+  response.json(request.query);
+});
+
+module.exports = examples;
+```