From 1915dfa447186fdb85fa8f335176275ca76afaed Mon Sep 17 00:00:00 2001 From: David Lurton Date: Wed, 23 Sep 2020 17:10:03 -0700 Subject: [PATCH 1/6] more revisions --- psr/README-PSR.md | 24 +++++++++++++++++------- 1 file changed, 17 insertions(+), 7 deletions(-) diff --git a/psr/README-PSR.md b/psr/README-PSR.md index 6a77a48..f317402 100644 --- a/psr/README-PSR.md +++ b/psr/README-PSR.md @@ -12,12 +12,18 @@ would be: However, this doesn't always work out so well because: - It is often difficult to precisely specify new features if there is no prototype to prove the -proposed behavior is implementable or desirable. Some experimentation may be required in order -to know the best way for a new feature to be implemented. -- The time and resources of the PartiQL steering committee may not be immediately available to review -every proposal in depth, and to re-review as changes to the proposed features are discovered during -implementation. -- There may not be enough time to update the specification before delivery of a new feature. + proposed behavior is implementable or desirable, forcing the implementation to deviate slightly (or significantly) + from the specification. Some experimentation and prototyping may be required in order + to know the best way for a new feature to be implemented. +- Since the individual or team defining the new feature may not always be the same as the one implementing it, + some intermediate and lightweight way to specify a feature should be should exist. This intermediate + specification does not need to be written to the same level of detail that would be required for the official + specification. Indeed, some of those details may not even be known yet and will not be discovered until + after feature has been added to the reference implementation. +- The time and resources of the PartiQL steering committee may not be immediately available to review + every proposal in depth, and to re-review as changes to the proposed features are discovered during + implementation. + - There may not be enough time to update the specification before delivery of a new feature. To address these concerns, I would like to propose that we adopt a process for revising the specification. @@ -33,7 +39,11 @@ PartiQL specification. They exist as documents that reside in the - Clarify any ambiguous part of the specification (Only if clarification results in changes to the reference implementation. If no changes to the reference implementation are needed then a standard GitHub PR should be submitted. -PSRs may be submitted by any party. +#### Notes about PSRs: + +- PSRs may be submitted by any party. +- The PartiQL steering committee will only need to review the final revision of the PSR and *may* be more involved +with some of the PSRs than others. ### PSR Process From 0c4fb597e63697fb389025850db3179638b50641 Mon Sep 17 00:00:00 2001 From: David Lurton Date: Thu, 1 Oct 2020 13:56:26 -0700 Subject: [PATCH 2/6] WIP that I might have to roll back --- common/macros.tex | 17 ++++++++++++++ {spec => common}/preamble.tex | 0 psr/PSR-0001-LET-in-FROM-clause.tex | 35 +++++++++++++++++++++++++++++ psr/README-PSR.md | 19 ++++++++++++---- spec/main.tex | 15 ++----------- 5 files changed, 69 insertions(+), 17 deletions(-) create mode 100644 common/macros.tex rename {spec => common}/preamble.tex (100%) create mode 100644 psr/PSR-0001-LET-in-FROM-clause.tex diff --git a/common/macros.tex b/common/macros.tex new file mode 100644 index 0000000..4d705d4 --- /dev/null +++ b/common/macros.tex @@ -0,0 +1,17 @@ + +\newcommand{\TRUE}{\gl{TRUE}\xspace} +\newcommand{\FALSE}{\gl{FALSE}\xspace} +\newcommand{\NULL}{\gl{NULL}\xspace} +\newcommand{\MISSING}{\gl{MISSING}\xspace} + + +\newcommand{\ionquote}[1]{\gl{\bt} #1 \gl{\bt}} + + +% MODEL definitions +\newcommand{\bt}{\texttt{\`}} +\newcommand{\ob}{<\!\!<} +\newcommand{\cb}{>\!\!>} +\newcommand{\out}{\{-} +\newcommand{\cut}{-\}} + diff --git a/spec/preamble.tex b/common/preamble.tex similarity index 100% rename from spec/preamble.tex rename to common/preamble.tex diff --git a/psr/PSR-0001-LET-in-FROM-clause.tex b/psr/PSR-0001-LET-in-FROM-clause.tex new file mode 100644 index 0000000..ac1bf9d --- /dev/null +++ b/psr/PSR-0001-LET-in-FROM-clause.tex @@ -0,0 +1,35 @@ +\documentclass{article} +\input{../common/preamble} +\input{../common/macros} + +\begin{document} +\section{LET in SELECT clauses} + + +\begin{figure}[ht!] + \centering + \begin{tabular}{|r|lrl|} + \hline + 1 & \gn{value} & \gp & \gn{absent\_value} \\ + 2 & & \gd & \gn{scalar\_value} \\ + 3 & & \gd & \gn{tuple\_value} \\ + 4 & & \gd & \gn{collection\_value} \\ + 5 & \gn{absent\_value} & \gp & \NULL \\ + 6 & & \gd & \MISSING \\ + 7 & \gn{scalar\_value} & \gp & \ionquote{\gs{ion\_literal}} \\ + 8 & & \gd & \gs{sql\_literal} \\ + 9 & \gn{tuple\_value} & \gp & \gl{\{\ \}} \\ + 10 & & \gd & \gl{\{} \gs{string\_value} \gl{:} \gn{value} (\gl{,} \gs{string\_value} \gl{:} \gn{value})* \gl{\}} \\ + 11 & & & \ \ \ \ \ \ \ \gn{value} cannot be \MISSING \\ + 12 & \gn{collection\_value} & \gp & \gn{array\_value} \\ + 13 & & \gd & \gn{bag\_value} \\ + 14 & \gn{array\_value} & \gp & \gl{[} (\gn{value} (\gl{,} \gn{value})*)? \gl{]} \\ + 15 & \gn{bag\_value} & \gp & \gl{\ob} (\gn{value} (\gl{,} \gn{value})*)? \gl{\cb} \\ + \hline + \end{tabular} + \caption{BNF Grammar for PartiQL Values} + \label{figure:values:bnf} +\end{figure} + +\end{document} + diff --git a/psr/README-PSR.md b/psr/README-PSR.md index f317402..1423b01 100644 --- a/psr/README-PSR.md +++ b/psr/README-PSR.md @@ -1,7 +1,12 @@ +# A Proposal for Proposing Specification Changes +## Definitons -A Proposal for Proposing Specification Changes +- `PartiQL Implementation`: an implementation of the partiql language such as the +[reference implementation](https://github.com/partiql/partiql-lang-kotlin/). +- `PartiQL service`: a component that combines PartiQL with data sources +## Background In an ideal world when a new feature is added to the PartiQL language the process for doing so would be: @@ -13,19 +18,19 @@ However, this doesn't always work out so well because: - It is often difficult to precisely specify new features if there is no prototype to prove the proposed behavior is implementable or desirable, forcing the implementation to deviate slightly (or significantly) - from the specification. Some experimentation and prototyping may be required in order + from the original proposal. Some experimentation and prototyping may be required in order to know the best way for a new feature to be implemented. - Since the individual or team defining the new feature may not always be the same as the one implementing it, some intermediate and lightweight way to specify a feature should be should exist. This intermediate specification does not need to be written to the same level of detail that would be required for the official specification. Indeed, some of those details may not even be known yet and will not be discovered until after feature has been added to the reference implementation. +- There may not be enough time to update the specification before delivery of a new feature. - The time and resources of the PartiQL steering committee may not be immediately available to review every proposal in depth, and to re-review as changes to the proposed features are discovered during implementation. - - There may not be enough time to update the specification before delivery of a new feature. -To address these concerns, I would like to propose that we adopt a process for revising the specification. +To address these concerns, we propose to adopt a process for revising the specification. ### PartiQL Specification Requests @@ -47,6 +52,12 @@ with some of the PSRs than others. ### PSR Process +- A PSR is added in the form of a LaTeX document that describes the new feature to the `psr` directory of the +specification repository. (Submit a pull request.) +- When first implemented by the PariQL reference implementation, the feature should be disabled by default. This +allows PartiQL services to use the reference implementation that contains experimental features without risking end-users +taking dependencies on features that aren't fully formalized + ![PSR Flowchar](psr.jpeg)