CI: Add release workflow for staging the Python package through GHA to PyPI

.github/workflows/release.yml

@@ -0,0 +1,36 @@
+---
+name: Release
+
+on: push
+
+jobs:
+  pypi:
+    name: Build and publish package to PyPI
+    runs-on: ubuntu-latest
+    if: startsWith(github.event.ref, 'refs/tags')
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Generate grammar
+        run: |
+          python -m pip install -r requirements.txt
+          poe generate
+
+      - name: Build package
+        run: |
+          python -m pip install build twine
+          cd cratedb_sqlparse_py
+          python -m build
+          twine check dist/{*.tar.gz,*.whl}
+
+      - name: Publish package to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: cratedb_sqlparse_py/dist/
+          user: __token__
+          password: ${{ secrets.PYPI_API_TOKEN }}

DEVELOP.md

@@ -0,0 +1,125 @@
+# Developer Guide for cratedb-sqlparse
+
+About building locally, or using a different CrateDB version.
+
+> The generated parser is not uploaded to the repository because it is huge.
+> To use the package locally or to build a different version use the build script.
+
+## Setup
+
+To start things off, bootstrap the sandbox environment.
+
+### Acquire sources
+```shell
+git clone [email protected]:crate/cratedb-sqlparse.git
+cd cratedb-sqlparse
+```
+
+### Install dependencies
+```
+pip install -r requirements.txt
+```
+
+### Generate grammar files
+```shell
+poe generate
+```
+
+
+## Running Tests for Python
+
+First, navigate to the corresponding subdirectory:
+
+    cd cratedb_sqlparse_py
+
+Verify code by running all linters and software tests:
+
+    poe check
+
+Run specific tests:
+
+    pytest -k enricher
+    pytest -k lexer
+
+Format code:
+
+    poe format
+
+
+## Running Tests for JavaScript
+
+First, navigate to the corresponding subdirectory:
+
+    cd cratedb_sqlparse_js
+
+Set up project:
+
+    npm install
+
+Verify code by running all linters and software tests:
+
+    npm test
+
+Run specific tests:
+
+    ???
+
+Format code:
+
+    ???
+
+
+
+## Running a Release
+
+### Python
+
+Overview:
+- Versioning happens automatically based on the `versioningit` package.
+  You just need to tag the repository.
+- Package building and publishing happens automatically, being staged
+  through GHA to PyPI.
+
+On branch `main`:
+- Add a section for the new version in the `CHANGES.md` file.
+- Commit your changes with a message like `Release vx.y.z`.
+- Create a tag, and push to remote.
+  This will trigger a GitHub action which releases the new version to PyPI.
+  ```shell
+  git tag v0.0.3
+  git push --tags
+  ```
+- On GitHub, designate a new release, copying in the relevant section
+  from the CHANGELOG.
+  https://github.com/crate/cratedb-sqlparse/releases
+
+Optionally, build the package and upload to PyPI manually.
+```shell
+poe release
+```
+
+
+### JavaScript
+
+Overview:
+- Versioning happens manually on behalf of the `package.json` file.
+- Package building and publishing to npmjs.com happens manually, using
+  the `npm` program.
+
+On branch `main`:
+- Make sure to run `poe generate` on the root folder first.
+- Adjust version number in `package.json`.
+- Generate `package-lock.json`.
+
+      npm install --package-lock-only
+
+- Commit your changes with a message like `Release vx.y.z`.
+- Create a tag, and push to remote.
+- Build package.
+
+      npm run build
+
+- Publish package.
+
+      npm login
+      npm publish

README.md

@@ -11,7 +11,27 @@ These libraries allow you to parse Crate's SQL dialect without sending it to a C
 - `Python`: https://github.com/crate/cratedb-sqlparse/tree/main/cratedb_sqlparse_py
 - `Javascript`: https://github.com/crate/cratedb-sqlparse/tree/main/cratedb_sqlparse_js
 
-## Example:
+
+## Install
+
+You can install the package in both its Python and JavaScript variants.
+
+- https://pypi.org/project/cratedb-sqlparse/
+- https://www.npmjs.com/package/@cratedb/cratedb-sqlparse
+
+### Python
+
+```shell
+pip install cratedb-sqlparse
+```
+
+### JavaScript
+```shell
+npm install @cratedb/cratedb-sqlparse
+```
+
+
+## Synopsis
 
 ```python
 from cratedb_sqlparse import sqlparse
@@ -49,23 +69,8 @@ exceptions as error listener, dollar-strings and any new one. See past commits t
 implemented in Python and Javascript, remember that [CrateDB'S SQLParser](https://github.com/crate/crate/tree/master/libs/sql-parser/src/main/java/io/crate/sql/parser) written in Java is the most
 complete and the default reference.
 
-## Building locally & using a different CrateDB version
-
-The generated parser is not uploaded to the repository since it's huge, to use the package locally or
-to build a different version use the build script.
-
-### Acquire sources
-```shell
-git clone [email protected]:crate/cratedb-sqlparse.git
-cd cratedb-sqlparse
-```
-
-### Install dependencies
-```
-pip install -r requirements.txt
-```
+## Development
 
-### Generate grammar files
-```shell
-poe generate
-```
+The generated parser is not uploaded to the repository because it is huge.
+To use the package locally or to build a different version use the build script.
+Further information can be found in the [developer guide](DEVELOP.md).