mirror of https://github.com/docker/docs.git
chore: update contribution guidelines
Moves most of the contribution guidelines to the well-known CONTRIBUTING.md file Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
This commit is contained in:
David Karlsson
parent
e75dfd58ec
commit
49f14f795c
113
CONTRIBUTING.md
113
CONTRIBUTING.md
|
|
@ -1,6 +1,113 @@
|
|||
# Contributing to Docker Documentation
|
||||
|
||||
We deeply value documentation contributions from the Docker community. We'd like to make it as easy
|
||||
as possible for you to work in this repository.
|
||||
We value documentation contributions from the Docker community. We'd like to
|
||||
make it as easy as possible for you to work in this repository.
|
||||
|
||||
We have created a ['Contribute' section](https://docs.docker.com/contribute/overview/) in our docs which guides you through the process of contributing to Docker documentation.
|
||||
Our style guide and instructions on using our page templates and components is
|
||||
available in the [contribution section](https://docs.docker.com/contribute/) on
|
||||
the website.
|
||||
|
||||
The following guidelines describe the ways in which you can contribute to the
|
||||
Docker documentation at <https://docs.docker.com/>, and how to get started.
|
||||
|
||||
## Reporting issues
|
||||
|
||||
If you encounter a problem with the content, or the site in general, feel free
|
||||
to [submit an issue](https://github.com/docker/docs/issues/new/choose) in our
|
||||
[GitHub issue tracker](https://github.com/docker/docs/issues). You can also use
|
||||
the issue tracker to raise requests on improvements, or suggest new content
|
||||
that you think is missing or that you would like to see.
|
||||
|
||||
## Editing content
|
||||
|
||||
The website is built using [Hugo](https://gohugo.io/). The content is primarily
|
||||
Markdown files in the `/content` directory of this repository (with a few
|
||||
exceptions, see [Content not edited here](#content-not-edited-here)).
|
||||
|
||||
The structure of the sidebar navigation on the site is defined in
|
||||
[`/data/toc.yaml`](./data/toc.yaml). To rename or change the location of a page
|
||||
in the left-hand navigation, edit the `toc.yaml` file.
|
||||
|
||||
You can edit the files directly on GitHub using the web editor, or
|
||||
[locally](#local-setup), whichever way you prefer.
|
||||
|
||||
### General guidelines
|
||||
|
||||
Help make reviewing easier 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 aren't
|
||||
editing for other reasons. Make sure your text editor isn't configured to
|
||||
automatically reformat the whole file when saving.
|
||||
- We use GitHub Actions for testing and creating preview deployments for each
|
||||
pull request. The URL of the preview deployment is added as a comment on the
|
||||
pull request. Check the staging site to verify how your changes look and fix
|
||||
issues, if necessary.
|
||||
|
||||
### Local setup
|
||||
|
||||
You can use Docker (surprise) to build and serve the files locally. This
|
||||
requires Docker Desktop version 4.24 or later, or Docker Engine with Docker
|
||||
Compose version 2.22 or later.
|
||||
|
||||
1. Clone the repository:
|
||||
|
||||
```console
|
||||
$ git clone git@github.com:docker/docs.git
|
||||
$ cd docs
|
||||
```
|
||||
|
||||
2. Check out a branch:
|
||||
|
||||
```console
|
||||
$ git checkout -b <branch>
|
||||
```
|
||||
|
||||
3. Start the local development server:
|
||||
|
||||
```console
|
||||
$ docker compose watch
|
||||
```
|
||||
|
||||
The site will be served for local preview at <http://localhost:1313>. The
|
||||
development server watches for changes and automatically rebuilds your site.
|
||||
|
||||
To stop the development server:
|
||||
|
||||
1. In your terminal, press `<Ctrl+C>` to exit the file watch mode of Compose.
|
||||
2. Stop the Compose service with the `docker compose down` command.
|
||||
|
||||
### Testing
|
||||
|
||||
Before you push your changes and open a pull request, we recommend that you
|
||||
test your site locally first. Local tests check for broken links, incorrectly
|
||||
formatted markup, and other things. To run the tests:
|
||||
|
||||
```console
|
||||
$ docker build bake validate
|
||||
```
|
||||
|
||||
If this command doesn't result in any errors, you're good to go!
|
||||
|
||||
## Content not edited here
|
||||
|
||||
CLI reference documentation is maintained in upstream repositories. It's
|
||||
partially generated from code, and is only vendored here for publishing. To
|
||||
update the CLI reference docs, refer to the corresponding repository:
|
||||
|
||||
- [docker/cli](https://github.com/docker/cli)
|
||||
- [docker/buildx](https://github.com/docker/buildx)
|
||||
- [docker/compose](https://github.com/docker/compose)
|
||||
|
||||
Feel free to raise an issue on this repository if you're not sure how to
|
||||
proceed, and we'll help out.
|
||||
|
||||
Other content that appears on the site, but that's not edited here, includes:
|
||||
|
||||
- Dockerfile reference
|
||||
- Docker Engine API reference
|
||||
- Compose specification
|
||||
- Buildx Bake reference
|
||||
|
||||
If you spot an issue in any of these pages, feel free to raise an issue here
|
||||
and we'll make sure it gets fixed in the upstream source.
|
||||
|
|
|
|||
|
|
@ -45,7 +45,7 @@ We've made it easy for you to file new issues.
|
|||
We value your contribution. We want to make it as easy as possible to submit
|
||||
your contributions to the Docker docs repository. Changes to the docs are
|
||||
handled through pull requests against the `main` branch. To learn how to
|
||||
contribute, see our [Contribute section](https://docs.docker.com/contribute/overview/).
|
||||
contribute, see [CONTRIBUTING.md](CONTRIBUTING.md).
|
||||
|
||||
## Copyright and license
|
||||
|
||||
|
|
|
|||
|
|
@ -145,11 +145,13 @@ This pattern can be followed for many languages and frameworks, such as Python w
|
|||
2. Run `docker compose watch` to build and launch a Compose project and start the file watch mode.
|
||||
3. Edit service source files using your preferred IDE or editor.
|
||||
|
||||
>**Looking for a sample project to test things out?**
|
||||
> **Looking for a sample project to test things out?**
|
||||
>
|
||||
> Check out [`dockersamples/avatars`](https://github.com/dockersamples/avatars), or [build the docs site locally](../contribute/contribute-guide.md#build-and-preview-the-docs-locally) for a demonstration of Compose `watch`.
|
||||
> Check out [`dockersamples/avatars`](https://github.com/dockersamples/avatars),
|
||||
> or [local setup for Docker docs](https://github.com/docker/docs/blob/main/CONTRIBUTING.md)
|
||||
> for a demonstration of Compose `watch`.
|
||||
{ .tip }
|
||||
|
||||
## Feedback
|
||||
|
||||
We are actively looking for feedback on this feature. Give feedback or report any bugs you may find in the [Compose Specification repository](https://github.com/compose-spec/compose-spec/pull/253).
|
||||
We are actively looking for feedback on this feature. Give feedback or report any bugs you may find in the [Compose Specification repository](https://github.com/compose-spec/compose-spec/pull/253).
|
||||
|
|
|
|||
|
|
@ -2,13 +2,10 @@
|
|||
title: Contribute to Docker's docs
|
||||
toc_max: 1
|
||||
aliases:
|
||||
- /CONTRIBUTING/
|
||||
- /opensource/
|
||||
- /contribute/overview/
|
||||
- /contribute/contribute-guide/
|
||||
grid:
|
||||
- title: Contribution guidelines
|
||||
description: Learn about the process of contributing to our docs.
|
||||
icon: description
|
||||
link: /contribute/contribute-guide
|
||||
- title: Grammar and style
|
||||
description: Explore Docker's grammar and style guide
|
||||
icon: menu_book
|
||||
|
|
@ -29,18 +26,26 @@ grid:
|
|||
description: Explore commonly used Docker terms.
|
||||
icon: spellcheck
|
||||
link: /contribute/style/terminology
|
||||
- title: Voice and tone
|
||||
description: Learn about how we use voice and tone in our writing.
|
||||
icon: voice_selection
|
||||
link: /contribute/style/voice-tone
|
||||
---
|
||||
|
||||
We deeply value documentation contributions from the Docker community. We'd like to make it as easy
|
||||
as possible for you to work in this repository. The following sections guide you through the process of contributing to Docker documentation.
|
||||
We value documentation contributions from the Docker community. We'd like to
|
||||
make it as easy as possible for you to contribute to the Docker documentation.
|
||||
|
||||
Find the contribution guidelines in
|
||||
[CONTRIBUTING.md](https://github.com/docker/docs/blob/main/CONTRIBUTING.md) in
|
||||
the `docker/docs` GitHub repository. Use the following links to review our
|
||||
style guide and instructions on how to use our page templates and components.
|
||||
|
||||
{{< grid >}}
|
||||
|
||||
### Additional resources
|
||||
|
||||
We also provide:
|
||||
See also:
|
||||
|
||||
- A section of useful components you can add to your documentation.
|
||||
- Information on Docker's [tone and voice](style/voice-tone.md).
|
||||
- A [writing checklist](checklist.md) to help you when you're contributing to Docker's documentation.
|
||||
- A command-line tool called vale to check the style and [help you find errors in your writing](contribute-guide.md#test-the-docs-locally).
|
||||
|
|
@ -14,7 +14,7 @@ toc_max: 3
|
|||
|
||||
You can also make a badge a link.
|
||||
|
||||
[{{< badge color="blue" text="badge with a link" >}}](../overview.md)
|
||||
[{{< badge color="blue" text="badge with a link" >}}](../_index.md)
|
||||
|
||||
### Markup
|
||||
|
||||
|
|
|
|||
|
|
@ -1,119 +0,0 @@
|
|||
---
|
||||
title: Contributing guidelines
|
||||
description: Guidelines for contributing to Docker's docs
|
||||
keywords: contribute, guide, style guide
|
||||
---
|
||||
|
||||
The live docs are published from the `main` branch. Therefore, you must create pull requests against the `main` branch for all content updates. This includes:
|
||||
|
||||
- Conceptual and task-based information
|
||||
- Restructuring / rewriting
|
||||
- Doc bug fixing
|
||||
- Fixing typos, broken links, and any grammar errors
|
||||
|
||||
There are two ways to contribute a pull request to the docs repository:
|
||||
|
||||
1. You can select the **Edit this page** option in the right column of every page on [https://docs.docker.com/](/).
|
||||
|
||||
This opens the GitHub editor, which means you don't need to know a lot about Git, or even about Markdown. When you save, GitHub prompts you to create a fork if you don't already have one, and to create a branch in your fork and submit the pull request.
|
||||
|
||||
<!-- markdownlint-disable-next-line -->
|
||||
2. Fork the [docs GitHub repository]({{% param "repo" %}}). Suggest changes or add new content on your local branch, and submit a pull request (PR) to the `main` branch.
|
||||
|
||||
This is the manual, more advanced version of selecting 'Edit this page' on a published docs page. Initiating a docs change in a PR from your own branch gives you more flexibility, as you can submit changes to multiple pages or files under a single pull request, and even create new topics.
|
||||
|
||||
For a demo of the components, tags, Markdown syntax, styles, etc. used in [https://docs.docker.com/](/), see the components section.
|
||||
|
||||
## Important files
|
||||
|
||||
Here’s a list of some of the important files:
|
||||
|
||||
- `/content` contains all the pages. The site uses filesystem-based routing, so the filepath of the source files correspond to the url subpath.
|
||||
- `/data/toc.yaml` defines the left-hand navigation for the docs.
|
||||
- `/layouts` contains the html templates used to generate the HTML pages.
|
||||
|
||||
CLI reference documentation is generated from code, and is not maintained in
|
||||
this repository. (They're only vendored here, either manually in `/data` or
|
||||
automatically in `/_vendor`.) To update CLI reference docs, refer to the
|
||||
corresponding repository containing the CLI source code.
|
||||
|
||||
## 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 aren't editing for other reasons. Make sure your text editor isn't configured to
|
||||
automatically reformat the whole file when saving.
|
||||
- We highly recommend that you [build](#build-and-preview-the-docs-locally) and [test](#test-the-docs-locally) the docs locally before submitting a PR.
|
||||
- A Netlify test runs for each PR that is against the `main` branch, and deploys the result of your PR to a staging site. The URL will be available in the **Conversation** tab. Check the staging site to verify how your changes look and fix issues, if necessary.
|
||||
|
||||
### 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 into the `main` branch. In some scenarios where a squash and merge isn't appropriate, all commits are kept separate when merging.
|
||||
|
||||
### Per-PR staging on GitHub
|
||||
|
||||
A Netlify test runs for each PR created against the `main` branch and deploys the result of your PR to a staging site. When the site builds successfully, you will see a comment in the **Conversation** tab in the PR stating **Deploy Preview for docsdocker ready!**. Click the **Browse the preview** URL and check the staging site to verify how your changes look and fix issues, if necessary. Reviewers also check the staged site before merging the PR to protect the integrity of the docs site.
|
||||
|
||||
## Build and preview the docs locally
|
||||
|
||||
On your local machine, clone the docs repository:
|
||||
|
||||
```console
|
||||
$ git clone {{% param "repo" %}}.git
|
||||
$ cd docs
|
||||
```
|
||||
|
||||
Then, build and run the documentation using [Docker Compose](../compose/_index.md):
|
||||
|
||||
```console
|
||||
$ docker compose watch
|
||||
```
|
||||
|
||||
> **Note**
|
||||
>
|
||||
>You need Docker Compose to build and run the docs locally. Docker Compose is included with [Docker Desktop](../desktop/_index.md). If you don't have Docker Desktop installed, follow the [instructions](../compose/install/index.md) to install Docker Compose.
|
||||
|
||||
When the container is built and running, visit [http://localhost:1313](http://localhost:1313) in your web browser to view the docs.
|
||||
|
||||
[Compose `watch`](../compose/file-watch.md) causes your
|
||||
running container to rebuild itself automatically when you make changes to your
|
||||
content files.
|
||||
|
||||
To stop the development container:
|
||||
|
||||
1. In your terminal, press `<Ctrl+C>` to exit the file watch mode of Compose.
|
||||
2. Stop the Compose services with the `docker compose down` command.
|
||||
|
||||
### Test the docs locally
|
||||
|
||||
For testing the documentation, we use:
|
||||
- a command-line tool called [vale](https://vale.sh/) to check the style and help you find errors in your writing.
|
||||
- [wjdp/htmltest](https://github.com/wjdp/htmltest) for proofing HTML markup and checking for broken links
|
||||
|
||||
You can use Buildx to run all the tests locally before you create your pull
|
||||
request:
|
||||
|
||||
```console
|
||||
$ docker buildx bake validate
|
||||
```
|
||||
|
||||
You can also integrate `vale` with your text editor to get real-time feedback
|
||||
on your writing. Refer to the relevant plugin for your editor:
|
||||
|
||||
- [VS Code](https://github.com/chrischinchilla/vale-vscode)
|
||||
- [Neovim](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#vale_ls)
|
||||
- [Emacs](https://github.com/tpeacock19/flymake-vale)
|
||||
- [Jetbrains](https://vale.sh/docs/integrations/jetbrains/)
|
||||
- [Sublime Text](https://github.com/errata-ai/LSP-vale-ls)
|
||||
|
||||
The `vale` rules that implement the Docker style guide are included in the
|
||||
Docker docs repository, in the `.github/vale` directory.
|
||||
|
|
@ -192,10 +192,8 @@ Guides:
|
|||
|
||||
- sectiontitle: Contribute
|
||||
section:
|
||||
- path: /contribute/overview/
|
||||
- path: /contribute/
|
||||
title: Contribute to Docker's docs
|
||||
- path: /contribute/contribute-guide/
|
||||
title: Contribution guidelines
|
||||
- sectiontitle: Style guide
|
||||
section:
|
||||
- path: /contribute/style/grammar/
|
||||
|
|
|
|||
Loading…
Reference in New Issue