From 9f15e72e5a7cac0a63b5bb421806893fe1b7ca0e Mon Sep 17 00:00:00 2001 From: Misty Stanley-Jones Date: Tue, 8 Nov 2016 13:24:39 -0800 Subject: [PATCH] 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 * Move YAML file, symlink it in the root Signed-off-by: Misty Stanley-Jones --- .NOT_EDITED_HERE.txt | 31 -------------------- .NOT_EDITED_HERE.yaml | 1 + .github/CONTRIBUTING.md | 50 ++++++++++++++++++++++++++++---- .github/PULL_REQUEST_TEMPLATE.md | 20 +++++-------- README.md | 19 +++++++++++- _data/.NOT_EDITED_HERE.yaml | 38 ++++++++++++++++++++++++ 6 files changed, 110 insertions(+), 49 deletions(-) delete mode 100644 .NOT_EDITED_HERE.txt create mode 120000 .NOT_EDITED_HERE.yaml create mode 100644 _data/.NOT_EDITED_HERE.yaml diff --git a/.NOT_EDITED_HERE.txt b/.NOT_EDITED_HERE.txt deleted file mode 100644 index 12164aede5..0000000000 --- a/.NOT_EDITED_HERE.txt +++ /dev/null @@ -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/ diff --git a/.NOT_EDITED_HERE.yaml b/.NOT_EDITED_HERE.yaml new file mode 120000 index 0000000000..6e88801400 --- /dev/null +++ b/.NOT_EDITED_HERE.yaml @@ -0,0 +1 @@ +_data/.NOT_EDITED_HERE.yaml \ No newline at end of file diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index ff1073d9e9..b6d84c2b56 100644 --- a/.github/CONTRIBUTING.md +++ b/.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 -the [style guide](https://docs.docker.com/opensource/doc-style/). The style guide provides -guidance about grammar, syntax, formatting, styling, language, or tone. If -something isn't clear in the guide, please submit an issue to let us know or -submit a pull request to help us improve it. +If you have questions about how to write for Docker's documentation, have a look +at the [style guide](https://docs.docker.com/opensource/doc-style/). The style +guide provides guidance about grammar, syntax, formatting, styling, language, or +tone. If something isn't clear in the guide, please submit an issue to let us +know or submit a pull request to help us improve it. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 403812517b..ae767832e8 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,33 +1,29 @@ - ### Describe the proposed changes - + -### Project version +### Unreleased project version - + ### Related issue - + ### Related issue or PR in another project - + ### Please take a look - + diff --git a/README.md b/README.md index c61b8ab3eb..d088da406a 100644 --- a/README.md +++ b/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: diff --git a/_data/.NOT_EDITED_HERE.yaml b/_data/.NOT_EDITED_HERE.yaml new file mode 100644 index 0000000000..65fbbfca1f --- /dev/null +++ b/_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/