From 7424242da39d86f6f03a576d079d865ea7c5eeac Mon Sep 17 00:00:00 2001 From: Terrence Dorsey Date: Fri, 4 Feb 2022 15:56:33 -0500 Subject: [PATCH 1/7] Correct instruction to install latest version. --- docs/getting-started/installation.md | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md index c014ffd821b6..a951550766ad 100644 --- a/docs/getting-started/installation.md +++ b/docs/getting-started/installation.md @@ -2,27 +2,26 @@ ## Python setup -Prefect requires Python 3.7+ +Prefect requires Python 3.7 or later. We recommend installing Orion using a Python virtual environment manager such as `pipenv`, `conda` or `virtualenv`. ## Installing the latest version -Prefect is published as a Python package. To install the latest 2.0 release, run the following in a shell, using the pre-release version of Orion you want to test: +Prefect is published as a Python package. To install the latest 2.0 alpha release, run the following in a shell: ```bash -pip install -U "prefect>=" +pip install -U "prefect>=2.0a" ``` -For example, to install the latest 2.0a6 version: +To install a specific version, specify the version: ```bash -pip install -U "prefect>=2.0a6" +pip install -U "prefect=2.0a9" ``` Find the available release versions in the [Orion Release Notes](https://github.com/PrefectHQ/prefect/blob/orion/RELEASE-NOTES.md) or the [PyPI release history](https://pypi.org/project/prefect/#history). - ## Installing the bleeding edge If you'd like to test with the most up-to-date code, you can install directly off the `orion` branch on GitHub: @@ -36,8 +35,8 @@ pip install git+https://github.com/PrefectHQ/prefect@orion ## Installing for development -If you'd like to install a version of Prefect for development, first clone the Prefect repository -and then install in editable mode with `pip`: +If you'd like to install a version of Prefect for development, first clone the Prefect repository, check out the `orion` branch, +then install in editable mode with `pip`: ```bash git clone https://github.com/PrefectHQ/prefect.git @@ -54,13 +53,12 @@ To check that Prefect was installed correctly, you can test the Prefect CLI:
``` $ prefect version -2.0a6 +2.0a9 ```
Running this command should print a familiar looking version string to your console. - ## External requirements While Prefect Orion works with many of your favorite tools and Python modules, Orion has a few external dependencies. From 299d4ba680255ad24fd6f45468ddffd13d2acffe Mon Sep 17 00:00:00 2001 From: Terrence Dorsey Date: Mon, 7 Feb 2022 13:51:20 -0500 Subject: [PATCH 2/7] Add database reset/upgrade instructions. --- docs/getting-started/installation.md | 31 +++++++++++++++++++++++++++- 1 file changed, 30 insertions(+), 1 deletion(-) diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md index a951550766ad..64d61639e161 100644 --- a/docs/getting-started/installation.md +++ b/docs/getting-started/installation.md @@ -14,7 +14,7 @@ Prefect is published as a Python package. To install the latest 2.0 alpha releas pip install -U "prefect>=2.0a" ``` -To install a specific version, specify the version: +To install a specific version, specify the version, such as: ```bash pip install -U "prefect=2.0a9" @@ -59,6 +59,35 @@ $ prefect version Running this command should print a familiar looking version string to your console. +## Upgrading the database + +Upgrading from Prefect version 2.0a9 or earlier requires resetting the Prefect Orion database. + +With the additions of migrations to Prefect Orion, if you if install a version later than 2.0a9, but had an existing db from before, you'll need to do one of the following processes: + +* Delete and rebuild the database +* Stamp and reset the database + +### Delete the database file + +Delete the database file `~/.prefect/orion.db`. + +Prefect Orion automatically creates a new database on the next write. + +### Reset the database manually + +Use the Prefect CLI to stamp the database revision table: + +```bash +prefect orion database stamp +``` + +Using the CLI, reset the database: + +```bash +prefect orion database reset +``` + ## External requirements While Prefect Orion works with many of your favorite tools and Python modules, Orion has a few external dependencies. From 66f12b6f68d979696ffd709f3e1c6830dd2f4b37 Mon Sep 17 00:00:00 2001 From: Terrence Dorsey Date: Mon, 7 Feb 2022 15:52:23 -0500 Subject: [PATCH 3/7] Minor edits. --- docs/getting-started/installation.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md index 64d61639e161..84212c9dcf5a 100644 --- a/docs/getting-started/installation.md +++ b/docs/getting-started/installation.md @@ -79,13 +79,13 @@ Prefect Orion automatically creates a new database on the next write. Use the Prefect CLI to stamp the database revision table: ```bash -prefect orion database stamp +$ prefect orion database stamp ``` Using the CLI, reset the database: ```bash -prefect orion database reset +$ prefect orion database reset ``` ## External requirements From e1d9d302fbcb6b0baa38371395041c43768185c9 Mon Sep 17 00:00:00 2001 From: Terrence Dorsey Date: Mon, 7 Feb 2022 19:36:56 -0500 Subject: [PATCH 4/7] Update docs/getting-started/installation.md Co-authored-by: Michael Adkins --- docs/getting-started/installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md index 84212c9dcf5a..11bb34028a4f 100644 --- a/docs/getting-started/installation.md +++ b/docs/getting-started/installation.md @@ -17,7 +17,7 @@ pip install -U "prefect>=2.0a" To install a specific version, specify the version, such as: ```bash -pip install -U "prefect=2.0a9" +pip install -U "prefect==2.0a9" ``` Find the available release versions in the [Orion Release Notes](https://github.com/PrefectHQ/prefect/blob/orion/RELEASE-NOTES.md) or the [PyPI release history](https://pypi.org/project/prefect/#history). From b2c0ef315f458417b925701784108a4abffb5b27 Mon Sep 17 00:00:00 2001 From: Terrence Dorsey Date: Mon, 7 Feb 2022 19:37:25 -0500 Subject: [PATCH 5/7] Update docs/getting-started/installation.md Co-authored-by: Michael Adkins --- docs/getting-started/installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md index 11bb34028a4f..9da472eff5cb 100644 --- a/docs/getting-started/installation.md +++ b/docs/getting-started/installation.md @@ -63,7 +63,7 @@ Running this command should print a familiar looking version string to your cons Upgrading from Prefect version 2.0a9 or earlier requires resetting the Prefect Orion database. -With the additions of migrations to Prefect Orion, if you if install a version later than 2.0a9, but had an existing db from before, you'll need to do one of the following processes: +Prior to 2.0a10, Orion did not have database migrations and required a hard reset of the database between versions. Now that migrations have been added, your database will be automatically upgraded with each version change. However, you must still perform a hard reset of the database if you are upgrading from 2.0a9 or earlier. * Delete and rebuild the database * Stamp and reset the database From 557305ab92e21b9f40ed5f11c09ab8973ce39ac2 Mon Sep 17 00:00:00 2001 From: Terrence Dorsey Date: Mon, 7 Feb 2022 20:06:45 -0500 Subject: [PATCH 6/7] Revisions based on feedback. --- docs/getting-started/installation.md | 37 +++++++++------------------- 1 file changed, 12 insertions(+), 25 deletions(-) diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md index 9da472eff5cb..afc3499c797b 100644 --- a/docs/getting-started/installation.md +++ b/docs/getting-started/installation.md @@ -36,16 +36,20 @@ pip install git+https://github.com/PrefectHQ/prefect@orion ## Installing for development If you'd like to install a version of Prefect for development, first clone the Prefect repository, check out the `orion` branch, -then install in editable mode with `pip`: +and install an editable version of the Python package: ```bash -git clone https://github.com/PrefectHQ/prefect.git -# or git clone git@github.com:PrefectHQ/prefect.git if SSH is preferred -cd prefect/ +# Clone the repository and switch to the 'orion' branch +git clone https://github.com/PrefectHQ/prefect.git git checkout orion +# Install the package with development dependencies pip install -e ".[dev]" +# Setup pre-commit hooks for required formatting +pre-commit install ``` +See our [Contributing](/contributing/overview/) guide for more details about standards and practices for contributing to Prefect. + ## Checking your installation To check that Prefect was installed correctly, you can test the Prefect CLI: @@ -63,30 +67,13 @@ Running this command should print a familiar looking version string to your cons Upgrading from Prefect version 2.0a9 or earlier requires resetting the Prefect Orion database. -Prior to 2.0a10, Orion did not have database migrations and required a hard reset of the database between versions. Now that migrations have been added, your database will be automatically upgraded with each version change. However, you must still perform a hard reset of the database if you are upgrading from 2.0a9 or earlier. - -* Delete and rebuild the database -* Stamp and reset the database - -### Delete the database file +Prior to 2.0a10, Orion did not have database migrations and required a hard reset of the database between versions. Now that migrations have been added, your database will be upgraded automatically with each version change. However, you must still perform a hard reset of the database if you are upgrading from 2.0a9 or earlier. Resetting the database by using the CLI command `prefect orion database reset` does not upgrade the database from 2.0a9 or earlier. -Delete the database file `~/.prefect/orion.db`. +To upgrade the database, delete the database file `~/.prefect/orion.db`. Prefect Orion automatically creates a new database on the next write. -Prefect Orion automatically creates a new database on the next write. +!!! warning "Resetting the database deletes data" -### Reset the database manually - -Use the Prefect CLI to stamp the database revision table: - -```bash -$ prefect orion database stamp -``` - -Using the CLI, reset the database: - -```bash -$ prefect orion database reset -``` + Note that resetting the database causes the loss of any existing data. ## External requirements From b874cfa024c3c26f57a7595581582c7349ed7f67 Mon Sep 17 00:00:00 2001 From: Terrence Dorsey Date: Tue, 8 Feb 2022 11:30:07 -0500 Subject: [PATCH 7/7] Update docs/getting-started/installation.md Co-authored-by: Michael Adkins --- docs/getting-started/installation.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md index afc3499c797b..3e06db62ab43 100644 --- a/docs/getting-started/installation.md +++ b/docs/getting-started/installation.md @@ -67,9 +67,9 @@ Running this command should print a familiar looking version string to your cons Upgrading from Prefect version 2.0a9 or earlier requires resetting the Prefect Orion database. -Prior to 2.0a10, Orion did not have database migrations and required a hard reset of the database between versions. Now that migrations have been added, your database will be upgraded automatically with each version change. However, you must still perform a hard reset of the database if you are upgrading from 2.0a9 or earlier. Resetting the database by using the CLI command `prefect orion database reset` does not upgrade the database from 2.0a9 or earlier. +Prior to 2.0a10, Orion did not have database migrations and required a hard reset of the database between versions. Now that migrations have been added, your database will be upgraded automatically with each version change. However, you must still perform a hard reset of the database if you are upgrading from 2.0a9 or earlier. -To upgrade the database, delete the database file `~/.prefect/orion.db`. Prefect Orion automatically creates a new database on the next write. +Resetting the database with the CLI command `prefect orion database reset` is not compatible a database from 2.0a9 or earlier. Instead, delete the database file `~/.prefect/orion.db`. Prefect Orion automatically creates a new database on the next write. !!! warning "Resetting the database deletes data"