diff --git a/docs/contribute/dev-contribute.mdx b/docs/contribute/dev-contribute.mdx index 52cfd22c77a1..a61f8d632d73 100644 --- a/docs/contribute/dev-contribute.mdx +++ b/docs/contribute/dev-contribute.mdx @@ -1,83 +1,82 @@ --- -title: Install for development -description: Learn how to set up Prefect for development and experimentation. +title: Develop on Prefect +description: Learn how to set up Prefect for development, experimentation and code contributions. --- -## Develop Prefect docs +import fork from '/snippets/fork.mdx' -We use [Mintlify](https://mintlify.com/) to host and build the Prefect documentation. -The main branch of the [prefecthq/prefect](https://github.com/PrefectHQ/prefect) GitHub repository is used to build the Prefect 3.0rc docs at [docs-3.prefect.io](https://docs-3.prefect.io) temporarily. +## Make a code contribution -The 2.x docs are hosted at [docs.prefect.io](https://docs.prefect.io) and built from the 2.x branch of prefecthq/prefect. +We welcome all forms of contributions to Prefect, whether it's small typo fixes in [our documentation](/contribute/docs-contribute), bug fixes or feature enhancements! +If this is your first time making an open source contribution we will be glad to work with you and help you get up to speed. -Make sure you have a recent version of Node.js installed. -We recommend using [nvm](https://github.com/nvm-sh/nvm) to manage Node.js versions. + +For small changes such as typo fixes you can simply open a pull request - we typically review small changes like these within the day. +For larger changes including all bug fixes, we ask that you first open [an issue](https://github.com/PrefectHQ/prefect/issues) or comment on the issue that you are planning to work on. + -1. Clone this repository. -2. Run `cd docs` to navigate to the docs directory. -3. Run `nvm use node` to use the correct Node.js version. -4. Run `npm i -g mintlify` to install Mintlify. -5. Run `mintlify dev` to start the development server. +## Fork the repository + -Your docs should now be available at `http://localhost:3000`. - -See the [Mintlify documentation](https://mintlify.com/docs/development) for more information on how install Mintlify, build previews, and use Mintlify's features while writing docs. - -`.mdx` files are Markdown files that can contain JavaScript and React components. - -## Develop Prefect source code - -### Step 1: Download the source code and install an editable copy of the Prefect Python package: +## Install Prefect for development +Once you have cloned your fork of the repo: ```bash # Clone the repository -git clone https://github.com/PrefectHQ/prefect.git +git clone https://github.com/GITHUB-USERNAME/prefect.git cd prefect +``` +you can install [an editable version](https://setuptools.pypa.io/en/latest/userguide/development_mode.html) of Prefect for quick iteration. +We recommend using a virtual environment such as `venv`: -# We recommend using a virtual environment. Below we use venv - +```bash python -m venv .venv source .venv/bin/activate -# Install the package with development dependencies - +# Installs the package with development dependencies pip install -e ".[dev]" ``` -### Step 2: Set up pre-commit hooks for required formatting +To ensure your changes comply with our linting policies, you can optionally set up pre-commit hooks to run with every commit: ``` pre-commit install ``` -If you don't want to install the pre-commit hooks, manually install the formatting dependencies with: +If you don't want to install the pre-commit hooks, you can manually install the linting utilities and run them yourself: ```bash pip install $(./scripts/precommit-versions.py) -``` -Run `ruff check` and `ruff format`. +ruff check +ruff format +``` -### Step 3: Run the test suite +## Write tests -After installation, you can run the test suite with `pytest`: +Prefect relies on unit testing to ensure proposed changes don't negatively impact any functionality. +For all code changes, including bug fixes, we ask that you write at least one corresponding test. +One rule of thumb - especially for bug fixes - is that you should write a test that fails prior to your changes and passes with your changes. +This ensures the test will fail and prevent the bug from resurfacing if other changes are made in the future. +All tests can be found in the `tests/` directory of the repository. -Run all tests: +You can run the test suite with `pytest`: ```bash +# run all tests pytest tests -``` - -Run a subset of tests -```bash +# run a specific file pytest tests/test_flows.py + +# run all tests that match a pattern +pytest -k 'tasks' ``` -### Build the Prefect UI +## Working with a development UI -If you intend to run a local Prefect server during development, first build the UI. +If you plan to use the UI during development, you will need to build a development version of the UI first. Using the Prefect UI in development requires installation of [npm](https://github.com/npm/cli). We recommend using [nvm](https://github.com/nvm-sh/nvm) to manage Node.js versions. @@ -89,13 +88,31 @@ Start a development UI that reloads on code changes: prefect dev ui ``` -Build the static UI (the UI served by `prefect server start`): +This command is most useful if you are working directly on the UI codebase. + +Alternatively, you can build a static UI that will be served when running `prefect server start`: ```bash prefect dev build-ui ``` -### Add database migrations +## Working with a development server + +The Prefect CLI provides several helpful commands to aid development of server-side changes. + +You can start all services with hot-reloading on code changes (note that this requires installation of UI dependencies): + +```bash +prefect dev start +``` + +Start a Prefect API that reloads on code changes: + +```bash +prefect dev api +``` + +## Add database migrations If your code changes necessitate modifications to a database table, first update the SQLAlchemy model in `src/prefect/server/database/orm_models.py`. @@ -149,20 +166,4 @@ prefect server database upgrade -y ``` After successfully creating migrations for all database types, update `MIGRATION-NOTES.md` to -document the changes. - -### Developer tooling - -The Prefect CLI provides several helpful commands to aid development. - -Start all services with hot-reloading on code changes (requires installation of UI dependencies): - -```bash -prefect dev start -``` - -Start a Prefect API that reloads on code changes: - -```bash -prefect dev api -``` \ No newline at end of file +document the changes. \ No newline at end of file diff --git a/docs/contribute/docs-contribute.mdx b/docs/contribute/docs-contribute.mdx new file mode 100644 index 000000000000..4cc78c5d1b2d --- /dev/null +++ b/docs/contribute/docs-contribute.mdx @@ -0,0 +1,34 @@ +--- +title: Contribute to documentation +description: Learn how to contribute to the Prefect docs. +--- + +import fork from '/snippets/fork.mdx' + + +We use [Mintlify](https://mintlify.com/) to host and build the Prefect documentation. + +The main branch of the [prefecthq/prefect](https://github.com/PrefectHQ/prefect) GitHub repository is used to build the Prefect 3.0rc docs at [docs-3.prefect.io](https://docs-3.prefect.io). + +The 2.x docs are hosted at [docs-2.prefect.io](https://docs-2.prefect.io) and built from the 2.x branch of the repository. + +## Fork the repository + + + +## Setup your local environment + +Make sure you have a recent version of Node.js installed. +We recommend using [nvm](https://github.com/nvm-sh/nvm) to manage Node.js versions. + +1. Clone this repository. +2. Run `cd docs` to navigate to the docs directory. +3. Run `nvm use node` to use the correct Node.js version. +4. Run `npm i -g mintlify` to install Mintlify. +5. Run `mintlify dev` to start the development server. + +Your docs should now be available at `http://localhost:3000`. + +See the [Mintlify documentation](https://mintlify.com/docs/development) for more information on how install Mintlify, build previews, and use Mintlify's features while writing docs. + +All documentation is written in `.mdx` files, which are Markdown files that can contain JavaScript and React components. diff --git a/docs/contribute/index.mdx b/docs/contribute/index.mdx index 907e651368ae..b4f07471428e 100644 --- a/docs/contribute/index.mdx +++ b/docs/contribute/index.mdx @@ -1,20 +1,22 @@ --- title: Contribute sidebarTitle: Overview -description: Join the community, improve Prefect, and share integrations +description: Join the community, improve Prefect, and share knowledge mode: "wide" --- +We welcome all forms of engagement, and love to learn from our users. There are many ways to get involved with the Prefect community: - Join nearly 30,000 engineers in the [Prefect Slack community](https://prefect.io/slack) - [Give Prefect a ⭐️ on GitHub](https://github.com/PrefectHQ/prefect) -- [Contribute](/contribute/dev-contribute) to Prefect's open source libraries -- [Contribute integrations](/contribute/contribute-integrations) to the community +- Make a contribution to [Prefect's documentation](/contribute/docs-contribute) +- Make a code contribution to [Prefect's open source libraries](/contribute/dev-contribute) +- Support or create a new [Prefect integration](/contribute/contribute-integrations) ## Report an issue -To report a bug, make a feature request, and more, visit our [Issues page on GitHub](https://github.com/PrefectHQ/prefect/issues/new/choose). +To report a bug, make a feature request, and more, visit our [issues page on GitHub](https://github.com/PrefectHQ/prefect/issues/new/choose). ## Code of conduct diff --git a/docs/contribute/styles-practices.mdx b/docs/contribute/styles-practices.mdx index 69dcab8eb7ec..50d76b100fba 100644 --- a/docs/contribute/styles-practices.mdx +++ b/docs/contribute/styles-practices.mdx @@ -1,5 +1,5 @@ --- -title: Styles and practices +title: Code and development style guide --- Generally, we follow the [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html). diff --git a/docs/mint.json b/docs/mint.json index 15fa8a34ae35..3b46d02de904 100644 --- a/docs/mint.json +++ b/docs/mint.json @@ -680,10 +680,10 @@ "group": "Contribute", "pages": [ "contribute/index", + "contribute/docs-contribute", "contribute/dev-contribute", - "contribute/styles-practices", - "contribute/develop-a-new-worker-type", "contribute/contribute-integrations", + "contribute/styles-practices", "contribute/code-of-conduct" ] } diff --git a/docs/snippets/fork.mdx b/docs/snippets/fork.mdx new file mode 100644 index 000000000000..2e2d145758ac --- /dev/null +++ b/docs/snippets/fork.mdx @@ -0,0 +1,6 @@ +All contributions to Prefect need to start on [a fork of the repository](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo). +Once you have successfully forked [the Prefect repo](https://github.com/PrefectHQ/prefect), create a branch with an informative name: +``` +git checkout -b fix-for-issue-NUM +``` +After committing your changes to this branch, you can then open a pull request from your fork that we will review with you. \ No newline at end of file