mirror of https://github.com/dapr/docs.git
Docs contributing guide updates (#2768)
* initial edits Signed-off-by: Hannah Hunter <hannahhunter@microsoft.com> * updates Signed-off-by: Hannah Hunter <hannahhunter@microsoft.com> * add templates Signed-off-by: Hannah Hunter <hannahhunter@microsoft.com> * fix links Signed-off-by: Hannah Hunter <hannahhunter@microsoft.com> * remove path Signed-off-by: Hannah Hunter <hannahhunter@microsoft.com> * add docs Signed-off-by: Hannah Hunter <hannahhunter@microsoft.com> * remove from .github doc Signed-off-by: Hannah Hunter <hannahhunter@microsoft.com> * fix validate links Signed-off-by: Hannah Hunter <hannahhunter@microsoft.com> * updates per mark Signed-off-by: Hannah Hunter <hannahhunter@microsoft.com> * add submodule section Signed-off-by: Hannah Hunter <hannahhunter@microsoft.com> * remove link and reword Signed-off-by: Hannah Hunter <hannahhunter@microsoft.com> * fix link? Signed-off-by: Hannah Hunter <hannahhunter@microsoft.com> * apparently case matters for links now Signed-off-by: Hannah Hunter <hannahhunter@microsoft.com> * update per mark review Signed-off-by: Hannah Hunter <hannahhunter@microsoft.com> * update link Signed-off-by: Hannah Hunter <hannahhunter@microsoft.com> Signed-off-by: Hannah Hunter <hannahhunter@microsoft.com> Co-authored-by: Mark Fussell <markfussell@gmail.com>
This commit is contained in:
Hannah Hunter
GitHub
parent
df5aab736e
commit
738610883f
|
|
@ -57,7 +57,7 @@ id = "UA-149338238-3"
|
|||
lang = "en"
|
||||
[[module.mounts]]
|
||||
source = "../sdkdocs/python/daprdocs/content/en/python-sdk-contributing"
|
||||
target = "content/contributing/"
|
||||
target = "content/contributing/sdk-contrib/"
|
||||
lang = "en"
|
||||
[[module.mounts]]
|
||||
source = "../sdkdocs/php/daprdocs/content/en/php-sdk-docs"
|
||||
|
|
@ -69,7 +69,7 @@ id = "UA-149338238-3"
|
|||
lang = "en"
|
||||
[[module.mounts]]
|
||||
source = "../sdkdocs/dotnet/daprdocs/content/en/dotnet-sdk-contributing"
|
||||
target = "content/contributing/"
|
||||
target = "content/contributing/sdk-contrib/"
|
||||
lang = "en"
|
||||
[[module.mounts]]
|
||||
source = "../sdkdocs/go/daprdocs/content/en/go-sdk-docs"
|
||||
|
|
@ -77,7 +77,7 @@ id = "UA-149338238-3"
|
|||
lang = "en"
|
||||
[[module.mounts]]
|
||||
source = "../sdkdocs/go/daprdocs/content/en/go-sdk-contributing"
|
||||
target = "content/contributing/"
|
||||
target = "content/contributing/sdk-contrib/"
|
||||
lang = "en"
|
||||
[[module.mounts]]
|
||||
source = "../sdkdocs/java/daprdocs/content/en/java-sdk-docs"
|
||||
|
|
@ -85,7 +85,7 @@ id = "UA-149338238-3"
|
|||
lang = "en"
|
||||
[[module.mounts]]
|
||||
source = "../sdkdocs/java/daprdocs/content/en/java-sdk-contributing"
|
||||
target = "content/contributing/"
|
||||
target = "content/contributing/sdk-contrib/"
|
||||
lang = "en"
|
||||
[[module.mounts]]
|
||||
source = "../sdkdocs/js/daprdocs/content/en/js-sdk-docs"
|
||||
|
|
@ -93,7 +93,7 @@ id = "UA-149338238-3"
|
|||
lang = "en"
|
||||
[[module.mounts]]
|
||||
source = "../sdkdocs/js/daprdocs/content/en/js-sdk-contributing"
|
||||
target = "content/contributing/"
|
||||
target = "content/contributing/sdk-contrib/"
|
||||
lang = "en"
|
||||
|
||||
[[module.mounts]]
|
||||
|
|
@ -102,7 +102,7 @@ id = "UA-149338238-3"
|
|||
lang = "zh-hans"
|
||||
[[module.mounts]]
|
||||
source = "../translations/docs-zh/content/contributing"
|
||||
target = "content/contributing/"
|
||||
target = "content/contributing/docs-contrib/docs-templates"
|
||||
lang = "zh-hans"
|
||||
[[module.mounts]]
|
||||
source = "../translations/docs-zh/content/sdks_python"
|
||||
|
|
|
|||
|
|
@ -2,7 +2,6 @@
|
|||
type: docs
|
||||
title: "Contributing to Dapr"
|
||||
linkTitle: "Contributing"
|
||||
weight: 100
|
||||
description: >
|
||||
How to contribute to the Dapr project
|
||||
weight: 60
|
||||
description: How to contribute to the Dapr project
|
||||
---
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
type: docs
|
||||
title: "Contributing with GitHub Codespaces"
|
||||
linkTitle: "GitHub Codespaces"
|
||||
weight: 2500
|
||||
weight: 60
|
||||
description: "How to work with Dapr repos in GitHub Codespaces"
|
||||
aliases:
|
||||
- "/developing-applications/ides/codespaces/"
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
type: docs
|
||||
title: "Contribution overview"
|
||||
linkTitle: "Overview"
|
||||
weight: 1000
|
||||
weight: 10
|
||||
description: >
|
||||
General guidance for contributing to any of the Dapr project repositories
|
||||
---
|
||||
|
|
|
|||
|
|
@ -0,0 +1,7 @@
|
|||
---
|
||||
type: docs
|
||||
title: "Docs contributing guide"
|
||||
linkTitle: "Docs"
|
||||
weight: 80
|
||||
description: How to contribute to the Dapr docs
|
||||
---
|
||||
|
|
@ -1,82 +1,86 @@
|
|||
---
|
||||
type: docs
|
||||
title: "Docs contributions"
|
||||
linkTitle: "Docs"
|
||||
weight: 2000
|
||||
description: >
|
||||
Guidelines for contributing to the Dapr Docs
|
||||
title: "Contributors guide"
|
||||
linkTitle: "Contributors guide"
|
||||
weight: 10
|
||||
description: Get started with contributing to the Dapr docs
|
||||
---
|
||||
|
||||
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.
|
||||
In this guide, you'll learn how to contribute to the [Dapr docs repository](https://github.com/dapr/docs). Since Dapr docs are published to [docs.dapr.io](https://docs.dapr.io), you must make sure your contributions compile and publish 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
|
||||
Before contributing to the Dapr docs:
|
||||
|
||||
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.
|
||||
- Review the [guidance around general Dapr project contributions]({{< ref contributing-overview>}}).
|
||||
- Install and set up your local environment with [Hugo](https://gohugo.io/) with the [Docsy](https://docsy.dev) theme. Follow the instructions in the repository [README.md](https://github.com/dapr/docs/blob/master/README.md#environment-setup).
|
||||
- Fork and clone the [docs repository](https://github.com/dapr/docs).
|
||||
|
||||
## Branch guidance
|
||||
The Dapr docs handles branching differently than most code repositories. Instead of having a `master` or `main` branch, every branch is labeled to match the major and minor version of a runtime release. For the full list visit the [Docs repo](https://github.com/dapr/docs#branch-guidance)
|
||||
|
||||
Overall, all updates should go into the docs branch for the latest release of Dapr. You can find this directly at [https://github.com/dapr/docs](https://github.com/dapr/docs), as the latest release will be the default branch. For any docs changes that are applicable to a release candidate or a pre-release version of the docs, make your changes into that particular branch.
|
||||
The Dapr docs handles branching differently than most code repositories. Instead of a `main` branch, every branch is labeled to match the major and minor version of a runtime release. For the full list visit the [Docs repo](https://github.com/dapr/docs#branch-guidance)
|
||||
|
||||
For example, if you are fixing a typo, adding notes, or clarifying a point, make your changes into the default Dapr branch. If you are documenting an upcoming change to a component or the runtime, make your changes to the pre-release branch. Branches can be found in the [Docs repo](https://github.com/dapr/docs#branch-guidance)
|
||||
Generally, all of your docs updates should point to [docs branch for the latest release of Dapr](https://github.com/dapr/docs). The latest release is the default branch [https://github.com/dapr/docs]. For example, if you are fixing a typo, adding notes, or clarifying a point, make your changes into the default Dapr branch.
|
||||
|
||||
For any docs changes applicable to a release candidate or a pre-release version of the docs, point your changes into that particular branch. For example, if you are documenting an upcoming change to a component or the runtime, make your changes to the pre-release branch.
|
||||
|
||||
## Style and tone
|
||||
These conventions should be followed throughout all Dapr documentation to ensure a consistent experience across all docs.
|
||||
|
||||
- **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.
|
||||
- **Use present tense** - Avoid sentences like "this command will install redis", which implies the action is in the future. Instead use "This command installs redis" which is in the present tense.
|
||||
Style and tone conventions should be followed throughout all Dapr documentation for consistency across all docs:
|
||||
|
||||
| Style/Tone | Guidance |
|
||||
| ---------- | -------- |
|
||||
| Casing | Use upper case only: <br> <ul><li>At the start of a sentence or header</li><li>For proper nouns, including names of technologies (Dapr, Redis, Kubernetes etc.)</li></ul> |
|
||||
| Headers and titles | Headers and titles must be brief, but descriptive and clear. |
|
||||
| Use simple sentences | Write easy-to-read, scannable sentences. Tip: Skip the formal tone and write as if you were talking directly to the reader. |
|
||||
| Avoid the first person | Instead of first person "I", "we", and "our", use second person "you" and "your". |
|
||||
| Assume a "new developer" audience | Some seemingly obvious steps to an experienced developer might not be as obvious to a new developer. Give the reader more explicit, thorough instructions. |
|
||||
| Use present tense | Avoid sentences like "this command _will_ install Redis". Instead, use "This command installs Redis". |
|
||||
|
||||
## Diagrams and images
|
||||
It is strongly encouraged to create diagrams and images where ever possible for documentation pages. All diagrams are kept in a Dapr Diagrams Deck, which has guidance on style and icons. The diagram images are saved as PNG files into the [images folder](/images).
|
||||
Diagrams should be;
|
||||
- Saved as PNG files with a high resolution
|
||||
- Named using the convention of a concept or building block so that they are grouped. For example `service-invocation-overview.png`. Also see Images guidance section below.
|
||||
- Added to the correct section in the `Dapr-Diagrams.pptx` deck so that they can be amended and updated.
|
||||
|
||||
{{< button text="Download the Dapr Diagrams Deck" link="/presentations/Dapr-Diagrams.pptx.zip" >}}
|
||||
Diagrams and images are invaluable visual aids for documentation pages. Diagrams are kept in a [Dapr Diagrams Deck](https://github.com/dapr/docs/tree/v1.8/daprdocs/static/presentations), which includes guidance on style and icons.
|
||||
|
||||
As you create diagrams for your documentation:
|
||||
|
||||
- Save them as high-res PNG files into the [images folder](https://github.com/dapr/docs/tree/v1.8/daprdocs/static/images).
|
||||
- Name your PNG files using the convention of a concept or building block so that they are grouped.
|
||||
- For example: `service-invocation-overview.png`.
|
||||
- For more information on calling out images using shortcode, see the [Images guidance](#images) section below.
|
||||
- Add the diagram to the correct section in the `Dapr-Diagrams.pptx` deck so that they can be amended and updated during routine refresh.
|
||||
|
||||
## 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.
|
||||
If you're creating a new article, make sure you:
|
||||
|
||||
### 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.
|
||||
- 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).
|
||||
- Place the new document in the correct place in the hierarchy.
|
||||
- Avoid creating new sections. Most likely, the proper place is already in the docs hierarchy.
|
||||
- Include complete [Hugo front-matter](#front-matter).
|
||||
|
||||
Select the topic type below to view a suggested template to help you get started.
|
||||
|
||||
| Topic type | What is it? |
|
||||
| ---------- | ----------- |
|
||||
| [Concept]({{< ref "concept-template.md" >}}) | Answers the question, "What problems does this help me solve?" Avoid repeating the API or component spec; provide more details. |
|
||||
| [Quickstart]({{< ref "quickstart-template.md" >}}) | Provides a "Five minutes to _wow_" experience. Walk the reader quickly through a feature or API and how it works in a controlled example. |
|
||||
| [How-to]({{< ref "howto-template.md" >}}) | Provides a detailed, practical step-by-step through a Dapr feature or technology. Encourage the reader to try with their own scenario, rather than the controlled scenario provided in a quickstart. |
|
||||
|
||||
## 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.
|
||||
|
||||
Make sure your contribution doesn't break the website build. The way Hugo builds the website requires following the guidance below:
|
||||
|
||||
### 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
|
||||
|
|
@ -88,6 +92,7 @@ description: "1+ SENTENCES DESCRIBING THE ARTICLE"
|
|||
```
|
||||
|
||||
#### Example
|
||||
|
||||
```yaml
|
||||
---
|
||||
type: docs
|
||||
|
|
@ -101,35 +106,46 @@ description: "A quick overview of Dapr service invocation and how to use it to i
|
|||
> 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"
|
||||
|
||||
- "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:
|
||||
Hugo `ref` and `relref` [shortcodes](https://gohugo.io/content-management/cross-references/) are used to reference other pages and sections. These shortcodes also allow the build to break if a page is incorrectly renamed or removed.
|
||||
|
||||
For example, 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:
|
||||
While 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. If there are duplicate names the build will break and an error will be thrown.
|
||||
|
||||
All pages and folders need to have _globally unique names_ in order for the ref shortcode to work properly. If there are duplicate names, the build will break and an error will be thrown.
|
||||
|
||||
#### Referencing sections in other pages
|
||||
|
||||
To reference a specific section in another page, add `#section-short-name` to the end of your reference.
|
||||
|
||||
As a general rule, the section short name is the text of the section title, all lowercase, with spaces changed to "-". You can check the section short name by visiting the website page, clicking the link icon (🔗) next to the section, and see how the URL renders in the nav bar. The content after the "#" is your section shortname.
|
||||
As a general rule, the section short name is the text of the section title, all lowercase, with spaces changed to "-". You can check the section short name by:
|
||||
|
||||
As an example, for this specific section the complete reference to the page and section would be:
|
||||
1. Visiting the website page.
|
||||
1. Clicking the link icon (🔗) next to the section.
|
||||
1. Seeing how the URL renders in the nav bar.
|
||||
1. Copying the content after the "#" for your section shortname.
|
||||
|
||||
As an example, for this specific section, the complete reference to the page and section would be:
|
||||
|
||||
```md
|
||||
{{</* ref "contributing-docs.md#referencing-sections-in-other-pages" */>}}
|
||||
|
|
@ -140,28 +156,33 @@ As an example, for this specific section the complete reference to the page and
|
|||
The following are useful shortcodes for writing Dapr documentation
|
||||
|
||||
### Images
|
||||
|
||||
The markdown spec used by Docsy and Hugo does not give an option to resize images using markdown notation. Instead, raw HTML 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.
|
||||
Don't forget to set the `alt` attribute to keep the docs readable and accessible.
|
||||
|
||||
#### 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]>}}
|
||||
|
||||
|
|
@ -176,9 +197,10 @@ The overall format is:
|
|||
{{< /tabs */>}}
|
||||
```
|
||||
|
||||
All content you author will be rendered to Markdown, so you can include images, code blocks, YouTube videos, and more.
|
||||
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>}}
|
||||
|
||||
|
|
@ -208,21 +230,27 @@ 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 >}}
|
||||
|
|
@ -236,12 +264,15 @@ Use the `code-snippet` shortcode to reference code snippets from the `static/cod
|
|||
```
|
||||
|
||||
{{% alert title="Warning" color="warning" %}}
|
||||
All Dapr sample code should be self-contained in separate files, not in markdown. Use the techniques described here to highlight the parts of the sample code users should focus on.
|
||||
All Dapr sample code should be self-contained in separate files, not in markdown. Use these techniques to highlight the parts of the sample code users should focus on.
|
||||
{{% /alert %}}
|
||||
|
||||
Use the `lang` (default `txt`) parameter to configure the language used for syntax highlighting.
|
||||
|
||||
Use the `marker` parameter to limit the embedded snipped to a portion of the sample file. This is useful when you want to show just a portion of a larger file. The typical way to do this is surround the interesting code with comments, and then pass the comment text into `marker`.
|
||||
Use the `marker` parameter to limit the embedded snipped to a portion of the sample file. This is useful when you want to show just a portion of a larger file. Typically, you'd do this by:
|
||||
|
||||
1. Surrounding the interesting code with comments.
|
||||
1. Passing the comment text into `marker`.
|
||||
|
||||
The shortcode below and code sample:
|
||||
|
||||
|
|
@ -324,7 +355,9 @@ Will result in the following output:
|
|||
{{< code-snippet file="./contributing-2.py" lang="python" replace-key-imports="#IMPORTS" replace-value-imports="# Import statements" >}}
|
||||
|
||||
### YouTube videos
|
||||
|
||||
Hugo can automatically embed YouTube videos using a shortcode:
|
||||
|
||||
```
|
||||
{{</* youtube [VIDEO ID] */>}}
|
||||
```
|
||||
|
|
@ -334,6 +367,7 @@ Hugo can automatically embed YouTube videos using a shortcode:
|
|||
Given the video https://youtu.be/dQw4w9WgXcQ
|
||||
|
||||
The shortcode would be:
|
||||
|
||||
```
|
||||
{{</* youtube dQw4w9WgXcQ */>}}
|
||||
```
|
||||
|
|
@ -355,6 +389,7 @@ An optional "newtab" parameter will indicate if the page should open in a new ta
|
|||
#### Link to another docs page
|
||||
|
||||
You can also reference pages in your button as well:
|
||||
|
||||
```
|
||||
{{</* button text="My Button" page="contributing" newtab="true" */>}}
|
||||
```
|
||||
|
|
@ -364,6 +399,7 @@ You can also reference pages in your button as well:
|
|||
#### Button colors
|
||||
|
||||
You can customize the colors using the Bootstrap colors:
|
||||
|
||||
```
|
||||
{{</* button text="My Button" link="https://example.com" color="primary" */>}}
|
||||
{{</* button text="My Button" link="https://example.com" color="secondary" */>}}
|
||||
|
|
@ -381,7 +417,8 @@ You can customize the colors using the Bootstrap colors:
|
|||
{{< button text="My Button" link="https://example.com" color="info" >}}
|
||||
|
||||
### References
|
||||
- [Docsy authoring guide](https://www.docsy.dev/docs/adding-content/)
|
||||
|
||||
[Docsy authoring guide](https://www.docsy.dev/docs/adding-content/)
|
||||
|
||||
## Translations
|
||||
|
||||
|
|
@ -390,12 +427,16 @@ The Dapr Docs supports adding language translations into the docs using git subm
|
|||
You can find an example PR of adding Chinese language support in [PR 1286](https://github.com/dapr/docs/pull/1286).
|
||||
|
||||
Steps to add a language:
|
||||
|
||||
- Open an issue in the Docs repo requesting to create a new language-specific docs repo
|
||||
- Once created, create a git submodule within the docs repo:
|
||||
|
||||
```sh
|
||||
git submodule add <remote_url> translations/<language_code>
|
||||
```
|
||||
|
||||
- Add a language entry within `daprdocs/config.toml`:
|
||||
|
||||
```toml
|
||||
[languages.<language_code>]
|
||||
title = "Dapr Docs"
|
||||
|
|
@ -403,11 +444,18 @@ Steps to add a language:
|
|||
contentDir = "content/<language_code>"
|
||||
languageName = "<language_name>"
|
||||
```
|
||||
|
||||
- Create a mount within `daprdocs/config.toml`:
|
||||
|
||||
```toml
|
||||
[[module.mounts]]
|
||||
source = "../translations/docs-<language_code>/content/<language_code>"
|
||||
target = "content"
|
||||
lang = "<language_code>"
|
||||
```
|
||||
- Repeat above step as necessary for all other translation directories
|
||||
|
||||
- Repeat above step as necessary for all other translation directories.
|
||||
|
||||
## Next steps
|
||||
|
||||
Get started by copying and working from one of [the Dapr doc templates]({{< ref docs-templates >}}).
|
||||
|
|
@ -0,0 +1,7 @@
|
|||
---
|
||||
type: docs
|
||||
title: "Suggested Dapr docs templates"
|
||||
linkTitle: "Docs templates"
|
||||
weight: 100
|
||||
description: Suggested template guidance for new Dapr doc articles
|
||||
---
|
||||
|
|
@ -0,0 +1,102 @@
|
|||
---
|
||||
type: docs
|
||||
title: "Conceptual article template"
|
||||
linkTitle: "Conceptual template"
|
||||
weight: 10
|
||||
description: Suggested template and guidance for creating a concept article
|
||||
---
|
||||
|
||||
|
||||
## Contributing a new conceptual or overview article
|
||||
|
||||
Conceptual (or overview) articles answer the questions:
|
||||
|
||||
- Why should you care about this feature?
|
||||
- What problems does it help you solve?
|
||||
|
||||
While a component, API, or SDK spec may help readers understand how to use or work with these features, a conceptual article provides more depth and context. Link off to the spec article, but try not to simply repeat the spec.
|
||||
|
||||
When naming your conceptual article, make sure it is consistent with the spec in terms of names, parameters, and terminology. Make sure you update both as needed.
|
||||
|
||||
{{% alert title="Note" color="primary" %}}
|
||||
This template is only a suggestion. Feel free to change based on your document's purpose.
|
||||
{{% /alert %}}
|
||||
|
||||
Learn more about [contributing to the Dapr docs]({{< ref contributing-docs.md >}}), like [front-matter]({{< ref "contributing-docs.md#front-matter" >}}) and [shortcodes]({{< ref "contributing-docs.md#shortcodes" >}}).
|
||||
|
||||
### Template
|
||||
|
||||
```md
|
||||
---
|
||||
type: #Required; docs
|
||||
title: #Required; Brief, clear title
|
||||
linkTitle: #Required; Brief title
|
||||
weight: #Required; Use the correct weight based on hierarchy
|
||||
description: #Required; One-sentence description of what to expect in the article
|
||||
---
|
||||
|
||||
<!--
|
||||
Remove all the comments in this template before opening a PR.
|
||||
-->
|
||||
|
||||
<!--
|
||||
H1: The title in the Hugo front-matter serves as the article's markdown H1.
|
||||
-->
|
||||
|
||||
<!-- Introductory paragraph
|
||||
Required. Brief intro that describes the concepts that the article will cover. Link off to the appropriate reference, specs, or how-to guides to provide context. -->
|
||||
|
||||
<!--
|
||||
Include a diagram or image, if possible.
|
||||
-->
|
||||
|
||||
## <Section 1 H2>
|
||||
|
||||
<!--
|
||||
Add your content here.
|
||||
-->
|
||||
|
||||
## <Section 2 H2>
|
||||
|
||||
<!--
|
||||
Each H2 step should start with a noun/descriptive word.
|
||||
-->
|
||||
|
||||
## <Section 3 H2>
|
||||
|
||||
<!--
|
||||
Add your content here.
|
||||
-->
|
||||
|
||||
<!--
|
||||
Include diagrams or images throughout, where applicable.
|
||||
-->
|
||||
|
||||
## Try out <concept>
|
||||
|
||||
<!--
|
||||
If applicable, include a section with links to the related quickstart, how-to guides, or tutorials. -->
|
||||
|
||||
### Quickstarts and tutorials
|
||||
|
||||
Want to put the Dapr <topic> API to the test? Walk through the following quickstart and tutorials to see <topic> in action:
|
||||
|
||||
| Quickstart/tutorial | Description |
|
||||
| ------------------- | ----------- |
|
||||
| [<topic> quickstart](link) | Description of the quickstart. |
|
||||
| [<topic> tutorial](link) | Description of the tutorial. |
|
||||
|
||||
### Start using <topic> directly in your app
|
||||
|
||||
Want to skip the quickstarts? Not a problem. You can try out the <topic> building block directly in your application. After [Dapr is installed](link), you can begin using the <topic> API, starting with [the <topic> how-to guide](link).
|
||||
|
||||
|
||||
-->
|
||||
|
||||
## Next steps
|
||||
|
||||
<!--
|
||||
Link to related pages and examples. For example, the related API spec, related building blocks, etc.
|
||||
-->
|
||||
|
||||
```
|
||||
|
|
@ -0,0 +1,86 @@
|
|||
---
|
||||
type: docs
|
||||
title: "How-to guide template"
|
||||
linkTitle: "How-to template"
|
||||
weight: 30
|
||||
description: Suggested template and guidance for creating a how-to guide
|
||||
---
|
||||
|
||||
## Contributing a new how-to guide
|
||||
|
||||
How-to guides provide step-by-step practical guidance to readers who wish to:
|
||||
|
||||
- Enable a feature
|
||||
- Integrate a technology
|
||||
- Use Dapr in a specific scenario
|
||||
|
||||
How-to guides can be considered "next-level", self-guided docs compared to quickstarts. How-to scenarios will take longer and can be more easily applied to the reader's individual project or environment.
|
||||
|
||||
When naming your how-to document, include the sub-directory name in the file name. If you need to create a new sub-directory, make sure it's descriptive and includes the relevant component or concept name. For example, _pubsub-namespaces_.
|
||||
|
||||
{{% alert title="Note" color="primary" %}}
|
||||
This template is only a suggestion. Feel free to change based on your document's purpose.
|
||||
{{% /alert %}}
|
||||
|
||||
Learn more about [contributing to the Dapr docs]({{< ref contributing-docs.md >}}), like [front-matter]({{< ref "contributing-docs.md#front-matter" >}}) and [shortcodes]({{< ref "contributing-docs.md#shortcodes" >}}).
|
||||
|
||||
### Template
|
||||
|
||||
```md
|
||||
---
|
||||
type: #Required; docs
|
||||
title: #Required; "How to: Brief, clear title"
|
||||
linkTitle: #Required; "How to: Shorter than regular title, to show in table of contents"
|
||||
weight: #Required; Use the correct weight based on hierarchy
|
||||
description: #Required; One-sentence description of what to expect in the article
|
||||
---
|
||||
|
||||
<!--
|
||||
Remove all the comments in this template before opening a PR.
|
||||
-->
|
||||
|
||||
<!--
|
||||
H1: The title in the Hugo front-matter serves as the article's markdown H1.
|
||||
-->
|
||||
|
||||
<!-- Introductory paragraph
|
||||
Required. Light intro that briefly describes what the how-to will cover and any default Dapr characteristics. Link off to the appropriate concept or overview docs to provide context. -->
|
||||
|
||||
<!--
|
||||
Include a diagram or image, if possible.
|
||||
-->
|
||||
|
||||
<!--
|
||||
If applicable, link to the related quickstart in a shortcode note or alert with text like:
|
||||
|
||||
If you haven't already, [try out the <topic> quickstart](link) for a quick walk-through on how to use <topic>.
|
||||
|
||||
-->
|
||||
|
||||
<!--
|
||||
Make sure the how-to includes examples for multiple programming languages, OS, or deployment targets, if applicable.
|
||||
-->
|
||||
|
||||
## <Action or task>
|
||||
|
||||
<!--
|
||||
Unlike quickstarts, do not use "Step 1", "Step 2", etc.
|
||||
-->
|
||||
|
||||
## <Action or task>
|
||||
|
||||
<!--
|
||||
Each H2 step should start with a verb/action word.
|
||||
-->
|
||||
|
||||
<!--
|
||||
Include code snippets where possible.
|
||||
-->
|
||||
|
||||
## Next steps
|
||||
|
||||
<!--
|
||||
Link to related pages and examples. For example, the building block overview, the related tutorial, API reference, etc.
|
||||
-->
|
||||
|
||||
```
|
||||
|
|
@ -0,0 +1,92 @@
|
|||
---
|
||||
type: docs
|
||||
title: "Quickstart guide template"
|
||||
linkTitle: "Quickstart template"
|
||||
weight: 20
|
||||
description: Suggested template and guidance for creating a quickstart guide
|
||||
---
|
||||
|
||||
## Contributing a new quickstart guide
|
||||
|
||||
Dapr quickstart guides consist of quick instructions that walk readers through a prepared quickstart, saved to the [dapr/quickstarts repo](https://github.com/dapr/quickstarts). These quickstarts package an entire feature or building block in one place, making it easy for the reader to experience how it works without compromising their own project.
|
||||
|
||||
The quickstart instructions should be succinct, direct, and clear. The sole purpose of a quickstart guide is to simply instruct a reader through the prepared quickstart. If you'd like to explain the concepts behind the quickstart, direct the reader to a concept article for more context.
|
||||
|
||||
{{% alert title="Note" color="primary" %}}
|
||||
This template is only a suggestion. Feel free to change based on your document's purpose.
|
||||
{{% /alert %}}
|
||||
|
||||
Learn more about [contributing to the Dapr docs]({{< ref contributing-docs.md >}}), like [front-matter]({{< ref "contributing-docs.md#front-matter" >}}) and [shortcodes]({{< ref "contributing-docs.md#shortcodes" >}}).
|
||||
|
||||
### Template
|
||||
|
||||
```md
|
||||
---
|
||||
type: #Required; docs
|
||||
title: #Required; "Quickstart: Brief, clear title"
|
||||
linkTitle: #Required; This will display in the docs table of contents
|
||||
weight: #Required; Use the correct weight based on hierarchy
|
||||
description: #Required; One-sentence description of what to expect in the article
|
||||
---
|
||||
|
||||
<!--
|
||||
Remove all the comments in this template before opening a PR.
|
||||
-->
|
||||
|
||||
<!--
|
||||
H1: The title in the Hugo front-matter serves as the article's markdown H1.
|
||||
-->
|
||||
|
||||
<!-- Introductory paragraph
|
||||
Required. Light intro that briefly describes what the quickstart will cover. Link off to the appropriate concept or overview docs to provide context. -->
|
||||
|
||||
<!--
|
||||
Include a diagram or image, if possible.
|
||||
-->
|
||||
|
||||
<!--
|
||||
Make sure the quickstart includes examples for multiple programming languages.
|
||||
-->
|
||||
|
||||
## Pre-requisites
|
||||
|
||||
<!--
|
||||
Make sure the reader is prepared for a successful quickstart walk through by listing what they may need.
|
||||
-->
|
||||
|
||||
## Step 1: Set up the environment
|
||||
|
||||
<!--
|
||||
Link to the quickstart sample for the reader to clone.
|
||||
-->
|
||||
|
||||
## Step 2: <action or task>
|
||||
|
||||
<!--
|
||||
Each H2 step should start with a verb/action word.
|
||||
-->
|
||||
|
||||
<!--
|
||||
Include code snippets where possible.
|
||||
-->
|
||||
|
||||
## Tell us what you think!
|
||||
|
||||
We're continuously working to improve our Quickstart examples and value your feedback. Did you find this quickstart helpful? Do you have suggestions for improvement?
|
||||
|
||||
Join the discussion in our [discord channel](https://discord.gg/22ZtJrNe).
|
||||
|
||||
<!-- Since Dapr is an open community of contributors, make sure to provide a link to the discord discussion to welcome feedback.
|
||||
-->
|
||||
|
||||
## Next steps
|
||||
|
||||
<!--
|
||||
Link to related pages and examples. For example, the building block overview, the HTTP version of an SDK quickstart sample, etc.
|
||||
-->
|
||||
|
||||
<!--
|
||||
Use the button shortcode to direct readers to more in-depth, related scenarios, like the Dapr tutorials.
|
||||
-->
|
||||
|
||||
```
|
||||
|
|
@ -0,0 +1,386 @@
|
|||
---
|
||||
type: docs
|
||||
title: "Maintainer guide"
|
||||
linkTitle: "Maintainer guide"
|
||||
weight: 20
|
||||
description: "Get started as a Dapr docs maintainer and approver."
|
||||
---
|
||||
|
||||
In this guide, you’ll learn how to perform routine Dapr docs maintainer and approver responsibilities. In order to successfully accomplish these tasks, you need either approver or maintainer status in the [`dapr/docs`](https://github.com/dapr/docs) repo.
|
||||
|
||||
To learn how to contribute to Dapr docs, review the [Contributor guide]({{< ref contributing-docs.md >}}).
|
||||
|
||||
## Branch guidance
|
||||
|
||||
The Dapr docs handles branching differently than most code repositories. Instead of a `main` branch, every branch is labeled to match the major and minor version of a runtime release.
|
||||
|
||||
For the full list, visit the [Docs repo](https://github.com/dapr/docs#branch-guidance).
|
||||
|
||||
Read the [contributor's guide]({{< ref "contributing-docs.md#branch-guidance" >}}) for more information about release branches.
|
||||
|
||||
## Upmerge from current release branch to the pre-release branch
|
||||
|
||||
As a docs approver or maintainer, you need to perform routine upmerges to keep the pre-release branch aligned with updates to the current release branch. It is recommended to upmerge the current branch into the pre-release branch on a weekly basis.
|
||||
|
||||
For the following steps, treat `v1.0` as the current release and `v1.1` as the upcoming release.
|
||||
|
||||
1. Open Visual Studio Code to the Dapr docs repo.
|
||||
1. From your local repo, switch to the latest branch (`v1.0`) and synchronize changes:
|
||||
|
||||
```bash
|
||||
git pull upstream v1.0
|
||||
git push origin v1.0
|
||||
```
|
||||
|
||||
1. Switch to the upcoming branch (`v1.1`) and synchronize changes:
|
||||
|
||||
```bash
|
||||
git pull upstream v1.1
|
||||
git push origin v1.1
|
||||
```
|
||||
|
||||
1. Create a new branch based off of the upcoming release:
|
||||
|
||||
```bash
|
||||
git checkout -b upmerge_MM-DD
|
||||
```
|
||||
|
||||
1. Open a terminal and stage a merge from the latest release into the upmerge branch:
|
||||
|
||||
```bash
|
||||
git merge --no-ff --no-commit v1.0
|
||||
```
|
||||
|
||||
1. In the terminal, make sure included files look accurate. Inspect any merge conflicts in VS Code. Remove configuration changes or version information that does not need to be merged.
|
||||
1. Commit the staged changes and push to the upmerge branch (`upmerge_MM-DD`).
|
||||
1. Open a PR from the upmerge branch to the upcoming release branch (`v1.1`).
|
||||
1. Review the PR and double check that no unintended changes were pushed to the upmerge branch.
|
||||
|
||||
## Release process
|
||||
|
||||
Dapr docs must align with features and updates included in the Dapr project release. Leading up to the Dapr release date, make sure:
|
||||
|
||||
- All new features or updates have been sufficiently documented and reviewed.
|
||||
- Docs PRs for the upcoming release point to the release branch.
|
||||
|
||||
For the following steps, treat `v1.0` as the latest release and `v1.1` as the upcoming release.
|
||||
|
||||
The release process for docs requires the following:
|
||||
|
||||
- An upmerge of the latest release into the upcoming release branch
|
||||
- An update to the latest and upcoming release Hugo configuration files
|
||||
- A new Azure Static Web App for the next version
|
||||
- A new DNS entry for the next version's website
|
||||
- A new git branch for the next version
|
||||
|
||||
### Upmerge
|
||||
|
||||
First, perform a [docs upmerge](#upmerge-from-current-release-branch-to-the-pre-release-branch) from the latest release to the upcoming release branch.
|
||||
|
||||
### Update Hugo Configuration
|
||||
|
||||
After upmerge, prepare the docs branches for the release. In two separate PRs, you need to:
|
||||
|
||||
- Archive the latest release.
|
||||
- Bring the preview/release branch as the current, live version of the docs.
|
||||
|
||||
#### Latest release
|
||||
|
||||
These steps will prepare the latest release branch for archival.
|
||||
|
||||
1. Open VS Code to the Dapr docs repo.
|
||||
1. Switch to the latest branch (`v1.0`) and synchronize changes:
|
||||
|
||||
```bash
|
||||
git pull upstream v1.0
|
||||
git push origin v1.0
|
||||
```
|
||||
|
||||
1. Create a new branch based off of the latest release:
|
||||
|
||||
```bash
|
||||
git checkout -b release_v1.0
|
||||
```
|
||||
|
||||
1. In VS Code, navigate to `/daprdocs/config.toml`.
|
||||
1. Add the following TOML to the `# Versioning` section (around line 154):
|
||||
|
||||
```toml
|
||||
version_menu = "v1.0"
|
||||
version = "v1.0"
|
||||
archived_version = true
|
||||
url_latest_version = "https://docs.dapr.io"
|
||||
|
||||
[[params.versions]]
|
||||
version = "v1.2 (preview)"
|
||||
url = "v1-2.docs.dapr.io"
|
||||
[[params.versions]]
|
||||
version = "v1.1 (latest)"
|
||||
url = "#"
|
||||
[[params.versions]]
|
||||
version = "v1.0"
|
||||
url = "https://v1-0.docs.dapr.io"
|
||||
```
|
||||
|
||||
1. Delete `.github/workflows/website-root.yml`.
|
||||
1. Commit the staged changes and push to your branch (`release_v1.0`).
|
||||
1. Open a PR from `release_v1.0` to `v1.0`.
|
||||
1. Have a docs maintainer or approver review. Wait to merge the PR until release.
|
||||
|
||||
#### Upcoming release
|
||||
|
||||
These steps will prepare the upcoming release branch for promotion to latest release.
|
||||
|
||||
1. Open VS Code to the Dapr docs repo.
|
||||
1. Switch to the upcoming release branch (`v1.1`) and synchronize changes:
|
||||
|
||||
```bash
|
||||
git pull upstream v1.1
|
||||
git push origin v1.1
|
||||
```
|
||||
|
||||
1. Create a new branch based off of the upcoming release:
|
||||
|
||||
```bash
|
||||
git checkout -b release_v1.1
|
||||
```
|
||||
|
||||
1. In VS Code, navigate to `/daprdocs/config.toml`.
|
||||
1. Update line 1 to `baseURL - https://docs.dapr.io/`.
|
||||
1. Update the `# Versioning` section (around line 154) to display the correct versions and tags:
|
||||
|
||||
```toml
|
||||
# Versioning
|
||||
version_menu = "v1.1 (latest)"
|
||||
version = "v1.1"
|
||||
archived_version = false
|
||||
url_latest_version = "https://docs.dapr.io"
|
||||
|
||||
[[params.versions]]
|
||||
version = "v1.2 (preview)"
|
||||
url = "v1-2.docs.dapr.io"
|
||||
[[params.versions]]
|
||||
version = "v1.1 (latest)"
|
||||
url = "#"
|
||||
[[params.versions]]
|
||||
version = "v1.0"
|
||||
url = "https://v1-0.docs.dapr.io"
|
||||
```
|
||||
|
||||
1. Navigate to `.github/workflows/website-root.yml`.
|
||||
1. Update the branches which trigger the workflow:
|
||||
|
||||
```yml
|
||||
name: Azure Static Web App Root
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- v1.1
|
||||
pull_request:
|
||||
types: [opened, synchronize, reopened, closed]
|
||||
branches:
|
||||
- v1.1
|
||||
```
|
||||
|
||||
1. Navigate to `/README.md`.
|
||||
1. Update the versions table:
|
||||
|
||||
```markdown
|
||||
| Branch | Website | Description |
|
||||
| ------------------------------------------------------------ | -------------------------- | ------------------------------------------------------------------------------------------------ |
|
||||
| [v1.1](https://github.com/dapr/docs) (primary) | https://docs.dapr.io | Latest Dapr release documentation. Typo fixes, clarifications, and most documentation goes here. |
|
||||
| [v1.2](https://github.com/dapr/docs/tree/v1.2) (pre-release) | https://v1-2.docs.dapr.io/ | Pre-release documentation. Doc updates that are only applicable to v1.2+ go here. |
|
||||
```
|
||||
|
||||
1. In VS Code, search for any `v1.0` references and replace them with `v1.1` as applicable.
|
||||
1. Commit the staged changes and push to your branch (`release_v1.1`).
|
||||
1. Open a PR from `release/v1.1` to `v1.1`.
|
||||
1. Have a docs maintainer or approver review. Wait to merge the PR until release.
|
||||
|
||||
### Create new website for future release
|
||||
|
||||
Next, create a new website for the future Dapr release, which you point to from the latest website. To do this, you'll need to:
|
||||
|
||||
- Deploy an Azure Static Web App.
|
||||
- Configure DNS via request from CNCF.
|
||||
|
||||
These steps require authentication.
|
||||
|
||||
#### Deploy Azure Static Web App
|
||||
|
||||
Deploy a new Azure Static Web App for the future Dapr release. For this example, we use v1.2 as the future release.
|
||||
|
||||
{{% alert title="Important" color="primary" %}}
|
||||
You need Microsoft employee access to create a new Azure Static Web App.
|
||||
{{% /alert %}}
|
||||
|
||||
1. Use Azure PIM to [elevate into the Owner role](https://eng.ms/docs/cloud-ai-platform/devdiv/devdiv-azure-service-dmitryr/azure-devex-philon/dapr/dapr/assets/azure) for the Dapr Prod subscription.
|
||||
1. Navigate to the [docs-website](https://ms.portal.azure.com/#@microsoft.onmicrosoft.com/resource/subscriptions/38875a89-0178-4f27-a141-dc6fc01f183d/resourceGroups/docs-website/overview) resource group.
|
||||
1. Select **+ Create** and search for **Static Web App**. Select **Create**.
|
||||
1. Enter in the following information:
|
||||
- Subscription: `Dapr Prod`
|
||||
- Resource Group: `docs-website`
|
||||
- Name: `daprdocs-v1-2`
|
||||
- Hosting Plan: `Free`
|
||||
- Region: `West US 2`
|
||||
- Source: `Other`
|
||||
1. Select **Review + create**, and then deploy the static web app.
|
||||
1. Wait for deployment, and navigate to the new static web app resource.
|
||||
1. Select **Manage deployment token** and copy the value.
|
||||
1. Navigate to the docs repo **Secrets management** page under **Settings** and create a new secret named `AZURE_STATIC_WEB_APPS_V1_2`, and provide the value of the deployment token.
|
||||
|
||||
#### Configure DNS
|
||||
|
||||
{{% alert title="Important" color="primary" %}}
|
||||
This section can only be completed on a Secure Admin Workstation (SAW). If you do not have a SAW device, ask a team member with one to assist.
|
||||
|
||||
{{% /alert %}}
|
||||
|
||||
1. Ensure you are a member of the `DMAdaprweb` security group in IDWeb.
|
||||
1. Navigate to [https://prod.msftdomains.com/dns/form?environment=0](https://prod.msftdomains.com/dns/form?environment=0) on a SAW
|
||||
1. Enter the following details in the left-hand pane:
|
||||
- Team Owning Alias: `DMAdaprweb`
|
||||
- Business Justification/Notes: `Configuring DNS for new Dapr docs website`
|
||||
- Environment: `Internet/Public-facing`
|
||||
- Zone: `dapr.io`
|
||||
- Action: `Add`
|
||||
- Incident ID: Leave blank
|
||||
|
||||
1. Back in the new static web app you just deployed, navigate to the **Custom domains** blade and select **+ Add**
|
||||
1. Enter `v1-2.docs.dapr.io` under **Domain name**. Click **Next**.
|
||||
1. Keep **Hostname record type** as `CNAME`, and copy the value of **Value**.
|
||||
1. Back in the domain portal, enter the following information in the main pane:
|
||||
- Name: `v1-2.docs`
|
||||
- Type: `CNAME`
|
||||
- Data: Value you just copied from the static web app
|
||||
|
||||
1. Click **Submit** in the top right corner.
|
||||
1. Wait for two emails:
|
||||
- One saying your request was received.
|
||||
- One saying the request was completed.
|
||||
1. Back in the Azure Portal, click **Add**. You may need to click a couple times to account for DNS delay.
|
||||
1. An SSL is now generated for you and the DNS record is saved. This may take 2-3 minutes.
|
||||
1. Navigate to `https://v1-2.docs.dapr.io` and verify a blank website loads correctly.
|
||||
|
||||
### Configure future website branch
|
||||
|
||||
1. Open VS Code to the Dapr docs repo.
|
||||
1. Switch to the upcoming release branch (`v1.1`) and synchronize changes:
|
||||
|
||||
```bash
|
||||
git pull upstream v1.1
|
||||
git push origin v1.1
|
||||
```
|
||||
|
||||
1. Create a new branch based on `v1.1` and name it `v1.2`:
|
||||
|
||||
```bash
|
||||
git checkout -b release_v1.1
|
||||
```
|
||||
|
||||
1. Rename `.github/workflows/website-v1-1.yml` to `.github/workflows/website-v1-2.yml`.
|
||||
1. Open `.github/workflows/website-v1-2.yml` in VS Code and update the name, trigger, and deployment target to 1.2:
|
||||
|
||||
```yml
|
||||
name: Azure Static Web App v1.2
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- v1.2
|
||||
pull_request:
|
||||
types: [opened, synchronize, reopened, closed]
|
||||
branches:
|
||||
- v1.2
|
||||
|
||||
...
|
||||
|
||||
with:
|
||||
azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_V1_2 }}
|
||||
repo_token: ${{ secrets.GITHUB_TOKEN }}
|
||||
|
||||
...
|
||||
|
||||
with:
|
||||
azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_V1_2 }}
|
||||
skip_deploy_on_missing_secrets: true
|
||||
```
|
||||
|
||||
1. Navigate to `daprdocs/config.toml` and update the `baseURL` to point to the new preview website:
|
||||
|
||||
```toml
|
||||
baseURL = "https://v1-2.docs.dapr.io"
|
||||
```
|
||||
|
||||
1. Update the `# GitHub Information` and `# Versioning` sections (around line 148) to display the correct versions and tags:
|
||||
|
||||
```toml
|
||||
# GitHub Information
|
||||
github_repo = "https://github.com/dapr/docs"
|
||||
github_project_repo = "https://github.com/dapr/dapr"
|
||||
github_subdir = "daprdocs"
|
||||
github_branch = "v1.2"
|
||||
|
||||
# Versioning
|
||||
version_menu = "v1.2 (preview)"
|
||||
version = "v1.2"
|
||||
archived_version = false
|
||||
url_latest_version = "https://docs.dapr.io"
|
||||
|
||||
[[params.versions]]
|
||||
version = "v1.2 (preview)"
|
||||
url = "#"
|
||||
[[params.versions]]
|
||||
version = "v1.1 (latest)"
|
||||
url = "https://docs.dapr.io"
|
||||
[[params.versions]]
|
||||
version = "v1.0"
|
||||
url = "https://v1-0.docs.dapr.io"
|
||||
```
|
||||
|
||||
1. Commit the staged changes and push to the v1.2 branch.
|
||||
1. Navigate to the [docs Actions page](https://github.com/dapr/docs/actions) and make sure the build & release successfully completed.
|
||||
1. Navigate to the new `https://v1-2.docs.dapr.io` website and verify that the new version is displayed.
|
||||
|
||||
### On the new Dapr release date
|
||||
|
||||
1. Wait for all code/containers/Helm charts to be published.
|
||||
1. Merge the the PR from `release_v1.0` to `v1.0`. Delete the release/v1.0 branch.
|
||||
1. Merge the the PR from `release_v1.1` to `v1.1`. Delete the release/v1.1 branch.
|
||||
|
||||
Congrats on the new docs release! 🚀 🎉 🎈
|
||||
|
||||
## Pull in SDK doc updates
|
||||
|
||||
SDK docs live in each of the SDK repos. Changes made to the SDK docs are pushed to the relevant SDK repo. For example, to update the Go SDK docs, you push changes to the `dapr/go-sdk` repo. Until you pull the latest `dapr/go-sdk` commit into the `dapr/docs` current version branch, your Go SDK docs updates won't be reflected on the Dapr docs site.
|
||||
|
||||
To bring updates to the SDK docs live to the Dapr docs site, you need to perform a straightforward `git pull`. This example refers to the Go SDK, but applies to all SDKs.
|
||||
|
||||
1. Pull the latest upstream into your local `dapr/docs` version branch.
|
||||
|
||||
1. Change into the root of the `dapr/docs` directory.
|
||||
|
||||
1. Change into the Go SDK repo. This command takes you out of the `dapr/docs` context and into the `dapr/go-sdk` context.
|
||||
|
||||
```bash
|
||||
cd sdkdocs/go
|
||||
```
|
||||
|
||||
1. Switch to the `main` branch in `dapr/go-sdk`.
|
||||
|
||||
```bash
|
||||
git checkout main
|
||||
```
|
||||
|
||||
1. Pull the latest Go SDK commit.
|
||||
|
||||
```bash
|
||||
git pull upstream main
|
||||
```
|
||||
|
||||
1. Change into the `dapr/docs` context to commit, push, and create a PR.
|
||||
|
||||
## Next steps
|
||||
|
||||
For guidance on contributing to Dapr docs, read the [Contributor Guide]({{< ref contributing-docs.md >}}).
|
||||
|
|
@ -2,7 +2,7 @@
|
|||
type: docs
|
||||
title: "Giving a presentation on Dapr"
|
||||
linkTitle: "Presentations"
|
||||
weight: 1500
|
||||
weight: 20
|
||||
description: How to give a presentation on Dapr and examples
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@ type: docs
|
|||
title: "Dapr Roadmap"
|
||||
linkTitle: "Roadmap"
|
||||
description: "The Dapr Roadmap is a tool to help with visibility into investments across the Dapr project"
|
||||
weight: 1100
|
||||
weight: 30
|
||||
no_list: true
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,7 @@
|
|||
---
|
||||
type: docs
|
||||
title: "SDK contributing guide"
|
||||
linkTitle: "SDKs"
|
||||
weight: 80
|
||||
description: How to contribute to the Dapr SDK docs
|
||||
---
|
||||
|
|
@ -2,6 +2,6 @@
|
|||
type: docs
|
||||
title: "Dapr Reference Docs"
|
||||
linkTitle: "Reference"
|
||||
weight: 60
|
||||
weight: 50
|
||||
description: "Detailed documentation on the Dapr API, CLI, bindings and more"
|
||||
---
|
||||
|
|
|
|||
Loading…
Reference in New Issue