fe7f18a5c4
- Add more detailed instructions for development workflow - Clarify type stub generation process - Add troubleshooting section - Add clean_examples.py utility script - Improve formatting and organization Co-Authored-By: Alek Petuskey <alek@reflex.dev>
157 lines
5.2 KiB
Markdown
157 lines
5.2 KiB
Markdown
# Reflex Contributing Guidelines
|
|
|
|
For an extensive guide on the different ways to contribute to Reflex see our [Contributing Guide on Notion](https://www.notion.so/reflex-dev/2107ab2bc166497db951b8d742748284?v=f0eaff78fa984b5ab15d204af58907d7).
|
|
|
|
## Running a Local Build of Reflex
|
|
|
|
Here is a quick guide on how to run Reflex repo locally so you can start contributing to the project.
|
|
|
|
**Prerequisites:**
|
|
|
|
- Python >= 3.9
|
|
- Poetry version >= 1.4.0 and add it to your path (see [Poetry Docs](https://python-poetry.org/docs/#installation) for more info).
|
|
|
|
**1. Fork this repository:**
|
|
Fork this repository by clicking on the `Fork` button on the top right.
|
|
|
|
**2. Clone Reflex and navigate into the repo:**
|
|
|
|
``` bash
|
|
git clone https://github.com/<YOUR-USERNAME>/reflex.git
|
|
cd reflex
|
|
```
|
|
|
|
**3. Install your local Reflex build:**
|
|
|
|
``` bash
|
|
poetry install
|
|
```
|
|
|
|
**4. Create an examples directory within the repository:**
|
|
|
|
The examples directory is used for testing your local changes. It's included in `.gitignore` so your test apps won't be committed.
|
|
|
|
``` bash
|
|
mkdir examples
|
|
cd examples
|
|
```
|
|
|
|
**5. Init and Run:**
|
|
|
|
Initialize a new Reflex app and run it in development mode:
|
|
|
|
``` bash
|
|
poetry run reflex init # Select option 0 for blank template
|
|
poetry run reflex run # Add --frontend-only for faster frontend-only development
|
|
```
|
|
|
|
The development server will start and your app will be available at http://localhost:3000. The server will automatically reload when you make changes to your code.
|
|
|
|
**Note:** In development mode, the server may occasionally need to be restarted when making significant changes. You can use Ctrl+C to stop the server and run it again.
|
|
|
|
To clean up your examples directory and start fresh, you can use the provided cleanup script:
|
|
```bash
|
|
poetry run python scripts/clean_examples.py
|
|
```
|
|
|
|
## 🧪 Testing and QA
|
|
|
|
Any feature or significant change added should be accompanied with unit tests.
|
|
|
|
Within the 'test' directory of Reflex you can add to a test file already there or create a new test python file if it doesn't fit into the existing layout.
|
|
|
|
#### What to unit test?
|
|
|
|
- Any feature or significant change that has been added.
|
|
- Any edge cases or potential problem areas.
|
|
- Any interactions between different parts of the code.
|
|
|
|
## ✅ Making a PR
|
|
|
|
Once you solve a current issue or improvement to Reflex, you can make a PR, and we will review the changes.
|
|
|
|
Before submitting a pull request, ensure the following steps are taken and tests are passing:
|
|
|
|
1. Run unit tests and coverage checks:
|
|
``` bash
|
|
poetry run pytest tests/units --cov --no-cov-on-fail --cov-report=
|
|
```
|
|
This will fail if code coverage is below 70%.
|
|
|
|
2. Run code quality checks:
|
|
``` bash
|
|
poetry run ruff check .
|
|
poetry run pyright reflex tests
|
|
find reflex tests -name "*.py" -not -path reflex/reflex.py | xargs poetry run darglint
|
|
```
|
|
|
|
3. Format your code:
|
|
``` bash
|
|
poetry run ruff format .
|
|
```
|
|
|
|
4. Install and run pre-commit hooks:
|
|
Consider installing git pre-commit hooks so Ruff, Pyright, Darglint and `make_pyi` will run automatically before each commit.
|
|
Note that pre-commit will only be installed when you use a Python version >= 3.9.
|
|
|
|
``` bash
|
|
pre-commit install
|
|
```
|
|
|
|
You can also run the pre-commit checks manually:
|
|
```bash
|
|
pre-commit run --all-files
|
|
```
|
|
|
|
## Type Stub Generation
|
|
|
|
When adding new components or modifying existing ones, you need to regenerate the type stub files (.pyi). This ensures proper type checking and IDE support.
|
|
|
|
To generate type stubs:
|
|
```bash
|
|
poetry run python scripts/make_pyi.py
|
|
```
|
|
|
|
After running this command:
|
|
1. Check `git status` to see if any .pyi files were modified
|
|
2. If changes were made, include them in your commit
|
|
3. If no changes were made, your types are up to date
|
|
|
|
## Editing Templates
|
|
|
|
To edit the templates in Reflex you can do so in two ways:
|
|
|
|
1. Change to the basic `blank` template can be done in the `reflex/.templates/apps/blank` directory.
|
|
|
|
2. Other templates can be edited in their own repository. For example the `sidebar` template can be found in the [`reflex-sidebar`](https://github.com/reflex-dev/sidebar-template) repository.
|
|
|
|
|
|
## Troubleshooting
|
|
|
|
Common issues and their solutions:
|
|
|
|
1. **Development Server Issues**
|
|
- If the development server becomes unresponsive, stop it with Ctrl+C and restart
|
|
- For frontend-only changes, use `--frontend-only` flag for faster development
|
|
- Clear the examples directory using `scripts/clean_examples.py` if you encounter unexplained issues
|
|
|
|
2. **Pre-commit Hook Failures**
|
|
- Run `pre-commit run --all-files` to identify specific issues
|
|
- Ensure you've formatted code with `ruff format .` before committing
|
|
- Check that type stubs are up to date with `make_pyi.py`
|
|
|
|
3. **Type Checking Errors**
|
|
- Verify your changes haven't broken type definitions
|
|
- Regenerate type stubs if you modified components
|
|
- Check the error messages from pyright for specific type issues
|
|
|
|
## Other Notes
|
|
|
|
For some pull requests when adding new components you will have to generate a pyi file for the new component. This is done by running the following command in the `reflex` directory.
|
|
|
|
(Please check in with the team before adding a new component to Reflex we are cautious about adding new components to Reflex's core.)
|
|
|
|
``` bash
|
|
poetry run python scripts/make_pyi.py
|
|
```
|