docs(book): include PRQL changelog in book #2348

eitsupi · 2023-03-30T04:05:52Z

Since prql code blocks in md files included in the Book will evaluated and replace with html, this PR introduce a new Option no-eval that modifies the Book preprocessor to not evaluate Changelog's prql code blocks.
Also add a pre-commit hook to avoid using bare prql code blocks on CHANGELOG.md.

…xecuting

max-sixty · 2023-03-30T04:15:59Z

CHANGELOG.md

@@ -233,17 +233,21 @@ This release has 74 commits from 12 contributors. Selected changes:
  formats. _format-arg_ can be `format:csv` or `format:json`. _string-arg_ can
  be a string in any format. (@aljazerzen & @snth, #1514)

-  ```prql
+  ```elm


Should these never be prql?

Maybe we add a grep lint in pre-commit if so; otherwise folks are going to forget?

Or are they OK / actually good in prql?

Thank you for your review.
The problem here is that in the book the prql code blocks are evaluated by the preprocessor and displayed alongside the sql code blocks.

If we could disable the evaluation of prql code blocks throughout the particular file with ignore settings, special comments or yaml front matter, I think we could continue to use prql code blocks there.
Is that possible now?

Maybe we add a grep lint in pre-commit if so; otherwise folks are going to forget?

I did not know of a solution that would make that possible. This is a good method at this stage!

prql_no_test will skip over creating a comparison table: https://github.com/prql/prql/blob/13d0060dfe80ee3ab098b85207ef6fae9d367a55/web/book/src/lib.rs#L155

(Though do we sometimes want a comparison table?)

I think the issue here is the gap between rendering on GitHub and rendering on Book.
That is, if prql code blocks are recognized on GitHub in the future (#1636), Changelog will need to use prql code blocks, but may not want to output sql on the Book.

Considering that the syntax has changed and past prql code block can no longer be compiled, Changelog still needs to disable prql code evaluation on a file-by-file basis.

Yes, I actually thought I'd make a change to use a list, quick PR at https://github.com/PRQL/prql/pull/2350/files

(doesn't affect this PR though)

Wow, wonderfully fast work, thanks!
So can we merge this PR now?

What should the instructions for including change blocks here be? "Always use elm"? "Only use prql if you want a comparison table"?

What should the instructions for including change blocks here be? "Always use elm"? "Only use prql if you want a comparison table"?

Good point.

It seems we need to stay with elm for now.
For now, it seems that when the prql code block is evaluated, a header PRQL is added and the display is corrupted.

prql/CHANGELOG.md

Lines 315 to 327 in fe1b7d4

- _Experimental:_ The

[`case`](https://prql-lang.org/book/language-features/case.html) function sets

a variable to a value based on one of several expressions (@aljazerzen,

#1278).

```prql

derive var = case [

score <= 10 -> "low",

score <= 30 -> "medium",

score <= 70 -> "high",

true -> "very high",

]

```

max-sixty · 2023-03-30T04:45:20Z

One thing we want to avoid here is:

Someone adds an entry to the Changelog with a prql block; the code doesn't compile
This is only picked up when building the book, not in the book tests, since the book tests only look at the .md files in the book. We run the book tests every commit, but we only build the book in build-web
Then build-web fails next time someone makes a small change to the web because of that issue, and we have to unravel what caused it, and we're reverting big PRs because of a small changelog problem.

We could run build-web on changes to the changelog; I think that would solve it

Idea from PRQL#2348

* refactor: Use tags for the language code blocks Idea from #2348 * change to spaces

…elm`

eitsupi · 2023-03-31T11:05:59Z

I added no-eval tag to skip evaluate the code block in 9e89bbb.
This should work the same way as the elm on the book, so it can be used as a perfect replacement for the elm code block.
(Of course, we could continue to use elm.)

max-sixty · 2023-03-31T17:09:34Z

Perfect!

Should we also add a https://pre-commit.com/#pygrep so no one puts a prql$ tag in the Changelog?

This reverts commit de5c5ff.

eitsupi · 2023-04-01T04:31:23Z

Should we also add a pre-commit.com/#pygrep so no one puts a prql$ tag in the Changelog?

I added that in 8347d17 and it seems working fine de5c5ff

eitsupi · 2023-04-01T06:03:05Z

It would be great if we could automatically link to issue numbers and GitHub user accounts like pkgdown does (https://pkgdown.r-lib.org/news/index.html), but my skills are not currently up to the task of implementing this...
https://github.com/r-lib/pkgdown/blob/c354aa7e5ea1f9936692494c28c89e5bdd31fc68/R/repo.R#L39-L46

.pre-commit-config.yaml

for more information, see https://pre-commit.ci

max-sixty · 2023-04-02T00:35:53Z

It would be great if we could automatically link to issue numbers and GitHub user accounts like pkgdown does (https://pkgdown.r-lib.org/news/index.html), but my skills are not currently up to the task of implementing this... https://github.com/r-lib/pkgdown/blob/c354aa7e5ea1f9936692494c28c89e5bdd31fc68/R/repo.R#L39-L46

Yes totally. A challenge for the future (...generations...)!

max-sixty · 2023-04-02T00:36:22Z

I hit the button to get this in for 0.7.0, hope that's OK!

max-sixty · 2023-04-02T00:54:31Z

In! Thanks @eitsupi !

eitsupi · 2023-04-02T01:21:14Z

Thanks!

* refactor: Use tags for the language code blocks Idea from PRQL#2348 * change to spaces

Close PRQL#2344 Since `prql` code blocks in md files included in the Book will evaluated and replace with html, this PR introduce a new Option `no-eval` that modifies the Book preprocessor to not evaluate Changelog's `prql` code blocks. Also add a pre-commit hook to avoid using bare `prql` code blocks on `CHANGELOG.md`. --------- Co-authored-by: Maximilian Roos <5635139+max-sixty@users.noreply.github.com> Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

eitsupi added 2 commits March 30, 2023 03:59

docs(book): include changelog in book

6058a7e

docs: use elm instead of prql in changelog code blocks to avoid e…

7819b39

…xecuting

max-sixty reviewed Mar 30, 2023

View reviewed changes

ci: web may includes md files out of web sub dir

f34d144

max-sixty added a commit to max-sixty/prql that referenced this pull request Mar 30, 2023

refactor: Use tags for the language code blocks

3224e86

Idea from PRQL#2348

max-sixty mentioned this pull request Mar 30, 2023

refactor: Use tags for the language code blocks #2350

Merged

max-sixty added a commit that referenced this pull request Mar 30, 2023

refactor: Use tags for the language code blocks (#2350)

8d46f6b

* refactor: Use tags for the language code blocks Idea from #2348 * change to spaces

eitsupi added 2 commits March 31, 2023 10:17

Merge branch 'main' into changelog-in-book

c4ee1d3

docs: use prql no-eval code blocks to prql code blocks instead of `…

9e89bbb

…elm`

eitsupi added 4 commits April 1, 2023 13:27

ci: pre-commit config for preventing prql code block commit in changelog

8347d17

chore: temporarily change for testing pre-commit hook

de5c5ff

Revert "chore: temporarily change for testing pre-commit hook"

12e5f44

This reverts commit de5c5ff.

Merge branch 'main' into changelog-in-book

74ee4d2

eitsupi requested a review from max-sixty April 2, 2023 00:32

max-sixty reviewed Apr 2, 2023

View reviewed changes

.pre-commit-config.yaml Outdated Show resolved Hide resolved

max-sixty and others added 2 commits April 1, 2023 17:34

Update .pre-commit-config.yaml

05fbf90

[pre-commit.ci] auto fixes from pre-commit.com hooks

30579be

for more information, see https://pre-commit.ci

max-sixty enabled auto-merge (squash) April 2, 2023 00:36

max-sixty merged commit 2125923 into PRQL:main Apr 2, 2023

eitsupi deleted the changelog-in-book branch April 2, 2023 03:21

max-sixty added a commit to max-sixty/prql that referenced this pull request Apr 2, 2023

refactor: Use tags for the language code blocks (PRQL#2350)

3aa52a8

* refactor: Use tags for the language code blocks Idea from PRQL#2348 * change to spaces

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(book): include PRQL changelog in book #2348

docs(book): include PRQL changelog in book #2348

eitsupi commented Mar 30, 2023 •

edited

Loading

max-sixty Mar 30, 2023

eitsupi Mar 30, 2023

max-sixty Mar 30, 2023

eitsupi Mar 30, 2023

eitsupi Mar 30, 2023

max-sixty Mar 30, 2023

eitsupi Mar 30, 2023

max-sixty Mar 30, 2023

max-sixty Mar 30, 2023

eitsupi Mar 31, 2023

max-sixty commented Mar 30, 2023 •

edited

Loading

eitsupi commented Mar 31, 2023

max-sixty commented Mar 31, 2023

eitsupi commented Apr 1, 2023

eitsupi commented Apr 1, 2023

max-sixty commented Apr 2, 2023

max-sixty commented Apr 2, 2023

max-sixty commented Apr 2, 2023

eitsupi commented Apr 2, 2023

	- _Experimental:_ The
	[`case`](https://prql-lang.org/book/language-features/case.html) function sets
	a variable to a value based on one of several expressions (@aljazerzen,
	#1278).

	```prql
	derive var = case [
	score <= 10 -> "low",
	score <= 30 -> "medium",
	score <= 70 -> "high",
	true -> "very high",
	]
	```

docs(book): include PRQL changelog in book #2348

docs(book): include PRQL changelog in book #2348

Conversation

eitsupi commented Mar 30, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

max-sixty commented Mar 30, 2023 • edited Loading

eitsupi commented Mar 31, 2023

max-sixty commented Mar 31, 2023

eitsupi commented Apr 1, 2023

eitsupi commented Apr 1, 2023

max-sixty commented Apr 2, 2023

max-sixty commented Apr 2, 2023

max-sixty commented Apr 2, 2023

eitsupi commented Apr 2, 2023

eitsupi commented Mar 30, 2023 •

edited

Loading

max-sixty commented Mar 30, 2023 •

edited

Loading