From 0b51afce6acace2de358120dae365f190719cd05 Mon Sep 17 00:00:00 2001 From: Daniel Biehl Date: Tue, 3 Jun 2025 19:39:56 +0200 Subject: [PATCH 01/91] feat(debugger): update delayed logging handling for Robot Framework 7.3 compatibility closes #457 --- .../src/robotcode/debugger/debugger.py | 57 +++++++++++-------- 1 file changed, 34 insertions(+), 23 deletions(-) diff --git a/packages/debugger/src/robotcode/debugger/debugger.py b/packages/debugger/src/robotcode/debugger/debugger.py index d09f684c..12544c1c 100644 --- a/packages/debugger/src/robotcode/debugger/debugger.py +++ b/packages/debugger/src/robotcode/debugger/debugger.py @@ -1781,29 +1781,40 @@ def run_kw() -> Any: result = None if len(test.body): - for kw in test.body: - with LOGGER.delayed_logging: - try: - result = self._run_keyword(kw, evaluate_context) - except (SystemExit, KeyboardInterrupt): - raise - except BaseException as e: - result = e - break - finally: - if get_robot_version() <= (7, 2): - messages = LOGGER._log_message_cache or [] - for msg in messages or (): - # hack to get and evaluate log level - listener: Any = next(iter(LOGGER), None) - if listener is None or self.check_message_is_logged(listener, msg): - self.log_message( - { - "level": msg.level, - "message": msg.message, - "timestamp": msg.timestamp, - } - ) + if get_robot_version() >= (7, 3): + for kw in test.body: + with evaluate_context.output.delayed_logging: + try: + result = self._run_keyword(kw, evaluate_context) + except (SystemExit, KeyboardInterrupt): + raise + except BaseException as e: + result = e + break + else: + for kw in test.body: + with LOGGER.delayed_logging: + try: + result = self._run_keyword(kw, evaluate_context) + except (SystemExit, KeyboardInterrupt): + raise + except BaseException as e: + result = e + break + finally: + if get_robot_version() <= (7, 2): + messages = LOGGER._log_message_cache or [] + for msg in messages or (): + # hack to get and evaluate log level + listener: Any = next(iter(LOGGER), None) + if listener is None or self.check_message_is_logged(listener, msg): + self.log_message( + { + "level": msg.level, + "message": msg.message, + "timestamp": msg.timestamp, + } + ) return result result = self.run_in_robot_thread(run_kw) From b23331b8622ddd97c2030de96212323f5e7d4171 Mon Sep 17 00:00:00 2001 From: Daniel Biehl Date: Thu, 5 Jun 2025 13:39:31 +0200 Subject: [PATCH 02/91] docs(contributing): enhance development setup and workflow instructions Updated the contributing guide to include detailed development environment setup options, IDE configuration, and a comprehensive development workflow. Improved clarity and added troubleshooting tips for common issues. --- CONTRIBUTING.md | 439 +++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 418 insertions(+), 21 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 05109c96..e9554b82 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,12 +5,12 @@ First off, thanks for taking the time to contribute! ❤️ All types of contributions are encouraged and valued. See the [Table of Contents](#table-of-contents) for different ways to help and details about how this project handles them. Please make sure to read the relevant section before making your contribution. It will make it a lot easier for us maintainers and smooth out the experience for all involved. The community looks forward to your contributions. 🎉 -> And if you like the project, but just don't have time to contribute, that's fine. There are other easy ways to support the project and show your appreciation, which we would also be very happy about: -> - Star the project -> - Tweet about it -> - Refer this project in your project's readme -> - Mention the project at local meetups and tell your friends/colleagues -> - Sponsor this project by clicking on the sponsor button on the project page +And if you like the project, but just don't have time to contribute, that's fine. There are other easy ways to support the project and show your appreciation, which we would also be very happy about: +- Star the project +- Tweet about it +- Refer this project in your project's readme +- Mention the project at local meetups and tell your friends/colleagues +- Sponsor this project by clicking on the sponsor button on the project page ## Table of Contents @@ -21,6 +21,15 @@ All types of contributions are encouraged and valued. See the [Table of Contents - [Reporting Bugs](#reporting-bugs) - [Suggesting Enhancements](#suggesting-enhancements) - [Your First Code Contribution](#your-first-code-contribution) + - [Development Environment Setup](#development-environment-setup) + - [IDE Configuration](#ide-configuration) + - [Development Workflow](#development-workflow) + - [Pull Request Guidelines](#pull-request-guidelines) + - [Running Tests](#running-tests) + - [Building the Project](#building-the-project) + - [Additional Development Commands](#additional-development-commands) + - [Troubleshooting Development Setup](#troubleshooting-development-setup) + - [Development Tools & Code Generation](#development-tools--code-generation) - [Improving The Documentation](#improving-the-documentation) - [Styleguides](#styleguides) - [Commit Messages](#commit-messages) @@ -37,7 +46,7 @@ to . ## I Have a Question -> If you want to ask a question, we assume that you have read the available [Documentation](https://robotcode.io). +If you want to ask a question, we assume that you have read the available [Documentation](https://robotcode.io). Before you ask a question, it is best to search for existing [Issues](https://github.com/robotcodedev/robotcode/issues) that might help you. In case you have found a suitable issue and still need clarification, you can write your question in this issue. It is also advisable to search the internet for answers first. @@ -80,7 +89,9 @@ A good bug report shouldn't leave others needing to chase you up for more inform - Make sure that you are using the latest version. - Determine if your bug is really a bug and not an error on your side e.g. using incompatible environment components/versions (Make sure that you have read the [documentation](https://robotcode.io). If you are looking for support, you might want to check [this section](#i-have-a-question)). -- To see if other users have experienced (and potentially already solved) the same issue you are having, check if there is not already a bug report existing for your bug or error in the [bug tracker](https://github.com/robotcodedev/robotcodeissues?q=label%3Abug). +- To see if other users have experienced (and potentially already solved) the same issue you are having, check if there is not already a bug report existing for your bug or error in the [bug tracker](https://github.com/robotcodedev/robotcode/issues?q=label%3Abug). +- Look or ask in the [Robot Framework Slack](https://robotframework.slack.com) in the channel [#vscode](https://robotframework.slack.com/archives/C0103745J7P) or in the [Robot Framework Forum](https://forum.robotframework.org) in the [Tools/Visual Studio Code(ium)](https://forum.robotframework.org/c/tools/vscode/28) category to see if other users have experienced (and potentially already solved) the same issue you are having. + - for questions about the intellj plugin there are also channels for pycharm - Also make sure to search the internet (including Stack Overflow) to see if users outside of the GitHub community have discussed the issue. - Collect information about the bug: - Stack trace (Traceback) @@ -137,33 +148,419 @@ Enhancement suggestions are tracked as [GitHub issues](https://github.com/robotc ### Your First Code Contribution - +Welcome to your first code contribution! Here's how to set up your development environment and get started. + +#### Development Environment Setup + +**Option 1: Using GitHub Codespaces (Easiest)** + +The quickest way to get started without any local setup: + +1. **Setup:** + - Go to the [robotcode repository](https://github.com/robotcodedev/robotcode) + - Click the green "Code" button + - Select "Codespaces" tab + - Click "Create codespace on main" + - Wait for the codespace to initialize (this uses the same dev container configuration) + +GitHub Codespaces provides a full VS Code environment in your browser with all dependencies pre-installed. + +**Option 2: Using Dev Container (Local)** + +For local development with containers: + +1. **Prerequisites:** + - Install [Docker](https://www.docker.com/get-started) + - Install [Visual Studio Code](https://code.visualstudio.com/) + - Install the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) + +2. **Setup:** + - Clone the repository: `git clone https://github.com/robotcodedev/robotcode.git` + - Open the project in VS Code + - When prompted, click "Reopen in Container" or use the Command Palette (`Cmd+Shift+P` / `Ctrl+Shift+P`) and select "Dev Containers: Reopen in Container" + - The container will automatically install all dependencies including Python, Node.js, and required packages + +**Option 3: Local Development** + +If you prefer to set up locally: + +1. **Prerequisites:** + - Python 3.8+ (system Python is fine) + - Node.js 16+ + - Git + +2. **Setup:** + ```bash + git clone https://github.com/robotcodedev/robotcode.git + cd robotcode + + # Install Hatch (choose one method): + # Option A: Using system package manager (if available) + # Ubuntu/Debian: sudo apt install hatch + # Fedora: sudo dnf install hatch + # Arch: sudo pacman -S hatch + + # Option B: Using pipx (recommended if not in package manager) + pip install pipx + pipx install hatch + + # Option C: Check https://hatch.pypa.io/latest/install/ for other methods + + # Create development environment + hatch env create devel + + # install needed packages for the vscode and intellij packaging + hatch run build:install-bundled-editable -TODO... + # Install Node.js dependencies + npm install --also-dev + ``` + +#### IDE Configuration + +The project includes VS Code settings optimized for development: +- Python testing with pytest +- Code formatting with Prettier and Ruff +- Type checking with mypy +- Debugging configuration +- Recommended extensions are automatically suggested + +**Important: Python Interpreter Selection** + +After setting up the development environment with `hatch env create devel`, you need to select the correct Python interpreter in VS Code: + +1. Open the Command Palette (`Cmd+Shift+P` or `Ctrl+Shift+P` or `F1`) +2. Type "Python: Select Interpreter" +3. Choose the interpreter from the Hatch environment +4. Select the desired Python/Robot Framework version environment + +Hatch creates separate Python environments for each supported Python/Robot Framework version combination in your system's cache directory. + +You can also check available environments with: `hatch env show` + +#### Development Workflow + +1. **Create a branch:** `git checkout -b feature/your-feature-name` +2. **Make your changes** following the project's coding standards +3. **Run tests:** `hatch run devel.py312-rf73:test` (single combination for faster development) +4. **Run linting:** `hatch run lint:all` (or use the VS Code task) +5. **Fix linting issues:** `hatch run lint:style` for formatting +6. **Commit your changes** with a descriptive commit message +7. **Push and create a pull request** + +#### Pull Request Guidelines + +Before submitting your pull request: + +1. **Ensure all tests pass:** Run `hatch run test.rf73:test` (or your preferred combination) +2. **Check linting:** Run `hatch run lint:all` and fix any issues +3. **Write descriptive PR description:** + - Explain what changes you made and why + - Reference any related issues + - Include screenshots for UI changes + - List any breaking changes +4. **Keep PRs focused:** One feature/fix per PR when possible +5. **Update documentation:** Include relevant documentation updates +6. **Sign your commits:** All commits must be signed (see [Signed Commits](#signed-commits-required)) + +**PR Review Process:** +- Automated checks must pass (tests, linting, etc.) +- At least one maintainer review is required +- Address any feedback promptly +- Keep your PR up to date with the main branch + +#### Running Tests + +**Basic Test Execution:** +- Use VS Code's built-in test runner (Testing tab in the sidebar) +- Or run from terminal: `hatch run test` (⚠️ **Warning**: This runs tests against ALL Python/Robot Framework combinations in the matrix - can take a very long time!) +- Run specific tests: `hatch run test tests/specific_test.py` (also runs against all matrix combinations) + +**Testing with Specific Python/Robot Framework Versions:** + +The project supports multiple Python and Robot Framework versions. You can run tests against specific combinations: + +```bash +# Run tests with specific Robot Framework versions (single combination) +hatch run test:test # ⚠️ Runs ALL matrix combinations (RF 4.1-7.3) +hatch run test.rf70:test # Robot Framework 7.0.x +hatch run test.rf71:test # Robot Framework 7.1.x +hatch run test.rf72:test # Robot Framework 7.2.x +hatch run test.rf73:test # Robot Framework 7.3.x (recommended for development) +hatch run test.rf61:test # Robot Framework 6.1.x +hatch run test.rf60:test # Robot Framework 6.0.x +hatch run test.rf50:test # Robot Framework 5.0.x +hatch run test.rf41:test # Robot Framework 4.1.x + +# Run tests in specific development environments (single combination) +hatch run devel:test # ⚠️ Runs ALL matrix combinations (Python 3.8-3.13 × RF 4.1-7.3) +hatch run devel.py39-rf73:test # Python 3.9 with Robot Framework 7.3.x (single combination) +hatch run devel.py311-rf70:test # Python 3.11 with Robot Framework 7.0.x (single combination) +hatch run devel.py312-rf73:test # Python 3.12 with Robot Framework 7.3.x (single combination) +hatch run devel.py313-rf73:test # Python 3.13 with Robot Framework 7.3.x (single combination) + +# Test against development versions of Robot Framework +hatch run rfbeta:test # Robot Framework beta/RC versions +hatch run rfmaster:test # Robot Framework master branch +hatch run rfdevel:test # Local Robot Framework development version +``` + +**⚠️ Important Matrix Behavior:** +- `hatch run test` executes tests for **all combinations** in the matrix (48 combinations: 6 Python versions × 8 RF versions) +- `hatch run devel:test` also runs **all matrix combinations** +- For faster development, use specific combinations like `hatch run devel.py312-rf73:test` +- For CI/full testing, use the matrix commands + +**Available Environment Matrix:** +- **Python versions**: 3.8, 3.9, 3.10, 3.11, 3.12, 3.13 +- **Robot Framework versions**: 4.1.x, 5.0.x, 6.0.x, 6.1.x, 7.0.x, 7.1.x, 7.2.x, 7.3.x + +#### Building the Project + +- Package for distribution: `hatch run build:package` + +#### Additional Development Commands + +**Code Quality & Linting:** +- Type checking: `hatch run lint:typing` +- Code style check and formatting: `hatch run lint:style` +- Run all linting checks: `hatch run lint:all` + +**Project Maintenance & Code Generation:** +- Generate Robot Framework syntax files: `hatch run generate-tmlanguage` +- Create JSON schema for robot.toml: `hatch run create-json-schema` +- Generate Robot Framework options: `hatch run generate-rf-options` +- Install bundled packages in editable mode: `hatch run build:install-bundled-editable` + +**Release & Documentation:** +- Update changelog: `hatch run build:update-changelog` +- Update git versions: `hatch run build:update-git-versions` +- Bump version: `hatch run build:bump [major|minor|patch]` +- Package for distribution: `hatch run build:package` +- Publish to PyPI, VS Code Marketplace, etc.: `hatch run build:publish` + - you need the specific credentials set up in your environment for this to work + +#### Troubleshooting Development Setup + +**Common Issues:** + +1. **Hatch environment creation fails:** + ```bash + # Clear Hatch cache and try again + hatch env prune + hatch env create devel + ``` + +2. **VS Code doesn't find the Python interpreter:** + - Use `hatch env find devel` to get the exact path + - Manually select the interpreter in VS Code using this path + +3. **Tests fail with import errors:** + - Ensure you're in the correct hatch environment + - Run `hatch run build:install-bundled-editable` to install development packages + +4. **Node.js dependencies issues:** + ```bash + # Clean and reinstall npm dependencies + rm -rf node_modules package-lock.json + npm install --also-dev + ``` + +#### Development Tools & Code Generation + +The robotcode project includes several development tools and code generation scripts: + +**Syntax & Language Support:** +- `hatch run generate-tmlanguage` - Regenerate VS Code syntax highlighting files for Robot Framework +- `hatch run create-json-schema` - Create JSON schema for robot.toml configuration validation +- `hatch run generate-rf-options` - Generate Robot Framework command-line options documentation + +**Maintenance & Release Tools:** +- `hatch run build:update-changelog` - Update project changelog +- `hatch run build:update-git-versions` - Update version information from git +- `hatch run build:update-doc-links` - Update documentation links +- `hatch run build:bump [major|minor|patch]` - Bump project version using semantic versioning + +These tools are typically used by maintainers, but contributors might need some of them when working on specific features (e.g., syntax highlighting changes require `generate-tmlanguage`). ### Improving The Documentation - +Documentation is crucial for helping users understand and use robotcode effectively. Here are ways you can help improve it: + +#### Types of Documentation Contributions + +1. **User Documentation** (`docs/` folder) + - Getting started guides + - Feature explanations + - Configuration examples + - Troubleshooting guides + +2. **Code Documentation** + - Docstrings for classes and functions + - Inline comments for complex logic + - Type hints and annotations + +3. **README Updates** + - Installation instructions + - Quick start examples + - Feature highlights + +#### Documentation Setup + +The documentation is built using modern web technologies and is located in the `docs/` folder: -TODO ... +```bash +cd docs +npm install +npm run dev # Start development server at http://localhost:3000 +npm run build # Build for production +npm run preview # Preview production build +``` + +#### Documentation Standards + +- **Clear and concise:** Write for users of all skill levels +- **Examples:** Include practical code examples +- **Screenshots:** Add visual aids where helpful (stored in `docs/images/`) +- **Links:** Reference related concepts and external resources +- **Testing:** Verify that code examples actually work + +#### Making Documentation Changes + +1. **Small fixes:** Edit files directly and submit a pull request +2. **Major changes:** Open an issue first to discuss the approach +3. **New sections:** Follow the existing structure in the `docs/` folder +4. **Images:** Store in `docs/images/` and use relative paths + +#### Documentation Review Process + +- All documentation changes go through the same review process as code +- Maintainers will check for accuracy, clarity, and consistency +- Community feedback is encouraged on documentation pull requests ## Styleguides ### Commit Messages - +Good commit messages help maintain a clean project history and make it easier to understand changes. Please follow these guidelines: + +#### Format + +``` +(): + + + +