From db375673d3a0f4d6f3ff8cdf773db856011fbca3 Mon Sep 17 00:00:00 2001 From: Gabriel Barbosa Soares Date: Thu, 5 Sep 2024 09:41:18 +0100 Subject: [PATCH] add: new development.md using rye --- docs/DEVELOPMENT.md | 158 +++++++++++++++++++++++++------------------- 1 file changed, 89 insertions(+), 69 deletions(-) diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md index 74befdf..859789e 100644 --- a/docs/DEVELOPMENT.md +++ b/docs/DEVELOPMENT.md @@ -1,93 +1,113 @@ # Development Guide -This guide provides instructions for setting up a local development environment for the Mann Kendall Automated (MKA) project. +This guide provides instructions for setting up a local development environment for the Mann Kendall Automated (MKA) project using rye, a modern Python packaging and project management tool. ## Prerequisites -1. Ensure Python is installed on your system. You can verify the installation by running the following command in your terminal: - ```bash - python --version - ``` -2. Ensure Git is installed on your system. You can verify the installation by running the following command in your terminal: - ```bash - git --version - ``` - -## Steps to Set Up the Local Development Environment - -1. Clone the MKA repository to your local machine using the command: - ```bash - git clone https://github.com/gabrielclimb/mann_kendall_automated.git - ``` -2. Navigate to the cloned repository directory: - ```bash - cd mann_kendall_automated - ``` -3. Install `virtualenv` using pip, Python's package installer: - ```bash - pip install virtualenv - ``` -4. Create a virtual environment in the project directory: - ```bash - virtualenv .venv - ``` -5. Activate the virtual environment: - - On Unix or MacOS, run: - ```bash - source .venv/bin/activate - ``` - - On Windows, run: - ```bash - .venv\Scripts\activate - ``` -6. Install the dependencies required for MKA: - ```bash - pip install -r dev-requirements.txt - ``` - -## Pre-commit setup +1. Python: Ensure Python is installed on your system. Verify the installation with: + ```bash + python --version + ``` -1. Install pre-commit: - ```bash - pip install pre-commit - ``` -2. Set up the git hook scripts: - ```bash - pre-commit install - ``` +2. Git: Make sure Git is installed. Verify with: + ```bash + git --version + ``` -This will add the pre-commit script to your `.git/hooks/pre-commit` directory. +3. Rye: Install rye by following the instructions in the [rye documentation](https://rye-up.com/guide/installation/). -## Makefile Usage +## Setting Up the Development Environment -The `Makefile` in the MKA repository contains a set of directives used to running linting checks and tests. +1. Clone the MKA repository: + ```bash + git clone https://github.com/gabrielclimb/mann_kendall_automated.git + cd mann_kendall_automated + ``` -### Linting +2. Set up the project environment and install dependencies: + ```bash + rye sync + ``` + This command creates a virtual environment, installs all project dependencies, and creates a lock file if it doesn't exist. -Linting refers to the process of analyzing source code to flag programming errors, bugs, stylistic errors, and suspicious constructs. This process helps in maintaining code consistency and avoiding potential issues that might come up during runtime. +## Development Workflow -In the context of this project, the `lint` command is used to run pre-commit checks on all files. This includes checks for code formatting, import order, type hinting, and more, depending on the hooks configured in your `.pre-commit-config.yaml`. +Rye provides several commands to manage your project: -You can run the linting checks with the command: +1. Add a new dependency: + ```bash + rye add + ``` -```bash -make lint -``` -This command runs pre-commit run --all-files, which executes all pre-commit hooks against all the files. +2. Add a development dependency: + ```bash + rye add --dev + ``` + +3. Update dependencies: + ```bash + rye sync + ``` -### Testing -Testing is a crucial part of software development. It's a process where the code is executed in a controlled environment to ascertain its correctness. +4. Run the Streamlit app: + ```bash + rye run stream + ``` -In this project, the test command is used to run the test suite using pytest, a testing framework for Python that allows you to easily create small, simple tests, yet scales to support complex functional testing. +5. Run tests: + ```bash + rye run test + ``` -The command to run the tests is: +6. Update requirements.txt: + ```bash + rye run req + ``` + +## Pre-commit Setup + +1. Install pre-commit: + ```bash + rye add --dev pre-commit + ``` + +2. Set up the git hook scripts: + ```bash + pre-commit install + ``` +## Linting + +Run linting checks with: +```bash +rye run lint +``` +This executes all pre-commit hooks against all files. + +## Testing + +Run the test suite with: ```bash -make test +rye run test ``` +This runs pytest, clears the cache before running tests, and measures code coverage of the source code in the src directory. -This command runs pytest --cache-clear --cov=src src/tests/, which clears the cache (--cache-clear) before running the tests, and also measures code coverage (--cov=src) of the source code in the src directory. The tests themselves are located in the src/tests/ directory. +## Project Structure + +- `src/`: Contains the main source code +- `tests/`: Contains test files +- `pyproject.toml`: Defines project metadata and dependencies +- `.pre-commit-config.yaml`: Configures pre-commit hooks + +## Best Practices + +1. Always use `rye run` to execute scripts defined in `pyproject.toml`. +2. Keep `pyproject.toml` up to date with all project dependencies. +3. Run linting and tests before committing changes. +4. Use pre-commit hooks to maintain code quality. ## Conclusion -Now, you have a local development environment set up for the MKA project. You can start contributing to the project by creating new features or fixing bugs. Please ensure to follow the coding standards defined in the project and make use of the pre-commit checks to maintain the code quality. +You now have a local development environment set up for the MKA project using rye. Start contributing by creating new features or fixing bugs. Ensure you follow the project's coding standards and use pre-commit checks to maintain code quality. + +For any questions or issues, please refer to the project's issue tracker on GitHub.