Merge pull request #58 from chkware/docs/update-zipapp

Docs/update zipapp

Author: 0hsn

.github/workflows/deploy.yml

@@ -16,10 +16,10 @@ jobs:
       - name: Set up Node
         uses: actions/setup-node@v3
         with:
-          node-version: 16.x
+          node-version: 18.x
 
       - name: Cache dependencies
-        uses: actions/cache@v2
+        uses: actions/cache@v3
         with:
           path: |
             **/node_modules

.github/workflows/test-deploy.yml

@@ -16,10 +16,10 @@ jobs:
       - name: Set up Node
         uses: actions/setup-node@v3
         with:
-          node-version: 16.x
+          node-version: 18.x
 
       - name: Cache dependencies
-        uses: actions/cache@v2
+        uses: actions/cache@v3
         with:
           path: |
             **/node_modules

docs/introduction.md

@@ -4,17 +4,17 @@ title: Introduction
 
 ![CHKware | Low-code API quality testing, and automation toolbox](./assets/github-hero-01.png)
 
-
 *CHKware* (pronounced as */check:ware/*) is a low-code API testing tool, a script-able HTTP client, and an API test automation tool for the API era.
 
 It is available as a command-line application. You write test specification files in a [YAML](https://yaml.org/)-based [DSL](https://en.wikipedia.org/wiki/Domain-specific_language). In that specification file you will define some structured configurations to be used for the following purpose:
 
-- Create reusable http request specification. [alpha]
-- Create reusable test specifications. [alpha]
+- Create reusable http request specification.
+- Create reusable test specifications.
 
 Afterward, you run those test specification files with *CHKware*, and get test results or even reuse them.
 
 ---
+
 ### Motivation
 
 In today's world, API is one of the key fuels that drive business. It is the way web applications consume services from self-hosted or 3rd-party vendors. Recent technology movements are going to a fluid internet direction, where *vendor_A* have one API, *vendor_B* is another API provider, while we are the consumers (e-commerce, fin-tech) of those vendor APIs. We use those APIs to host our contents based on those APIs. Maybe we are *vendor_U* hosting more complex APIs on top of those. So, with the upcoming complexity of integration we need better tooling for API testing. Testing tools for modularize api testing.
@@ -63,5 +63,5 @@ There is no native binary dependency, therefore it is expected on all the platfo
 
 Command name | Specification document | Stability
 ---|---|---
-`http`| Http | _alpha_
-`testcase`| Testcase | _alpha_
+`chk http`| Http | *alpha*
+`chk testcase`| Testcase | *alpha*

docs/setup.md

@@ -23,3 +23,5 @@ pipx upgrade chk
 ```
 
 Otherwise, if _pip_ was used to install then same process given above should work for upgrade as well.
+
+Alternatively, chkware tool can be build and use as a zipapp, [following this instruction](/setup/build-zipapp).

docs/setup/build-wheel.md

@@ -0,0 +1,74 @@
+---
+title: Pypi release process
+---
+
+Follow the steps to do a manual release on PyPi.
+
+- Please confirm that [Python 3.11.x](https://www.python.org/downloads) with [Pipenv](https://pipenv.pypa.io/en/latest/#install-pipenv-today) is installed and setup on this machine
+
+- Clone the repo
+
+    ```bash
+    git clone https://github.com/chkware/cli.git cli-wheel
+    ```
+
+- Change to the directory
+
+    ```bash
+    cd cli-wheel
+    ```
+
+- Update version number on `setup.cfg`
+
+    ```ini
+    version = 0.X.X
+    ```
+
+- Update version number on `chk/console/main.py`
+
+    ```python
+    """v0.X.X | supported version strings: 0.7.2, ..."""
+    ```
+
+- Update *docs/CHANGELOG.md* with the release *0.X.X* information
+
+- Make directory for local *virtualenv* setup
+
+    ```bash
+    mkdir ./.venv
+    ```
+
+- Install all required packages
+
+    ```bash
+    pipenv install
+    ```
+
+- Install all required packages for build and push to PyPI
+
+    ```bash
+    pipenv run pip install -U build twine
+    ```
+
+- Use the environment's python to build
+
+    ```bash
+    pipenv run python -m build --wheel --sdist
+    ```
+
+- Push the packages to PyPi. This setup will require your PyPi username and password. So, make sure to setup an account, and have permission to push setup ready on the `chk` package repository.
+
+    ```bash
+    pipenv run twine upload dist/*
+    ```
+
+- Publish and push an annotated tag
+
+    ```bash
+    git tag -a v0.X.X -m "..."
+    git push -u origin v0.X.X
+    ```
+
+- [_OPTIONAL_] [build a zipapp](build-zipapp.md), and release a version
+
+A new version is release.

docs/setup/build-zipapp.md

@@ -0,0 +1,63 @@
+---
+title: Build cli zipapp
+---
+
+CHKware `zipapp` is a self contained executable alike utility that once build can be used from anywhere. However, it have python version dependency.
+
+Follow these steps to bundle `chkware` as [zipapp](https://docs.python.org/3/library/zipapp.html).
+
+- Please confirm that [Python 3.11.x](https://www.python.org/downloads) is installed and setup on this machine
+
+- Clone the repo
+
+    ```bash
+    git clone https://github.com/chkware/cli.git cli-zip
+    ```
+  
+- Change to the directory
+
+    ```bash
+    cd cli-zip
+    ```
+
+- Make directory for local _virtualenv_ setup
+
+    ```bash
+    python -m venv .venv
+    ```
+
+- Switch to the _virtualenv_
+
+    ```bash
+    source .venv/bin/activate
+    ```
+
+    or on windows
+
+    ```bash
+    .venv/Scripts/activate.bat
+    ```
+
+- Install all required packages
+
+    ```bash
+    pip install -U -r requirements.txt
+    ```
+
+- Install shiv for building the zipapp
+
+    ```bash
+    pip install -U shiv
+    ```
+  
+- Use the environment's python to build the zipapp. Refer to shiv [documentation](https://shiv.readthedocs.io/en/latest/#:~:text=let%E2%80%99s%20break%20this%20command%20down%2C) for further explanation.
+
+    ```bash
+    python -m shiv -c chk -o chk.pyz .
+    ```
+
+- `chk.pyz` is generated in the project folder. You can move it to anywhere on your machine, and put it on your machine's environment variable or `$PATH`. Then, use it as follows:
+
+    ```bash
+    chk.pyz http tests/resources/storage/sample_config/xkcd-joke.chk
+    ```