Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
145 lines (95 loc) · 5.52 KB

CONTRIBUTING.md

File metadata and controls

145 lines (95 loc) · 5.52 KB

Contributing to ZenML VSCode Extension

We appreciate your interest in contributing to the ZenML VSCode extension! This guide will help you get started with setting up your development environment, making changes, and proposing those changes back to the project. By following these guidelines, you'll ensure a smooth and efficient contribution process.

Setting Up Your Development Environment

  1. Fork and Clone: Fork the zenml-io/vscode-zenml repository and clone it to your local machine.
git clone https://github.com/YOUR_USERNAME/vscode-zenml.git
git checkout develop
  1. Install Dependencies: Navigate to the cloned repository directory and install the required dependencies.
cd vscode-zenml
npm install
  1. Compile the Project: Build the TypeScript source code into JavaScript.
npm run compile

Python Environment Setup

The extension's Python functionality requires setting up a corresponding Python environment.

  1. Create and activate a Python virtual environment using Python 3.8 or greater. (e.g., python -m venv .venv on Windows, or python3 -m venv .venv on Unix-based systems).
  2. Install nox for environment management.
python -m pip install nox
  1. Use nox to set up the environment.
nox --session setup
  1. Install any Python dependencies specified in requirements.txt.
pip install -r requirements.txt

Development Workflow

  • Running the Extension: Press F5 to open a new VSCode window with the extension running, or click the Start Debugging button in the VSCode menubar under the Run menu.
  • Making Changes: Edit the source code. The TypeScript code is in the src directory, and Python logic for the LSP server is in bundled/tool.

Testing

  • Writing Tests: Add tests in the src/test directory. Follow the naming convention *.test.ts for test files.
  • Running Tests: Use the provided npm scripts to compile and run tests.
npm run test

Debugging

  • VSCode Debug Console: Utilize the debug console in the VSCode development window for troubleshooting and inspecting values.
  • Extension Host Logs: Review the extension host logs for runtime errors or unexpected behavior.

Spellchecking

The project uses typos for spellchecking with a standardized configuration. Run the spellcheck script with the following command:

./scripts/spellcheck.sh

The script automatically uses the repository's default config file .typos.toml in the root of the repository. Custom configurations are not supported to ensure consistent spell checking across all contributions. All arguments passed to the script (except -c/--config) are forwarded directly to typos.

Formatting and Linting

We use automatic formatting and linting tools to keep our code consistent.

Quick Commands

Task Command What it does
Format everything ./scripts/format.sh Formats all Python, TypeScript, JSON, and YAML files
Lint everything ./scripts/lint.sh Checks all files for style/quality issues

Individual Tools

  • Python: ruff for formatting/linting, mypy for type checking
  • TypeScript/JSON: prettier for formatting, eslint for linting
  • YAML: yamlfix for formatting and checking

NPM Scripts

For frontend code only:

  • npm run format - Format TypeScript and JSON files
  • npm run lint - Lint TypeScript files

Please run these commands before submitting your PR.

Contributing Changes

  1. Create a Branch: Make your changes in a new git branch based on the develop branch.
git checkout -b feature/your-feature-name
  1. Commit Your Changes: Write clear, concise commit messages following the conventional commit guidelines.
  2. Push to Your Fork: Push your branch to your fork on GitHub.
git push origin feature/your-feature-name
  1. Open a Pull Request: Go to the original zenml-io/vscode-zenml repository and create a pull request from your feature branch. Please follow our contribution guidelines for more details on proposing pull requests.

Troubleshooting Common Issues

  • Ensure all dependencies are up to date and compatible.
  • Rebuild the project (npm run compile) after making changes.
  • Reset your development environment if encountering persistent issues by re-running nox setup commands and reinstalling dependencies.
  • You can also run the scripts/clear_and_compile.sh script, which will delete the cache, dist folder, and recompile automatically.
  • Check the ZenML documentation and GitHub issues for common problems and solutions.

Release Process

For maintainers who need to publish new versions of the extension, please refer to our detailed Release Process Guide. This document covers:

  • Testing release workflows before publishing
  • Creating and tagging new releases
  • Publishing to the VS Code Marketplace
  • Troubleshooting common release issues

Additional Resources