From 4b674ca47ffa08d774f87ee11d3b73ce9fc9b8d6 Mon Sep 17 00:00:00 2001 From: Fabio Pliger Date: Wed, 30 Apr 2025 15:10:06 -0500 Subject: [PATCH 1/7] add more details around installing on virtualenv or conda environments --- CONTRIBUTING.md | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 27f6efe..4e614bf 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -14,14 +14,29 @@ git clone https://github.com/pyscript/pyscript.git pip install --upgrade pip ``` -Make a virtualenv and activate it: +Create a local enviroment with your enviroment manager of choice. + +### Virtualenv + +In case you choose Virtualenv, make a virtualenv and activate it using the following commands: ```shell python -m venv .venv source .venv/bin/activate ``` -Install your local enviroment dependencies +### Conda + +In case you choose to use conda, use the following commands: + +```shell +conda create -n pyscript-cli python +conda activate pyscript-cli +``` + +### Installation + +Now that you have your environment set up and activated, install your local enviroment dependencies ```shell pip install -e ".[dev]" From 198a7c8da55c9ca9d67d38ea813e2e2311d1df3e Mon Sep 17 00:00:00 2001 From: Fabio Pliger Date: Wed, 30 Apr 2025 17:03:28 -0500 Subject: [PATCH 2/7] add instructions to run the pyscript command in dev --- CONTRIBUTING.md | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4e614bf..c7cf2b4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -54,6 +54,37 @@ After setting up your developer enviroment, you can run the tests with the follo pytest . ``` +# Running CLI Commands + +Once the installation process is done, the `pyscript` CLI is avaible to be used once the environment has been +activated. Simply run `pyscript` with the appropriate command. For instance, to see the list of commands: + +```shell +>> pyscript --help + + Usage: pyscript [OPTIONS] COMMAND [ARGS]... + + Command Line Interface for PyScript. + +╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ +│ --version Show project version and exit. │ +│ --help Show this message and exit. │ +╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Commands ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ +│ create Create a new pyscript project with the passed in name, creating a new directory in the current directory. Alternatively, use `--wrap` so as to embed a │ +│ python file instead. │ +│ run Creates a local server to run the app on the path and port specified. │ +╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ +``` + +or, to run a pyscript app: + +```shell +>> pyscript run +Serving from /pyscript-example at port 8000. To stop, press Ctrl+C. +127.0.0.1 - - [30/Apr/2025 17:01:03] "GET / HTTP/1.1" 200 - +``` + ## Documentation ### Install the documentation dependencies From ac1483207e32745e17980b13895f28b24117bc4a Mon Sep 17 00:00:00 2001 From: Fabio Pliger Date: Wed, 30 Apr 2025 17:18:25 -0500 Subject: [PATCH 3/7] add section about how to create a new release --- CONTRIBUTING.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c7cf2b4..723bc49 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -123,3 +123,35 @@ e.g.: ```shell make -C docs html ``` + + +## Creating a New Release + +To create a new release of pyscript-cli, follow these steps: + +1. Update the version number in `src/pyscript/version` + +2. Update CHANGELOG.md with the changes since the last release + +3. Create a new git tag matching the version number: + ```shell + git tag X.Y.Z + ``` + +4. Push the tag to GitHub: + ```shell + git push origin X.Y.Z + ``` + +5. The GitHub Actions workflow will automatically: + - Verify the tag matches the version in `src/pyscript/version` + - Run tests + - Build and publish the package to PyPI + - Create a GitHub release + +6. Verify the new version is available on PyPI: https://pypi.org/project/pyscript-cli/ + +Note: Make sure all tests pass locally before creating a new release. The release workflow will fail if there are any test failures or version mismatches. + +Note 2: The version number in `src/pyscript/version` and the tag pushed to git (`X.Y.Z` in the example above) MUST MATCH! If they don't match the, the +action to create and publish the release won't start. From 32b979c5215ed6a12ef947f9444446e6e11cab4b Mon Sep 17 00:00:00 2001 From: Fabio Pliger Date: Wed, 30 Apr 2025 17:18:43 -0500 Subject: [PATCH 4/7] add section about how the release process works --- CONTRIBUTING.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 723bc49..300f73a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -155,3 +155,28 @@ Note: Make sure all tests pass locally before creating a new release. The releas Note 2: The version number in `src/pyscript/version` and the tag pushed to git (`X.Y.Z` in the example above) MUST MATCH! If they don't match the, the action to create and publish the release won't start. + + +### How the Release Process Works + +The release process is automated through GitHub Actions workflows. Here's what happens behind the scenes: + +1. When a new tag is pushed, it triggers the release workflow +2. The workflow first checks that: + - The tag name matches the version in `src/pyscript/version` + - All tests pass successfully + +3. If checks pass, the workflow: + - Builds the Python package using setuptools + - Creates source and wheel distributions + - Uploads the distributions to PyPI using twine + - Creates a GitHub release with the tag name + +4. The version check is performed by the `check_tag_version()` function in setup.py, which: + - Reads the version from `src/pyscript/version` + - Compares it to the git tag that triggered the workflow + - Fails if they don't match exactly + +5. The PyPI upload uses credentials stored as GitHub repository secrets + +This automated process ensures consistent and reliable releases while preventing common issues like version mismatches or failed tests from being published. From da49eab417c946b771d30df588ba54bedf64ad05 Mon Sep 17 00:00:00 2001 From: Fabio Pliger Date: Tue, 6 May 2025 15:05:43 -0500 Subject: [PATCH 5/7] fix mispellings (enviroment and avaible) --- CONTRIBUTING.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 300f73a..f465c2a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -14,7 +14,7 @@ git clone https://github.com/pyscript/pyscript.git pip install --upgrade pip ``` -Create a local enviroment with your enviroment manager of choice. +Create a local environment with your environment manager of choice. ### Virtualenv @@ -36,7 +36,7 @@ conda activate pyscript-cli ### Installation -Now that you have your environment set up and activated, install your local enviroment dependencies +Now that you have your environment set up and activated, install your local environment dependencies ```shell pip install -e ".[dev]" @@ -48,7 +48,7 @@ It is now possible to normally use the CLI. For more information on how to use i ## Run the tests -After setting up your developer enviroment, you can run the tests with the following command from the root directory: +After setting up your developer environment, you can run the tests with the following command from the root directory: ```shell pytest . @@ -56,7 +56,7 @@ pytest . # Running CLI Commands -Once the installation process is done, the `pyscript` CLI is avaible to be used once the environment has been +Once the installation process is done, the `pyscript` CLI is available to be used once the environment has been activated. Simply run `pyscript` with the appropriate command. For instance, to see the list of commands: ```shell From 70de3511e6f1a3230e7fd6e187e175657007e666 Mon Sep 17 00:00:00 2001 From: Fabio Pliger Date: Tue, 6 May 2025 15:33:08 -0500 Subject: [PATCH 6/7] pin the python version when creating the dev environment --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f465c2a..19e11af 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -30,7 +30,7 @@ source .venv/bin/activate In case you choose to use conda, use the following commands: ```shell -conda create -n pyscript-cli python +conda create -n pyscript-cli python=3.13 conda activate pyscript-cli ``` From 9e50f530f04ecac96c7590514c290ccfd552859b Mon Sep 17 00:00:00 2001 From: Fabio Pliger Date: Tue, 6 May 2025 15:39:15 -0500 Subject: [PATCH 7/7] add note on how to build the package whell locally --- CONTRIBUTING.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 19e11af..6ca1fd7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -180,3 +180,6 @@ The release process is automated through GitHub Actions workflows. Here's what h 5. The PyPI upload uses credentials stored as GitHub repository secrets This automated process ensures consistent and reliable releases while preventing common issues like version mismatches or failed tests from being published. + +NOTE: If you wanna build locally, run `CHECK_VERSION=False python -m build`. This will skip the check tag version conditions defined in `setup.py`, allowing +to create the wheel locally, without having a tag with a version matching the `src/pyscript/version` file.