dapr
/
docs
mirror of https://github.com/dapr/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Updating contributing section

This commit is contained in:
Ori Zohar 2020-10-23 18:34:12 -07:00
parent e3dc72210f
commit 4b61351a7c
9 changed files with 303 additions and 184 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
CONTRIBUTING.md Normal file
View File

@ -0,0 +1,3 @@
# Contributing to Dapr docs
Please see [this docs section](https://docs.dapr.io/contributing/) for general guidance on contributions to the Dapr project as well as specific guidelines on contributions to the docs repo.

47
README.md
View File

@ -1,6 +1,14 @@
# Dapr Documentation Repo
# Dapr documentation
This repo contains the markdown files which generate the Dapr documentation site over at https://docs.dapr.io. Head over there to read the docs and get started with Dapr! Read on to get up and running with a local environment to contribute to the docs.
If you are looking to explore the Dapr documentation, please go to the documentation website:
## [docs.dapr.io](https://docs.dapr.io)
This repo contains the markdown files which generate the above website. See below for guidance on running with a local environment to contribute to the docs.
## Contribution guidelines
Before making your first contribution, make sure to review the ["Contributing"](http://docs.dapr.io/contributing/) section in the docs.
## Overview
@ -16,15 +24,33 @@ The [daprdocs](./daprdocs) directory contains the hugo project, markdown files,
## Environment setup
1. Ensure pre-requisites are installed
1. Clone repository
1. Change to daprdocs directory: `cd daprdocs`
1. Add Docsy submodule: `git submodule add https://github.com/google/docsy.git themes/docsy`
1. Update submodules: `git submodule update --init --recursive`
1. Install npm packages: `npm install`
1. Clone this repository
```sh
git clone https://github.com/dapr/docs.git
```
1. Change to daprdocs directory:
```sh
cd daprdocs`
```
1. Add Docsy submodule:
```sh
git submodule add https://github.com/google/docsy.git themes/docsy
```
1. Update submodules:
```sh
git submodule update --init --recursive
```
1. Install npm packages:
```sh
npm install
```
## Run local server
1. Make sure you're still in the daprdocs repo
1. Run `hugo server --disableFastRender`
1. Make sure you're still in the `daprdocs` directory
1. Run
```sh
hugo server --disableFastRender
```
1. Navigate to `http://localhost:1313/docs`
## Update docs
@ -33,8 +59,5 @@ The [daprdocs](./daprdocs) directory contains the hugo project, markdown files,
1. Submit pull request to `master`
1. Staging site will automatically get created and linked to PR to review and test
## Authoring guide
Read the [authoring guide](./authoring-guide.md) for info on how to write docs and be consistent.
## Code of Conduct
Please refer to our [Dapr community code of conduct](https://github.com/dapr/community/blob/master/CODE-OF-CONDUCT.md)

143
authoring-guide.md
View File

@ -1,143 +0,0 @@
# How to author Dapr Docs
This guide will walk through how to write and edit the markdown so that Hugo can correctly render it.
## Styling Conventions
These conventions should be followed throughout all Dapr documentation to ensure a consistent experience across all docs.
1. **Titles** should only capitalize the first word and proper nouns, with the exception of "How-to:"
- "Getting started with Dapr service invocation"
- "How-to: Setup a local Redis instance"
1. **File and folder names** should be globally unique.
- `\service-invocation`
- `service-invocation-overview.md`
1. **[Front-matter](#front-matter)** should be compelted with all fields including type, title, linkTitle, weight, and description.
- `title` should be 1 sentence, no period at the end
- `linkTitle` should be 1-3 words, with the exception of How-to at the front.
- `description` should be 1-2 sentences on what the reader will learn, accomplish, or do in this doc.
## Front-matter
[Front-matter](https://www.docsy.dev/docs/adding-content/content/#page-frontmatter) is what takes regular markdown files and upgrades them into Hugo compatible docs for rendering into the nav bars and ToCs.
Every page needs a section at the top of the document like this:
```yaml
---
type: docs
title: "TITLE FOR THE PAGE"
linkTitle: "SHORT TITLE FOR THE NAV BAR"
weight: (number)
description: "1+ SENTENCES DESCRIBING THE ARTICLE"
---
```
### Example
```yaml
---
type: docs
title: "Service invocation overview"
linkTitle: "Overview"
weight: 10
description: "A quick overview of Dapr service invocation and how to use it to invoke services within your application."
---
```
> Remember to follow the [styling conventions](#styling-conventions) from above.
> Weight determines the order of the pages in the left sidebar, with 0 being the top-most.
## Referencing other pages
Hugo `ref` and `relref` [shortcodes](https://gohugo.io/content-management/cross-references/) are used to reference other pages and sections. It also allows the build to break if a page is incorrectly renamed or removed.
This shortcode, written inline with the rest of the markdown page, will link to the _index.md of the section/folder name:
```
{{< ref "folder" >}}
```
This shortcode will link to a specific page:
```
{{< ref "page.md" >}}
```
> Note that all pages and folders need to have globally unique names in order for the ref shortcode to work properly.
## Images
The markdown spec used by Docsy and Hugo does not give an option to resize images using markdown notation. Instead, raw HMTL is used.
Begin by placing images under `/daprdocs/static/images` with the naming convention of `[page-name]-[image-name].[png|jpg|svg]`.
Then link to the image using:
```
<img src="/images/[image-filename]" width=1000 alt="Description of image">
```
>Don't forget to set the alt attribute to keep the docs readable for our visually impaired users.
### Example
This HTML will display the `dapr-overview.png` image on the `overview.md` page:
```
<img src="/images/overview-dapr-overview.png" width=1000 alt="Overview diagram of Dapr and its building blocks">
```
## Tabbed Content
Tabs are made possible through [Hugo shortcodes](https://gohugo.io/content-management/shortcodes/).
The overall format is:
```
{{< tabs [Tab1] [Tab2]>}}
{{% codetab %}}
[Content for Tab1]
{{% /codetab %}}
{{% codetab %}}
[Content for Tab2]
{{% /codetab %}}
{{< /tabs >}}
```
All content you author will be rendered to Markdown, so you can include images, code blocks, YouTube videos, and more.
### Example
````
{{< tabs Windows Linux MacOS>}}
{{% codetab %}}
```powershell
powershell -Command "iwr -useb https://raw.githubusercontent.com/dapr/cli/master/install/install.ps1 | iex"
```
{{% /codetab %}}
{{% codetab %}}
```bash
wget -q https://raw.githubusercontent.com/dapr/cli/master/install/install.sh -O - | /bin/bash
```
{{% /codetab %}}
{{% codetab %}}
```bash
brew install dapr/tap/dapr-cli
```
{{% /codetab %}}
{{< /tabs >}}
````
## YouTube Videos
Hugo can automatically embed YouTube videos using a shortcode:
```
{{< youtube [VIDEO ID] >}}
```
### Example
Given the video https://youtu.be/dQw4w9WgXcQ
The shortcode would be:
```
{{< youtube dQw4w9WgXcQ >}}
```
## References
- [Docsy authoring guide](https://www.docsy.dev/docs/adding-content/)

2
daprdocs/content/en/contributing/_index.md
View File

@ -6,5 +6,3 @@ weight: 100
description: >
How to contribute to the Dapr project
---

217
daprdocs/content/en/contributing/contributing-docs.md
View File

@ -1,45 +1,214 @@
---
type: docs
title: "Contributing to Dapr Docs"
title: "Docs contributions"
linkTitle: "Docs"
weight: 100
weight: 2000
description: >
How to contribute to Dapr Docs
Guidelines for contributing to the Dapr Docs
---
High quality documentation is a core tenant of the Dapr project. Some contribution guidelines are below.
This guide contains information about contributions to the [Dapr docs repository](https://github.com/dapr/docs). Please review the guidelines below before making a contribution to the Dapr docs. This guide assumes you have already reviewed the [general guidance]({{< ref contributing-overview>}}) which applies to any Dapr project contributions.
Dapr docs are published to [docs.dapr.io](https://docs.dapr.io). Therefore, any contribution must ensure docs can be compiled and published correctly.
## Prerequisites
The Dapr docs are built using [Hugo](https://gohugo.io/) with the [Docsy](https://docsy.dev) theme. To verify docs are built correctly before submitting a contribution, you should setup your local environment to build and display the docs locally.
Fork the [docs repository](https://github.com/dapr/docs) to work on any changes
Follow the instructions in the repository [README.md](https://github.com/dapr/docs/blob/master/README.md#environment-setup) to install Hugo locally and build the docs website.
## Style and tone
These conventions should be followed throughout all Dapr documentation to ensure a consistent experience across all docs.
- Use sentence-casing for headers.
- When referring to product names and technologies use capitalization (e.g. Kubernetes, Helm, Visual Studio Code, Azure Key Vault and of course Dapr).
- Check the spelling and grammar in your articles.
- Use a casual and friendly voice—like tone as if you're talking to another person one-on-one.
- Use simple sentences. Easy-to-read sentences mean the reader can quickly use the guidance you share.
- Use “you” rather than “users” or “developers” conveying friendliness.
- Avoid the word “will”; write in present tense and not future where possible. E.g. Avoid “Next we will open the file and build”. Just say “Now open the file and build”
- Avoid the word “we”. We is generally not meaningful. We who?
- Avoid the word “please”. This is not a letter asking for any help, this is technical documentation.
- Assume a new developer audience. Some obvious steps can seem hard. E.g. Now set an environment variable DAPR to a value X. It is better to give the reader the explicit command to do this, rather than having them figure this out.
- Where possible give the reader links to next document/article for next steps or related topics (this can be relevant "how-to", samples for reference or concepts).
- **Casing** - Use upper case only at the start of a sentence or for proper nouns including names of technologies (Dapr, Redis, Kubernetes etc.).
- **Headers and titles** - Headers and titles must be descriptive and clear, use sentence casing i.e. use the above casing guidance for headers and titles too
- **Use simple sentences** - Easy-to-read sentences mean the reader can quickly use the guidance you share.
- **Avoid the first person** - Use 2nd person "you", "your" instead of "I", "we", "our".
- **Assume a new developer audience** - Some obvious steps can seem hard. E.g. Now set an environment variable Dapr to a value X. It is better to give the reader the explicit command to do this, rather than having them figure this out.
## Contributing to `Concepts`
## Contributing a new docs page
- Make sure the documentation you are writing is in the correct place in the hierarchy.
- Avoid creating new sections where possible, there is a good chance a proper place in the docs hierarchy already exists.
- Make sure to include a complete [Hugo front-matter](front-matter).
### Contributing a new concept doc
- Ensure the reader can understand why they should care about this feature. What problems does it help them solve?
- Ensure the doc references the spec for examples of using the API.
- Ensure the spec is consistent with concept in terms of names, parameters and terminology. Update both the concept and the spec as needed.
- Avoid just repeating the spec. The idea is to give the reader more information and background on the capability so that they can try this out. Hence provide more information and implementation details where possible.
- Provide a link to the spec in the [Reference]({{<ref reference >}}) section.
- Where possible reference a practical How-To] doc.
- Where possible reference a practical How-To doc.
## Contributing to `How-Tos`
### Contributing a new How-To guide
- `How To` articles are meant to provide step-by-step practical guidance on to readers who wish to enable a feature, integrate a technology or use Dapr in a specific scenario.
- Sub directory naming - the directory name should be descriptive and if referring to specific component or concept should begin with the relevant name. Example *pubsub-namespaces*.
- Do not assume the reader is using a specific environment unless the article itself is specific to an environment. This include OS (Windows/Linux/MacOS), deployment target (Kubernetes, IoT etc.) or programming language. If instructions vary between operating systems, provide guidance for all.
- How to articles should include the following sub sections:
- **Pre-requesties**
- **\<Steps\>** times X as needed
- **Cleanup**
- **Related links**
- Include code/sample/config snippets that can be easily copied and pasted.
- Include code/sample/config snippets that can be easily copied and pasted.
- At the end of the article, provide the reader with related links and next steps (this can be other relevant "how-to", samples for reference or related concepts).
## Requirements for docs.dapr.io
Any contribution must ensure not to break the website build. The way Hugo builds the website requires following the below guidance.
### Files and folder names
File and folder names should be globally unique.
- `\service-invocation`
- `service-invocation-overview.md`
### Front-matter
[Front-matter](https://www.docsy.dev/docs/adding-content/content/#page-frontmatter) is what takes regular markdown files and upgrades them into Hugo compatible docs for rendering into the nav bars and ToCs.
Every page needs a section at the top of the document like this:
```yaml
---
type: docs
title: "TITLE FOR THE PAGE"
linkTitle: "SHORT TITLE FOR THE NAV BAR"
weight: (number)
description: "1+ SENTENCES DESCRIBING THE ARTICLE"
---
```
#### Example
```yaml
---
type: docs
title: "Service invocation overview"
linkTitle: "Overview"
weight: 10
description: "A quick overview of Dapr service invocation and how to use it to invoke services within your application"
---
```
> Weight determines the order of the pages in the left sidebar, with 0 being the top-most.
Front-matter should be completed with all fields including type, title, linkTitle, weight, and description.
- `title` should be 1 sentence, no period at the end
- `linkTitle` should be 1-3 words, with the exception of How-to at the front.
- `description` should be 1-2 sentences on what the reader will learn, accomplish, or do in this doc.
As per the [styling conventions](#styling-conventions), titles should only capitalize the first word and proper nouns, with the exception of "How-To:"
- "Getting started with Dapr service invocation"
- "How-To: Setup a local Redis instance"
### Referencing other pages
Hugo `ref` and `relref` [shortcodes](https://gohugo.io/content-management/cross-references/) are used to reference other pages and sections. It also allows the build to break if a page is incorrectly renamed or removed.
This shortcode, written inline with the rest of the markdown page, will link to the _index.md of the section/folder name:
```md
{{</* ref "folder" */>}}
```
This shortcode will link to a specific page:
```md
{{</* ref "page.md" */>}}
```
> Note that all pages and folders need to have globally unique names in order for the ref shortcode to work properly.
### Images
The markdown spec used by Docsy and Hugo does not give an option to resize images using markdown notation. Instead, raw HMTL is used.
Begin by placing images under `/daprdocs/static/images` with the naming convention of `[page-name]-[image-name].[png|jpg|svg]`.
Then link to the image using:
```md
<img src="/images/[image-filename]" width=1000 alt="Description of image">
```
>Don't forget to set the alt attribute to keep the docs readable for our visually impaired users.
#### Example
This HTML will display the `dapr-overview.png` image on the `overview.md` page:
```md
<img src="/images/overview-dapr-overview.png" width=1000 alt="Overview diagram of Dapr and its building blocks">
```
### Tabbed Content
Tabs are made possible through [Hugo shortcodes](https://gohugo.io/content-management/shortcodes/).
The overall format is:
```
{{</* tabs [Tab1] [Tab2]>}}
{{% codetab %}}
[Content for Tab1]
{{% /codetab %}}
{{% codetab %}}
[Content for Tab2]
{{% /codetab %}}
{{< /tabs */>}}
```
All content you author will be rendered to Markdown, so you can include images, code blocks, YouTube videos, and more.
#### Example
````
{{</* tabs Windows Linux MacOS>}}
{{% codetab %}}
```powershell
powershell -Command "iwr -useb https://raw.githubusercontent.com/dapr/cli/master/install/install.ps1 | iex"
```
{{% /codetab %}}
{{% codetab %}}
```bash
wget -q https://raw.githubusercontent.com/dapr/cli/master/install/install.sh -O - | /bin/bash
```
{{% /codetab %}}
{{% codetab %}}
```bash
brew install dapr/tap/dapr-cli
```
{{% /codetab %}}
{{< /tabs */>}}
````
This example will render to this:
{{< tabs Windows Linux MacOS>}}
{{% codetab %}}
```powershell
powershell -Command "iwr -useb https://raw.githubusercontent.com/dapr/cli/master/install/install.ps1 | iex"
```
{{% /codetab %}}
{{% codetab %}}
```bash
wget -q https://raw.githubusercontent.com/dapr/cli/master/install/install.sh -O - | /bin/bash
```
{{% /codetab %}}
{{% codetab %}}
```bash
brew install dapr/tap/dapr-cli
```
{{% /codetab %}}
{{< /tabs >}}
### YouTube Videos
Hugo can automatically embed YouTube videos using a shortcode:
```
{{</* youtube [VIDEO ID] */>}}
```
#### Example
Given the video https://youtu.be/dQw4w9WgXcQ
The shortcode would be:
```
{{</* youtube dQw4w9WgXcQ */>}}
```
### References
- [Docsy authoring guide](https://www.docsy.dev/docs/adding-content/)

69
daprdocs/content/en/contributing/contributing-overview.md Normal file
View File

@ -0,0 +1,69 @@
---
type: docs
title: "Contribution overview"
linkTitle: "Overview"
weight: 1000
description: >
General guidance for contributing to any of the Dapr project repositories
---
Thank you for your interest in Dapr!
This document provides the guidelines for how to contribute to the [Dapr project](https://github.com/dapr) through issues and pull-requests. Contributions can also come in additional ways such as engaging with the community in community calls, commenting on issues or pull requests and more.
See the [Dapr community repository](https://github.com/dapr/community) for more information on community engagement and community membership.
> If you are looking to contribute to the Dapr docs, please also see the specific guidelines for [docs contributions]({{< ref contributing-docs >}}).
## Issues
### Issue types
In most Dapr repositories there are usually 4 types of issues:
- Issue/Bug: You've found a bug with the code, and want to report it, or create an issue to track the bug.
- Issue/Discussion: You have something on your mind, which requires input form others in a discussion, before it eventually manifests as a proposal.
- Issue/Proposal: Used for items that propose a new idea or functionality. This allows feedback from others before code is written.
- Issue/Question: Use this issue type, if you need help or have a question.
### Before submitting
Before you submit an issue, make sure you've checked the following:
1. Is it the right repository?
- The Dapr project is distributed across multiple repositories. Check the list of [repositories](https://github.com/dapr) if you aren't sure which repo is the correct one.
1. Check for existing issues
- Before you create a new issue, please do a search in [open issues](https://github.com/dapr/dapr/issues) to see if the issue or feature request has already been filed.
- If you find your issue already exists, make relevant comments and add your [reaction](https://github.com/blog/2119-add-reaction-to-pull-requests-issues-and-comments). Use a reaction:
- 👍 up-vote
- 👎 down-vote
1. For bugs
- Check it's not an environment issue. For example, if running on Kubernetes, make sure prerequisites are in place. (state stores, bindings, etc.)
- You have as much data as possible. This usually comes in the form of logs and/or stacktrace. If running on Kubernetes or other environment, look at the logs of the Dapr services (runtime, operator, placement service). More details on how to get logs can be found [here](https://github.com/dapr/docs/tree/master/best-practices/troubleshooting/logs.md).
1. For proposals
- Many changes to the Dapr runtime may require changes to the API. In that case, the best place to discuss the potential feature is the main [Dapr repo](https://github.com/dapr/dapr).
- Other examples could include bindings, state stores or entirely new components.
## Pull Requests
All contributions come through pull requests. To submit a proposed change, follow this workflow:
1. Make sure there's an issue (bug or proposal) raised, which sets the expectations for the contribution you are about to make.
1. Fork the relevant repo and create a new branch
1. Create your change
- Code changes require tests
1. Update relevant documentation for the change
1. Commit and open a PR
1. Wait for the CI process to finish and make sure all checks are green
1. A maintainer of the project will be assigned, and you can expect a review within a few days
#### Use work-in-progress PRs for early feedback
A good way to communicate before investing too much time is to create a "Work-in-progress" PR and share it with your reviewers. The standard way of doing this is to add a "[WIP]" prefix in your PR's title and assign the **do-not-merge** label. This will let people looking at your PR know that it is not well baked yet.
### Use of Third-party code
- Third-party code must include licenses.
## Code of Conduct
Please see the [Dapr community code of conduct](https://github.com/dapr/community/blob/master/CODE-OF-CONDUCT.md).

2
daprdocs/content/en/developing-applications/building-blocks/state-management/howto-stateful-service.md
View File

@ -10,7 +10,7 @@ In this article you'll learn how you can create a stateful service which can be
This frees developers from difficult state coordination, conflict resolution and failure handling, and allows them instead to consume these capabilities as APIs from Dapr.
## 1. Setup a state store
## Setup a state store
A state store component represents a resource that Dapr uses to communicate with a database.
For the purpose of this guide, we'll use a Redis state store.

2
daprdocs/content/en/operations/_index.md
View File

@ -3,5 +3,5 @@ type: docs
title: "Deploying and configuring Dapr in your environment"
linkTitle: "Operations"
weight: 40
description: "Hosting options, best-practices, and other guides and running your application on Dapr."
description: "Hosting options, best-practices, and other guides and running your application on Dapr"
---

2
daprdocs/content/en/operations/hosting/kubernetes/kubernetes-hybrid-clusters.md
View File

@ -3,7 +3,7 @@ type: docs
title: "How-To: Deploy to hybrid Linux/Windows Kubernetes clusters"
linkTitle: "Hybrid clusters"
weight: 20000
description: "How to run Dapr apps on kubernetes clusters with windows nodes"
description: "How to run Dapr apps on Kubernetes clusters with windows nodes"
---
Dapr supports running on kubernetes clusters with windows nodes. You can run your Dapr microservices exclusively on Windows, exclusively on Linux, or a combination of both. This is helpful to users who may be doing a piecemeal migration of a legacy application into a Dapr Kubernetes cluster.