Skip to content

Commit db61a55

Browse files
dirkgroenenJonasjanet-cangregkaczanJarosław Załucki
authored
Add initial setup for release notes (#89)
* Add initial setup * adding draft release notes for SSO * better capitalisation (I hope) * update to correct release date and number * Moving authorisation entry to Draft * Removing authorization changelog entry + correcting date for SSO entry in changelog * Updates to titles and text. Updates to titles and text to match style guide. * Added guidance in README for release notes, and templates to use. * add authorization release notes * add authorization release notes * add authorization release notes * remove .lh files * feat: Add schema evolution monitor release notes. * feat: Fix schema evo link. Co-authored-by: Jonas <[email protected]> Co-authored-by: Janet Revell <[email protected]> Co-authored-by: gregkaczan <[email protected]> Co-authored-by: Jarosław Załucki <[email protected]>
1 parent 2edc597 commit db61a55

14 files changed

+165
-18
lines changed

‎.ruby-version

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
2.7.4

‎README.md

+35-16
Original file line numberDiff line numberDiff line change
@@ -70,8 +70,8 @@ Formatting:
7070
- Use sentence case for all titles and headings.
7171
- Use H1 headings for the page title. Use H2 and H3 as subheadings. Use H4 headings to introduce example code snippets.
7272
- Never stack headings with no content between them. Add content or remove a heading, likely the latter so as to avoid adding non-essential text.
73-
- Use [bulleted lists](https://docs.splunk.com/Documentation/StyleGuide/current/StyleGuide/Bulletlists) for non-linear lists.
74-
- Use [numbered lists](https://docs.splunk.com/Documentation/StyleGuide/current/StyleGuide/Tasklists) for procedures or ordered tasks.
73+
- Use <a href="https://docs.splunk.com/Documentation/StyleGuide/current/StyleGuide/Bulletlists" target="_blank">bulleted lists</a> for non-linear lists.
74+
- Use <a href="https://docs.splunk.com/Documentation/StyleGuide/current/StyleGuide/Tasklists" target="_blank">numbered lists</a> for procedures or ordered tasks.
7575
- Use relative links to link to other files or sections in Soda documentation.
7676
- Use hard-coded links to link to external sources.
7777
- Liberally include links to the [Glossary]({% link soda/glossary.md %}), but only link the first instance of a term on a page, not all instances.
@@ -84,6 +84,19 @@ Content:
8484
- Produce content that focuses on how to achieve a goal or solve a problem and, insofar as it is practical, is inclusive of all products. Avoid creating documentation that focuses on how to use a single product. For example, instead of writing two documents -- one for "Troubleshoot Soda SQL" and one for "Troubleshoot Soda Cloud" -- write one Troubleshoot document that offers guidance for both tools.
8585
- Remember that Every Page is Page One for your reader. Most people enter your docs by clicking on the result of a Google search, so they could land anywhere and you should assume your new page is the first page that a new reader lands on. Give them the context for what they are reading, lots of "escape hatches" to the glossary or pre-requisite procedures, and instructions on what to read next in a "Go further" section at the bottom of all Concept or Task pages.
8686

87+
### Release note documentation
88+
89+
Document the details of each Soda SQL and Soda Cloud release using included release note files.
90+
91+
1. Create a new branch in this Docs repo to create your product release notes.
92+
2. To the `_release-notes` folder in this Docs repo, add a new markdown file for your new product release notes. Follow the file naming structure established by existing files.
93+
3. Copy and paste the contents of the `template-soda-cloud-rn.md` file or the `template-soda-sql-rn.md` file into your new file.
94+
4. Write your release notes using the style guide for guidance on format, language, etc.
95+
5. Spell check your content. (Copy paste to a Google Doc or your favorite editor to run a spell check.)
96+
6. Commit your changes, then create a new pull request when you are ready to publish.
97+
7. In the new pull request, request a review by @janet-can if you wish, or simply squash and merge to publish.
98+
99+
87100
### Use Jekyll markdown
88101

89102
Kramdown is the default markdown renderer that Jekyll uses.
@@ -140,29 +153,35 @@ Show code:
140153
```
141154
To keep the numbered list intact, apply endraw to the end of the line of preceding text; do not prepend with a line break.
142155

156+
Add Last modified date:
143157

144-
### Redirecting site visitors
145-
146-
The `jekyll-redirect-from` plugin is installed, allowing authors to redirect users if a page is moved.
147-
148-
See documentation: https://github.com/jekyll/jekyll-redirect-from
149-
150-
To apply a redirect, navigate to the redirect destination file, then add the following to the file metadata at the top:
151-
152-
`redirect_from: /pageyouwanttoredirect/`
153-
154-
155-
### Adding Last modified date
156158
```
157159
{% last_modified_at %}
158160
```
159161

160-
### Adding collapse-expand toggle
162+
Add collapse-expand toggle:
161163

162164
```
163165
<details>
164166
<summary>Click to expand</summary>
165167
Long content here
166168
and here
167169
</details>
168-
```
170+
```
171+
172+
Add mailto link:
173+
```
174+
<a href="mailto:[email protected]">Soda Support</a>
175+
```
176+
177+
### Redirect site visitors
178+
179+
The `jekyll-redirect-from` plugin is installed, allowing authors to redirect users if a page is moved.
180+
181+
See documentation: https://github.com/jekyll/jekyll-redirect-from
182+
183+
To apply a redirect, navigate to the redirect destination file, then add the following to the file metadata at the top:
184+
185+
`redirect_from: /pageyouwanttoredirect/`
186+
187+

‎_config.yml

+4-1
Original file line numberDiff line numberDiff line change
@@ -21,4 +21,7 @@ aux_links:
2121
"Visit Soda.io":
2222
- "//www.soda.io/"
2323

24-
aux_links_new_tab: true
24+
aux_links_new_tab: true
25+
26+
collections:
27+
- release-notes

‎_data/nav.yml

+9
Original file line numberDiff line numberDiff line change
@@ -118,3 +118,12 @@
118118
- subtitle: Support
119119
page: soda/support.md
120120

121+
- title: Release notes
122+
page: release-notes/all.md
123+
subcategories:
124+
- subtitle: Soda products
125+
page: release-notes/all.md
126+
- subtitle: Soda Cloud
127+
page: release-notes/soda-cloud.md
128+
- subtitle: Soda SQL
129+
page: release-notes/soda-sql.md

‎_release-notes/authorization.md

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
---
2+
name: Roles and rights in Soda Cloud
3+
date: 2021-09-30
4+
products:
5+
- soda-cloud
6+
---
7+
Role-based user access control support is now available for Soda Cloud.
8+
Read the [Roles and rights docs]({% link soda-cloud/roles-and-rights.md %}) to learn more.

‎_release-notes/schema-evolution-monitor.md

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
name: Schema Evolution Monitor in Soda Cloud
3+
date: 2021-10-14
4+
products:
5+
- soda-cloud
6+
---
7+
New monitor type "Schema Evolution" is now available for Soda Cloud. Read the [Schema evolution monitor docs]({% link soda-cloud/schema-evolution.md %}) to learn more.

‎_release-notes/soda-sql-v2.1.0b16.md

+16
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
---
2+
name: "Week 36: Celeborn"
3+
date: 2021-09-07
4+
products:
5+
- soda-sql
6+
---
7+
8+
- Core: fix time option as it's always set to "now" by default
9+
- Core: Update dev requirements
10+
- Core: Update readme with dialect status (#477)
11+
- Core: Update Tox in dev requirements to prevent version deadlock (#474)
12+
- BigQuery: fix NoneType issue when credentials are not sufficient for BigQuery (#472)
13+
- BigQuery: Update bigquery dependency version (#470)
14+
- MySQL: Fix MySQL dialect issues (#475)
15+
16+
Refer to the <a href="https://github.com/sodadata/soda-sql/blob/main/CHANGELOG.md#210b16---2021-09-07-celeborn" target="_blank">Soda SQL Changelog</a> for details.

‎_release-notes/sso-okta-and-azure.md

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
name: Single sign-on (SSO) with Soda Cloud
3+
date: 2021-09-28
4+
products:
5+
- soda-cloud
6+
---
7+
Single sign-on support is now available for Soda Cloud with SAML 2.0 Identity Providers (IdP), Okta and Azure AD. Contact <a href="mailto:[email protected]">Soda Support</a> to set up Soda Cloud as a service provider in your SSO IdP so that users in your organization must log in to Soda Cloud via the IdP. Read the [Single sign-on docs]({% link soda-cloud/sso.md %}) to learn more about activating and using SSO with Soda Cloud.

‎release-notes/all.md

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
---
2+
layout: default
3+
title: Release notes
4+
parent: Release notes
5+
---
6+
7+
# Release notes for Soda products
8+
9+
{% assign notes = site.release-notes | sort:"date" | reverse %}
10+
{% for release-note in notes %}
11+
<h2>[{{ release-note.products | join:', ' }}] {{ release-note.name }}</h2>
12+
<sup>{{ release-note.date | date_to_long_string }}</sup>
13+
{{ release-note.content }}
14+
<hr/>
15+
{% endfor %}
16+
17+
*Last modified on {% last_modified_at %}*

‎release-notes/soda-cloud.md

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
---
2+
layout: default
3+
title: Release notes for Soda Cloud
4+
parent: Release notes
5+
---
6+
7+
# Release notes for Soda Cloud
8+
9+
{% assign notes = site.release-notes | where_exp:"item","item.products contains 'soda-cloud'" | sort:"date" | reverse %}
10+
{% for release-note in notes %}
11+
<h2>[{{ release-note.products | join:', ' }}] {{ release-note.name }}</h2>
12+
<sup>{{ release-note.date | date_to_long_string }}</sup>
13+
{{ release-note.content }}
14+
<hr/>
15+
{% endfor %}
16+
17+
*Last modified on {% last_modified_at %}*

‎release-notes/soda-sql.md

+16
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
---
2+
layout: default
3+
title: Release notes for Soda SQL
4+
parent: Release notes
5+
---
6+
7+
# Release notes for Soda SQL
8+
{% assign notes = site.release-notes | where_exp:"item","item.products contains 'soda-sql'" | sort:"date" | reverse %}
9+
{% for release-note in notes %}
10+
<h2>[{{ release-note.products | join:', ' }}] {{ release-note.name }}</h2>
11+
<sup>{{ release-note.date | date_to_long_string }}</sup>
12+
{{ release-note.content }}
13+
<hr/>
14+
{% endfor %}
15+
16+
*Last modified on {% last_modified_at %}*

‎soda/product-overview.md

+2-1
Original file line numberDiff line numberDiff line change
@@ -54,10 +54,11 @@ Get started with the [Quick start tutorial for Soda Cloud]({% link soda-cloud/qu
5454
|Configure scan YAML to send <br />[failed row samples]({% link soda-sql/send-failed-rows.md %}) to Soda Cloud | Use a missing value metric type to [collect failed row samples]({% link soda-cloud/failed-rows.md %}#use-a-missing-value-metric-type-to-collect-failed-row-samples)|
5555
| | View [failed rows]({% link soda-cloud/failed-rows.md %}) |
5656
| Configure scan YAML to send <br />[sample dataset data]({% link soda-sql/samples.md %}) to Soda Cloud | [Enable sample data]({% link soda-cloud/display-samples.md %}) for a dataset |
57-
| | View sample data for a dataset |
57+
| | View [sample data]({% link soda-cloud/display-samples.md %}) for a dataset |
5858
| | [Disable sending all sample data]({% link soda-cloud/display-samples.md %}#disable-sample-data) to Soda Cloud |
5959
| | Use [anomaly detection]({% link soda-cloud/anomaly-detection.md %}) |
6060
| | [Collaborate]({% link soda-cloud/collaborate.md %}) with your team to monitor your data: invite team members, and integrate with Slack
61+
| | Set up [Single sign-on for Soda Cloud]({% link soda-cloud/sso.md %}) so that all users in your organization must use your IdP to access Soda Cloud. |
6162
| | Manage [user access]({% link soda-cloud/roles-and-rights.md %}) to your organization and its datasets. |
6263

6364
## Go further

‎template-soda-cloud-rn.md

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
name: "Feature or release name"
3+
date: YYYY-MM-DD
4+
products:
5+
- soda-cloud
6+
---
7+
8+
Feature description
9+
10+
OR
11+
12+
- change or new item
13+
- change or new item
14+
- change or new item

‎template-soda-sql-rn.md

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
---
2+
name: "Week XX: Name of release"
3+
date: YYYY-MM-DD
4+
products:
5+
- soda-sql
6+
---
7+
8+
- change or new item
9+
- change or new item
10+
- change or new item
11+
12+
Refer to the <a href="https://github.com/sodadata/soda-sql/blob/main/CHANGELOG.md" target="_blank">Soda SQL Changelog</a> for details.

0 commit comments

Comments
 (0)