Add info about Netlify, convert .NOT_EDITED_HERE to YAML, other improvements (#485)

* Add info about Netlify, convert .NOT_EDITED_HERE to YAML, other misc improvements

Signed-off-by: Misty Stanley-Jones <misty@docker.com>

* Move YAML file, symlink it in the root

Signed-off-by: Misty Stanley-Jones <misty@docker.com>

.NOT_EDITED_HERE.txt

@@ -1,31 +0,0 @@
-# Files and directories here are not edited in the docker.github.io repo.
-# Instead, they are edited in the appropriate upstream repo and pulled
-# into this repo periodically. The intent is that if you submit a PR
-# with changes to these files or directories, a CI job will fail in the
-# PR, indicating that it should not be merged.
-
-# If you need to edit these files or directories, submit a PR in one of the
-# following repos. The file will probably be located within the docs/ subdirectory.
-
-# docker-trusted-registry:                 n/a, file an issue
-# engine:                                  https://github.com/docker/docker
-# compose:                                 https://github.com/docker/compose
-# notary:                                  https://github.com/docker/notary
-# registry:                                https://github.com/docker/distribution
-# swarm:                                   https://github.com/docker/swarm
-# ucp:                                     n/a, file an issue
-
-# Make sure directories have the trailing slash, keep the list alphabetical
-
-apidocs/
-compose/reference/
-docker-trusted-registry/reference/
-engine/deprecated.md
-engine/extend/
-engine/reference/
-machine/reference/
-notary/reference/
-registry/configuration.md
-registry/spec/
-swarm/reference/
-ucp/reference/

.NOT_EDITED_HERE.yaml

@@ -0,0 +1 @@
+_data/.NOT_EDITED_HERE.yaml

.github/CONTRIBUTING.md

@@ -9,6 +9,14 @@ let you know so that you can rebase it.
 >**Note**: To contribute code to Docker projects, see the
 [Contribution guidelines](opensource/project/who-written-for).
 
+### Files not edited here
+
+Files and directories listed in the `path:` keys in
+[`.NOT_EDITED_HERE.yaml`](/NOT_EDITED_HERE.yaml) are maintained in other
+repositories and should not be edited in this one. Pull requests against these
+files will be rejected. Make your edits to the files in the repository and path
+in the `source:` key in the YAML file.
+
 ### Quickstart
 
 If you spot a problem while reading the documentation and want to try to fix it
@@ -79,10 +87,42 @@ The following `vnext` branches currently exist:
   docs for upcoming features in the [docker/kitematic](https://github.com/docker/kitematic/)
   project
 
+## Collaborate on a pull request
+
+Unless the PR author specifically disables it, you can push commits into another
+contributor's PR. You can do it from the command line by adding and fetching
+their remote, checking out their branch, and adding commits to it. Even easier,
+you can add commits from the Github web UI, by clicking the pencil icon for a
+given file in the **Files** view.
+
+If a PR consists of multiple small addendum commits on top of a more significant
+one, the commit will usually be "squash-merged", so that only one commit is
+merged in. On occasion this is not appropriate and all commits will be kept
+separate when merging.
+
+## Pull request guidelines
+
+Help us review your PRs more quickly by following these guidelines.
+
+- Try not to touch a large number of files in a single PR if possible.
+
+- Don't change whitespace or line wrapping in parts of a file you are not
+  editing for other reasons. Make sure your text editor is not configured to
+  automatically reformat the whole file when saving.
+
+- A Netlify test runs for each PR that is against one of our long-lived
+  branches like `master` and the `vnext` branches, and deploys the result of
+  your PR to a staging site. The URL will be available at the bottom of the PR
+  in the **Conversation** view. Check the staging site for problems and fix them
+  if necessary. Reviewers will check the staging site too.
+
+If you can think of other ways we could streamline the review process, let us
+know.
+
 ## Style guide
 
-If you have questions about how to write for Docker's documentation, please see
+If you have questions about how to write for Docker's documentation, have a look
-the [style guide](https://docs.docker.com/opensource/doc-style/). The style guide provides
+at the [style guide](https://docs.docker.com/opensource/doc-style/). The style
-guidance about grammar, syntax, formatting, styling, language, or tone. If
+guide provides guidance about grammar, syntax, formatting, styling, language, or
-something isn't clear in the guide, please submit an issue to let us know or
+tone. If something isn't clear in the guide, please submit an issue to let us
-submit a pull request to help us improve it.
+know or submit a pull request to help us improve it.

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,33 +1,29 @@
 <!--Thanks for your contribution. See [CONTRIBUTING](CONTRIBUTING.md)
     for this project's contribution guidelines. -->
 
-<!--DO NOT edit files and directories listed in .NOT_EDITED_HERE.txt.
+<!--DO NOT edit files and directories listed in .NOT_EDITED_HERE.yaml.
     These are maintained in upstream repos and changes here will be lost.-->
 
 ### Describe the proposed changes
 
-<!-- Tell us what you did and why. You can leave this off if the PR title
+<!-- Tell us what you did and why.-->
-     is descriptive. The commit message will be added to the end of this form.-->
 
-### Project version
+### Unreleased project version
 
-<!-- If this change only applies to a future version of a project (like
+<!-- If this change only applies to an unreleased version of a project, note
-     Docker Engine 1.13), note that here and base your work on the `vnext-`
+     that here and base your work on the `vnext-` branch for your project. -->
-     branch for your project. -->
 
 ### Related issue
 
-<!-- If this relates to an issue or PR in this repo, refer to it like
+<!-- Refer to related PRs or issues: #1234, or 'Fixes #1234' or 'Closes #1234'. -->
-     #1234, or 'Fixes #1234' or 'Closes #1234'. -->
 
 ### Related issue or PR in another project
 
-<!-- Links to issues or pull requests in other repositories if applicable. -->
+<!-- Full URLs to issues or pull requests in other Github projects -->
 
 ### Please take a look
 
-<!-- At-mention specific individuals or groups who should take a
+<!-- At-mention specific individuals or groups, like @exampleuser123 -->
-     look at this PR. For instance, @exampleuser123 -->
 
 
 <!-- To improve this template, edit .github/PULL_REQUEST_TEMPLATE.md. -->

README.md

@@ -34,6 +34,14 @@ let you know so that you can rebase it.
 >**Note**: To contribute code to Docker projects, see the
 [Contribution guidelines](opensource/project/who-written-for).
 
+### Files not edited here
+
+Files and directories listed in the `path:` keys in
+[`.NOT_EDITED_HERE.yaml`](.NOT_EDITED_HERE.yaml) are maintained in other
+repositories and should not be edited in this one. Pull requests against these
+files will be rejected. Make your edits to the files in the repository and path
+in the `source:` key in the YAML file.
+
 ### Overall doc improvements
 
 Most commits will be made against the `master` branch. This include:
@@ -93,8 +101,17 @@ The following `vnext` branches currently exist:
   docs for upcoming features in the [docker/kitematic](https://github.com/docker/kitematic/)
   project
 
+## Per-PR staging on Github
 
-## Staging
+For every PR against `master` and all the long-lived branches, a staged version
+of the site is built using Netlify. If the site builds, you will see
+**deploy/netlify — Deploy preview ready**. Otherwise, you will see an error.
+Click **Details** to review the staged site or the errors that prevented it from
+building. Review the staged site and amend your commit if necessary. Reviewers
+will also check the staged site before merging the PR, to protect the integrity
+of [docs.docker.com](http://docs.docker.com/).
+
+## Staging locally
 
 You have three options:
 

_data/.NOT_EDITED_HERE.yaml

@@ -0,0 +1,38 @@
+# Files and directories here are not edited in the docker.github.io repo.
+# Instead, they are edited in the appropriate upstream repo and pulled
+# into this repo periodically, or they are automatically generated. The intent
+# is that if you submit a PR with changes to these files or directories, a CI
+# job will fail in the PR, indicating that it should not be merged. THIS IS NOT
+# YET IMPLEMENTED!! The PR reviewer should make sure no files here are in the PR.
+
+# If you need to edit these files or directories, submit a PR in the repo and
+# directory listed in "source" below.
+
+# Make sure directories have the trailing slash, keep the list alphabetical
+
+- path: apidocs/
+  description: "Auto-generated API docs for Docker Cloud, DTR, UCP. File an issue."
+
+- path: engine/deprecated.md
+  description: Docker Engine deprecation reference
+  source: https://github.com/docker/docker/docs/deprecated.md
+
+- path: engine/extend/
+  description: References for Docker Engine plugin system
+  source: https://github.com/docker/docker/docs/extend/
+
+- path: engine/reference/
+  description: Docker Engine CLI and API references
+  source: https://github.com/docker/docker/docs/reference/
+
+- path: notary/reference/
+  description: Reference docs for Docker Notary
+  source: https://github.com/docker/notary/docs/reference/
+
+- path: registry/configuration.md
+  description: Reference docs for configuring Docker Registry
+  source: https://github.com/docker/distribution/docs/configuration.md
+
+- path: registry/spec/
+  description: Docker Registry API references
+  source: https://github.com/docker/distribution/docs/spec/