Add alpha/beta version information to alerts (#375)

This commit is contained in:
Pete Lumbis 2023-03-01 14:09:33 -05:00 committed by GitHub
parent dad3573e2e
commit a80242ff8a
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
8 changed files with 62 additions and 22 deletions

View File

@ -45,7 +45,8 @@ documentation.
{{< /hint >}}
Make changes to the files in the associated version folder. To make changes
across multiple versions change the files in each version folder.
across more than one version, change the files in each version folder.
## Adding new content
To create new content create a new markdown file in the appropriate location.
@ -55,8 +56,8 @@ root.
### Types of content
Crossplane documentation has three content sections:
* The [Contributing Guide]({{<ref "/contribute/_index.md">}}) with details on how to
contribute to the Crossplane documentation.
* The [Contributing Guide]({{<ref "/contribute/_index.md">}}) with details on
how to contribute to the Crossplane documentation.
* The [Knowledge Base]({{<ref "/knowledge-base" >}}) is for content related to
Crossplane integrations, in-depth articles or how-to guides.
* [User documentation]({{<ref "/master" >}}) are for generic documentation,
@ -74,22 +75,26 @@ of a Crossplane Provider.
_Procedural_ content is the step-by-step instructions to do something.
Procedural content details the "how" of a piece of technology.
An example of a _Procedural_ document would be a step-by-step Crossplane installation guide.
An example of a _Procedural_ document would be a step-by-step Crossplane
installation guide.
User documentation is more narrowly focused on a single piece or
related pieces of technology. For example, installing a Provider and creating a
ProviderConfig.
Knowledge base articles are more "free-form" and can describe multiple pieces of
technology or provide more opinionated examples.
Knowledge base articles are more "free-form" and can describe more than one
piece of technology or provide more opinionated examples.
{{< hint "tip" >}}
Not sure if the content would be better as a knowledge base article or user
document? Ask in the `#documentation` channel of the [Crossplane Slack](https://slack.crossplane.io/).
document? Ask in the `#documentation` channel of the
[Crossplane Slack](https://slack.crossplane.io/).
{{< /hint >}}
### Front matter
Each page contains metadata called [front matter](https://gohugo.io/content-management/front-matter/). Each page requires front matter to render.
Each page contains metadata called
[front matter](https://gohugo.io/content-management/front-matter/). Each page
requires front matter to render.
```yaml
---
@ -103,9 +108,36 @@ weight: 610
weight pages come before higher weights in the table of contents. The value of
`weight` is otherwise arbitrary.
#### Alpha and beta features
Note features as alpha or beta in the front matter.
For alpha features set `state: alpha` and use `alphaVersion` to provide the
version that introduced the feature.
```yaml
---
title: Composition Functions
state: alpha
alphaVersion: "1.11"
---
```
For beta features set `state: beta` and use both `alhpaVersion` and
`betaVersion` to provide the version that introduced and graudated the feature.
```yaml
---
title: Composition Revisions
state: beta
alphaVersion: "1.4"
betaVersion: "1.11"
---
```
### Headings
Use standard markdown for headings (`#`). The top level heading, a single hash
(`#`) is for the page title. All content headings should be two hashes (`##`) or more.
(`#`) is for the page title. All content headings should be two hashes (`##`) or
more.
### Hiding pages
To hide a page from the left-hand navigation use `tocHidden: true` in the front

View File

@ -1,6 +1,7 @@
---
title: Composition Functions
state: alpha
alphaVersion: "1.11"
---
Composition Functions allow you to supplement or replace your Compositions with

View File

@ -1,6 +1,8 @@
---
title: Composition Revision Example
state: beta
alphaVersion: "1.4"
betaVersion: "1.11"
---
This tutorial discusses how CompositionRevisions work and how they manage Composite Resource
(XR) updates. This starts with a `Composition` and `CompositeResourceDefinition` (XRD) that defines a `MyVPC`

View File

@ -1,6 +1,8 @@
---
title: Composition Revisions
state: beta
alphaVersion: "1.4"
betaVersion: "1.11"
---
This guide discusses the use of "Composition Revisions" to safely make and roll

View File

@ -5,15 +5,30 @@
</div>
<div class="d-flex">
{{ if eq .Page.Params.state "alpha"}}
{{- if not .Page.Params.alphaVersion -}}
{{- errorf "\n\nNo \"alphaVersion\" front matter in page %q\n\n\n" .Page.File.Path -}}
{{- end -}}
This is an alpha feature.
{{ end }}
{{ if eq .Page.Params.state "beta" }}
{{- if not .Page.Params.alphaVersion -}}
{{- errorf "\n\nNo \"alphaVersion\" front matter in page %q\n\n\n" .Page.File.Path -}}
{{- end -}}
{{- if not .Page.Params.betaVersion -}}
{{- errorf "\n\nNo \"betaVersion\" front matter in page %q\n\n\n" .Page.File.Path -}}
{{- end -}}
This is a beta feature.
{{ end }}
</div>
</div>
<div class="bd-content mt-3">
<p>
This feature was introduced in v{{.Page.Params.alphaVersion}}.
{{ if eq .Page.Params.state "beta" }}
<br />
This feature graduated to beta status in v{{.Page.Params.betaVersion}}.
{{ end }}
<br /><br />
Crossplane may change or drop this feature at any time. <br />
For more information read the <a href="{{.Site.BaseURL}}knowledge-base/guides/feature-lifecycle/">Crossplane feature lifecycle</a>.
</p>

View File

@ -1,11 +0,0 @@
extends: capitalization
message: "'%s' should use sentence-style capitalization."
link: 'https://developers.google.com/style/capitalization#capitalization-in-titles-and-headings'
level: warning
scope: heading
match: $sentence
indicators:
- ':'
exceptions:
- Vale
- Kubernetes

View File

@ -13,6 +13,7 @@ exceptions:
- Cosmos
- Docker
- Emmet
- Hugo
- gRPC
- I
- Kubernetes

View File

@ -40,8 +40,6 @@ swap:
\ time"
long time no see: "I haven\u2019t seen you in a long time|it\u2019s been a long\
\ time"
master: primary|hub|reference
masters: primaries|hubs|references
mexican: Latinx
natives are becoming restless: dissatisfied|frustrated
natives are getting restless: dissatisfied|frustrated